API Documentation

The Aegis Algorithm API provides AI-powered trade compliance tools — HS code classification, ECCN export control classification, sanctions screening, duty calculation, and RAG knowledge base querying.

Base URL: https://api.aegisalgorithm.com

API Version: v1

Authentication

All API requests require a Bearer token in the Authorization header. Obtain your token via the /auth/login or /auth/signup endpoints.

// Example request with Bearer token
curl -X POST https://api.aegisalgorithm.com/api/v1/classify \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"product_name":"Laptop","product_description":"..."}'

Rate Limiting

Requests are limited to 100 per 60 seconds per IP address. When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Header	Description
`X-Request-ID`	Unique identifier for each request (returned in response)
`Retry-After`	Seconds to wait before retrying (on 429)
`X-RateLimit-Remaining`	Remaining requests in the current window

Error Handling

The API uses standard HTTP status codes and returns JSON error bodies:

{
  "detail": "Invalid or expired token"
}

Code	Meaning
`200`	Success
`400`	Bad request — check your input parameters
`401`	Unauthorized — missing or invalid token
`409`	Conflict — resource already exists (e.g., duplicate email)
`429`	Too many requests — rate limit exceeded
`500`	Internal server error

HS Code Classification

AI-powered product classification into HS codes using GRI rules. Returns TOP-3 candidates with confidence scores, reasoning chains, and relevant trade history.

POST/api/v1/classify

Request Body

Field	Type	Required	Description
`product_name`	string	✅	Product name (1–500 chars)
`product_description`	string	✅	Detailed product description (5–2000 chars)
`material`	string	—	Material composition
`usage`	string	—	Intended use
`origin_country`	string	—	ISO 2-letter origin country code
`destination_country`	string	—	ISO 2-letter destination country code

// Request
curl -X POST https://api.aegisalgorithm.com/api/v1/classify \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "product_name": "Bluetooth Wireless Earbuds",
  "product_description": "True wireless stereo earbuds with ANC and charging case",
  "material": "ABS plastic, lithium-ion battery",
  "usage": "Personal audio listening",
  "origin_country": "CN",
  "destination_country": "US"
}'

// Response (200)
{
  "candidates": [
    {
      "code": "8518.30.2000",
      "description": "Bluetooth wireless earbuds/headphones",
      "confidence": 0.92,
      "reasoning": "GRI 1: Heading 8518 covers headphones..."
    }
  ],
  "suggested_code": "8518.30.2000",
  "confidence": 0.92,
  "processing_time_ms": 1234
}

POST/api/v1/classify/batch

Classify up to 10 products in a single request. Each item uses the same schema as the single classification endpoint.

curl -X POST .../api/v1/classify/batch \
  -d '[{"product_name":"Laptop","product_description":"..."},{"product_name":"Phone","product_description":"..."}]'

ECCN Classification

AI-powered ECCN (Export Control Classification Number) classification following the CCL methodology. Returns TOP-3 candidates with license determinations, EAR99 detection, and Reasons for Control.

POST/api/v1/classify/eccn

Field	Type	Description
`product_name`	string ✅	Product name (1–500 chars)
`product_description`	string ✅	Detailed description including technical nature
`technical_parameters`	string	Processing power, frequency, etc.
`encryption_capable`	boolean	Has encryption/info-security functionality?
`encryption_strength`	string	Algorithm & key length (e.g. AES-256)
`end_user_type`	string	commercial / government / military / academic
`destination_country`	string	ISO 2-letter code

// Response (200)
{
  "suggested_eccn": "3A991",
  "is_ear99": false,
  "license_determination": "NLR (No License Required)",
  "candidates": [{
    "eccn": "3A991",
    "confidence": 0.91,
    "license_required": false,
    "reason_for_control": "AT (Anti-Terrorism)"
  }]
}

POST/api/v1/classify/eccn/batch

Classify up to 10 products for ECCN in a single request.

Sanctions Screening

POST/api/v1/screen

Screen an entity against OFAC, BIS, EU, and UN sanctions lists with AI false-positive reduction.

curl -X POST .../api/v1/screen \
  -d '{
  "entity_name": "Global Trade LLC",
  "entity_type": "company",
  "country": "AE"
}'

// Response
{
  "entity_name": "Global Trade LLC",
  "match_count": 0,
  "overall_risk": "low"
}

POST/api/v1/screen/batch

Screen up to 100 entities in a single request.

Trade Data Search

GET/api/v1/trade-data/search

Search historical import/export records by HS code, country, product description, or trade flow.

Param	Description
`q`	Keyword search (product description)
`hs_code`	HS code prefix search
`origin_country`	Origin country filter
`destination_country`	Destination country filter
`trade_flow`	export / import
`limit`	Max results (default 20)

curl "https://api.aegisalgorithm.com/api/v1/trade-data/search?q=bluetooth&limit=5"

RAG Knowledge Query

POST/api/v1/rag/query

Query the export control knowledge base using RAG (Retrieval-Augmented Generation). Returns AI-generated answers with cited sources.

curl -X POST .../api/v1/rag/query \
  -H "Authorization: Bearer <token>" \
  -d '{"question": "What is the de minimis rule under EAR?", "top_k": 5}'

Health Check

GET/health

Returns service health status with database connectivity check.

{
  "status": "healthy",
  "database": "connected",
  "environment": "production"
}

GET/api/v1/db/stats

Returns record counts across all database tables for monitoring.