Width — API Documentation

Authentication

All API calls (except /v1/register) require an API key passed via the X-API-Key header.

HTTP Header

X-API-Key: your-uuid-api-key

Get a key instantly at /register or via POST /v1/register.

Registration Flow

1. Register (get a UUID key) → 2. Use key in headers → 3. Optionally upgrade tier for higher limits.

POST/v1/register NO AUTH

Register a new API key. No authentication required. Returns your key immediately.

name	string *	Your name or company name
email	string	Email (optional). Providing one upgrades to 500/day tier.

curl example

# Register (no email = 300/day free tier)
curl -X POST http://localhost:8899/v1/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp"}'

# Register with email (500/day email tier)
curl -X POST http://localhost:8899/v1/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "email": "compliance@acme.com"}'

Response

{
  "api_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme Corp",
  "email": "compliance@acme.com",
  "tier": "email",
  "daily_limit": 500,
  "status": "active",
  "created_at": "2026-03-30T12:00:00+00:00"
}

Screening API

Submit a name for full KYC due diligence. The screening runs asynchronously (40-120s). Poll for results.

POST/v1/screening API KEY

Submit a KYC screening task. Returns task ID immediately, runs in background.

name	string *	Primary name (Chinese or English)
country	string	ISO code (CN, SG, HK, JP, KR, TH, AE, US, UK) — targeted source selection
industry	string	"crypto", "banking", "insurance", etc. — industry-specific sources
aliases	string[]	Additional name variants, e.g. ["CZ", "Changpeng Zhao"]
context	string	Background for disambiguation ("Founder of Binance...")
threshold	float	Fuzzy match minimum (default 0.3)

curl example

curl -X POST http://localhost:8899/v1/screening \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "name": "赵长鹏",
    "country": "CN",
    "industry": "crypto",
    "aliases": ["CZ", "Changpeng Zhao"],
    "context": "Founder of Binance, world largest crypto exchange"
  }'

Response (immediate)

{
  "id": "ee508b37-1234-5678-abcd-ef1234567890",
  "status": "processing",
  "query": "赵长鹏"
}

GET/v1/screening/{id} API KEY

Poll screening status and result. Call every 3-5 seconds until status != "processing".

status	string	"processing" \| "completed" \| "failed"
result.decision	string	APPROVE \| ENHANCED_REVIEW \| EDD \| MANDATORY_EDD \| REJECT
result.risk_level	string	none \| low \| medium \| high \| severe
result.decision_reasons	string[]	Human-readable audit trail of decision logic
result.risk_level_reasons	string[]	Factors contributing to risk level
result.sanctions	object	{hit: bool, triggers: [{type, entity, similarity, detail}]}
result.pep	object	{hit: bool, triggers: [{entity, detail: [{position, jurisdiction}]}]}
result.convicted	object	{hit: bool, triggers: [{entity, detail}]}
result.adverse_media	object	{hit: bool, triggers: [{entity, count, max_severity, entries}]}
result.relationships	object	{hit: bool, triggers: [{entity, relationship, risk}]}
result.live_news	object	{articles: [{headline, source, date, severity, url, verified}]}

curl example — poll

curl -H "X-API-Key: YOUR_KEY" \
  http://localhost:8899/v1/screening/ee508b37-1234-5678-abcd-ef1234567890

Response (completed)

{
  "id": "ee508b37-...",
  "status": "completed",
  "query": "赵长鹏",
  "result": {
    "decision": "EDD",
    "decision_label": "Enhanced Due Diligence Required",
    "risk_level": "high",
    "sanctions": { "hit": false, "triggers": [] },
    "pep": { "hit": false, "triggers": [] },
    "convicted": { "hit": true, "triggers": [...] },
    "adverse_media": { "hit": true, "triggers": [...] },
    "live_news": { "articles": [...] },
    "decision_reasons": ["Criminal record: conviction on record", ...],
    "risk_level_reasons": ["HIGH adverse media severity", ...]
  }
}

GET/v1/screening/{id}/report API KEY

Get a formatted Markdown screening report. Content-Type: text/markdown. Only available when status is "completed".

curl example

curl -H "X-API-Key: YOUR_KEY" \
  http://localhost:8899/v1/screening/ee508b37-.../report

Search & Entity API

Direct access to the intelligence database. Useful for building your own UI or pre-checking before full screening.

GET/v1/search?q={name}&limit=20&threshold=0.3 API KEY

Fuzzy name search against 206K+ entities. CJK: exact + substring matching. Latin: pg_trgm similarity.

q	string *	Search query (name)
limit	int	Max results (default 20, max 100)
threshold	float	Fuzzy similarity threshold (default 0.3)

curl example

curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:8899/v1/search?q=Putin&limit=5"

GET/v1/entity/{id} API KEY

Full entity profile by UUID. Includes all names, sanctions entries, PEP positions, adverse media, relationships.

curl example

curl -H "X-API-Key: YOUR_KEY" \
  http://localhost:8899/v1/entity/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Account Management

Upgrade your tier and check usage. All endpoints require your API key.

POST/v1/account/bind-email API KEY

Bind an email address to upgrade from Free (300/day) to Email tier (500/day).

email

string *

Email address to bind

curl example

curl -X POST http://localhost:8899/v1/account/bind-email \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"email": "compliance@acme.com"}'

POST/v1/account/survey API KEY

Complete a short survey to upgrade to Survey tier (1000/day). Must have email tier first.

answers

object

Survey answers (freeform key-value)

curl example

curl -X POST http://localhost:8899/v1/account/survey \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"answers": {"use_case": "compliance", "company_size": "50-200"}}'

GET/v1/account/usage API KEY

Check current daily usage, remaining quota, tier, and status.

curl example

curl -H "X-API-Key: YOUR_KEY" \
  http://localhost:8899/v1/account/usage

Response

{
  "used_today": 42,
  "daily_limit": 500,
  "remaining": 458,
  "tier": "email",
  "email": "compliance@acme.com",
  "status": "active"
}

Rate Limits

Each API key has a daily request limit based on its tier. When the limit is exceeded, you'll receive a 429 Too Many Requests response.

Tier	Daily Limit	Requirement
Free	300 / day	Name only
Email	500 / day	Provide email address
Survey	1,000 / day	Complete short survey

Every response includes rate limit headers:

Response Headers

X-RateLimit-Limit: 500       # Your daily limit
X-RateLimit-Remaining: 458   # Requests remaining today

When quota is exceeded:

429 Response

HTTP/1.1 429 Too Many Requests
Retry-After: 86400
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0

{
  "detail": "Daily quota exceeded (300/day). Upgrade at /register."
}

Quotas reset at midnight UTC. Upgrade your tier to increase limits.

Decision Hierarchy

The screening engine applies checks in priority order. The highest-priority match determines the final decision.

1

REJECTSanctioned entity or convicted criminal

2

MANDATORY_EDDPolitically Exposed Person (PEP)

3

EDDHIGH or SEVERE adverse media / live news

4

ENHANCED_REVIEWMEDIUM adverse media

5

APPROVENo risk indicators found

Error Responses

Status	Meaning	Action
`401`	Missing or invalid API key	Register at /register
`403`	API key suspended or banned	Contact admin
`404`	Screening task or entity not found	Check the UUID
`429`	Daily quota exceeded	Wait until UTC midnight or upgrade tier
`500`	Internal server error	Retry or report the issue

Error Response Format

{
  "detail": "Human-readable error message"
}