{"openapi":"3.1.0","info":{"title":"CustosHUB API","description":"B2B OFAC sanctions screening API with weighted multi-field matching, field-level explain, and audit logging.\n\n## Authentication\n- `X-API-Key` — required client API key on all screening endpoints\n- Missing or unknown key → 401 · disabled key → 403\n- `X-Admin-API-Key` — required for admin/sync/audit endpoints\n\n## Tracing\nPass `X-Request-ID` (UUID recommended) on every request. The same value is returned in the response header and JSON body.\n\n## Rate limits\nRate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (per minute); `X-RateLimit-Month-Limit`, `X-RateLimit-Month-Remaining`, `X-RateLimit-Month-Reset` (per month). On 429: `Retry-After` plus JSON body with `retry_after_seconds`. Tiers: Free $0 / 5k checks · Starter $39 / 50k · Business $149 / 250k · Enterprise custom.\n\nInteractive docs: `/docs` · OpenAPI schema: `/openapi.json`","version":"0.3.0"},"paths":{"/health":{"get":{"tags":["health"],"summary":"Liveness probe","operationId":"health_health_get","responses":{"200":{"description":"Service is running","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}}},"/api/v1/status":{"get":{"tags":["health"],"summary":"Service and sanctions list status","description":"Returns OFAC list counts, sync schedule, and readiness.","operationId":"api_status_api_v1_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}}}}},"/api/v1/auth/mode":{"get":{"tags":["auth"],"summary":"Active authentication mode","operationId":"auth_mode_api_v1_auth_mode_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Auth Mode Api V1 Auth Mode Get"}}}}}}},"/api/v1/auth/stub/login":{"post":{"tags":["auth"],"summary":"Dev login (no Google)","description":"Creates a local dev account and API key instantly. Used when AUTH_MODE=stub (default until Google OAuth is configured).","operationId":"stub_login_api_v1_auth_stub_login_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/auth/connect-key":{"post":{"tags":["auth"],"summary":"Connect an existing API key (disabled)","description":"Portal login by pasting an API key is no longer supported. Sign in with Google and manage keys under API Credentials.","operationId":"connect_api_key_api_v1_auth_connect_key_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectApiKeyRequest"}}},"required":true},"responses":{"410":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/google":{"get":{"tags":["auth"],"summary":"Start Google sign-in","description":"Redirects the browser to Google OAuth. Only Gmail / Google accounts.","operationId":"google_login_api_v1_auth_google_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/auth/session":{"get":{"tags":["auth"],"summary":"Current portal session","description":"Returns the signed-in Google user and API key metadata. Raw API key is shown once after registration.","operationId":"get_auth_session_api_v1_auth_session_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Auth Session Api V1 Auth Session Get"}}}}}}},"/api/v1/auth/session/api-key/ack":{"post":{"tags":["auth"],"summary":"Confirm API key was saved","description":"Marks the API key as revealed and clears the one-time bootstrap secret from the session.","operationId":"ack_api_key_saved_api_v1_auth_session_api_key_ack_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Ack Api Key Saved Api V1 Auth Session Api Key Ack Post"}}}}}}},"/api/v1/auth/logout":{"post":{"tags":["auth"],"summary":"Sign out","operationId":"logout_api_v1_auth_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Logout Api V1 Auth Logout Post"}}}}}}},"/api/v1/screen":{"post":{"tags":["screening"],"summary":"Screen a name or entity","description":"Screen against locally synchronized OFAC SDN and Consolidated lists. Returns weighted score, field-level explain, and `request_id` for support tracing. Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (per minute); `X-RateLimit-Month-Limit`, `X-RateLimit-Month-Remaining`, `X-RateLimit-Month-Reset` (per month). On 429: `Retry-After` plus JSON body with `retry_after_seconds`. Tiers: Free $0 / 5k checks · Starter $39 / 50k · Business $149 / 250k · Enterprise custom.","operationId":"screen_api_v1_screen_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Custos-Client","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Custos-Client"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenResponse"}}}},"400":{"description":"Invalid query","content":{"application/json":{"example":{"detail":"Fill at least one search field","request_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid API key"},"403":{"description":"Disabled API key"},"429":{"description":"Rate limit exceeded. Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (per minute); `X-RateLimit-Month-Limit`, `X-RateLimit-Month-Remaining`, `X-RateLimit-Month-Reset` (per month). On 429: `Retry-After` plus JSON body with `retry_after_seconds`. Tiers: Free $0 / 5k checks · Starter $39 / 50k · Business $149 / 250k · Enterprise custom."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/screen/batch":{"post":{"tags":["screening"],"summary":"Batch screen multiple queries","description":"Run up to `MAX_SCREEN_BATCH_SIZE` screening queries in one request. Each item counts as one rate-limit unit. Each item gets its own audit log entry.","operationId":"screen_batch_api_v1_screen_batch_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Custos-Client","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Custos-Client"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScreenRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ScreenResponse"},"title":"Response Screen Batch Api V1 Screen Batch Post"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"description":"Invalid API key"},"403":{"description":"Disabled API key"},"429":{"description":"Rate limit exceeded. Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (per minute); `X-RateLimit-Month-Limit`, `X-RateLimit-Month-Remaining`, `X-RateLimit-Month-Reset` (per month). On 429: `Retry-After` plus JSON body with `retry_after_seconds`. Tiers: Free $0 / 5k checks · Starter $39 / 50k · Business $149 / 250k · Enterprise custom."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/screen/batch/csv":{"post":{"tags":["screening"],"summary":"Batch screen from CSV upload","description":"Upload a CSV file with screening rows. Recognized columns: first_name, last_name, full_name, dob, country, passport, etc. Optional `webhook_url` form field for async result delivery.","operationId":"screen_batch_csv_api_v1_screen_batch_csv_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Custos-Client","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Custos-Client"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_screen_batch_csv_api_v1_screen_batch_csv_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ScreenResponse"},"title":"Response Screen Batch Csv Api V1 Screen Batch Csv Post"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"description":"Invalid API key"},"429":{"description":"Rate limit exceeded. Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (per minute); `X-RateLimit-Month-Limit`, `X-RateLimit-Month-Remaining`, `X-RateLimit-Month-Reset` (per month). On 429: `Retry-After` plus JSON body with `retry_after_seconds`. Tiers: Free $0 / 5k checks · Starter $39 / 50k · Business $149 / 250k · Enterprise custom."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/plans":{"get":{"tags":["account"],"summary":"List available subscription plans","description":"Public plan catalog with quotas and pricing. Paid plans are purchased via `/api/v1/billing/checkout`.","operationId":"list_plans_api_v1_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List Plans Api V1 Plans Get"}}}}}}},"/api/v1/signup":{"post":{"tags":["account"],"summary":"Create a new API key (self-service)","description":"Issue a new `ofac_…` API key for an allowed plan. The raw secret is returned once — store it securely.","operationId":"signup_api_v1_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}}}},"403":{"description":"Plan is not available for self-service signup"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/billing/plans":{"get":{"tags":["billing"],"summary":"Plan catalog with pricing","operationId":"billing_plans_api_v1_billing_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Billing Plans Api V1 Billing Plans Get"}}}}}}},"/api/v1/billing/checkout":{"post":{"tags":["billing"],"summary":"Start a plan purchase / upgrade","description":"Signed-in users only. Free plan activates instantly. Paid plans create an order and either return a Stripe checkout URL or wait for manual confirmation.","operationId":"create_checkout_api_v1_billing_checkout_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Create Checkout Api V1 Billing Checkout Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/billing/orders":{"get":{"tags":["billing"],"summary":"List your billing orders","operationId":"list_my_orders_api_v1_billing_orders_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List My Orders Api V1 Billing Orders Get"}}}}}}},"/api/v1/api/v1/admin/billing/orders":{"get":{"tags":["billing","admin"],"summary":"List billing orders (admin)","operationId":"admin_list_orders_api_v1_api_v1_admin_billing_orders_get","parameters":[{"name":"status_filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Filter"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Admin List Orders Api V1 Api V1 Admin Billing Orders Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/api/v1/admin/billing/orders/{order_id}/confirm":{"post":{"tags":["billing","admin"],"summary":"Manually confirm a paid order (admin)","description":"Marks a manual/bank-transfer order as paid and upgrades the user's key.","operationId":"admin_confirm_order_api_v1_api_v1_admin_billing_orders__order_id__confirm_post","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Admin Confirm Order Api V1 Api V1 Admin Billing Orders  Order Id  Confirm Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/api/v1/admin/billing/orders/{order_id}/cancel":{"post":{"tags":["billing","admin"],"summary":"Cancel a pending order (admin)","operationId":"admin_cancel_order_api_v1_api_v1_admin_billing_orders__order_id__cancel_post","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Admin Cancel Order Api V1 Api V1 Admin Billing Orders  Order Id  Cancel Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me":{"get":{"tags":["account"],"summary":"Current account and quota","operationId":"get_me_api_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeAccountResponse"}}}}}}},"/api/v1/me/stats":{"get":{"tags":["account"],"summary":"Dashboard statistics for today","operationId":"get_me_stats_api_v1_me_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeStatsResponse"}}}}}}},"/api/v1/me/audit":{"get":{"tags":["account"],"summary":"Search audit logs for your account","operationId":"get_me_audit_api_v1_me_audit_get","parameters":[{"name":"request_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditLogListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/audit/export":{"get":{"tags":["account"],"summary":"Export audit log as CSV or JSON","operationId":"export_me_audit_api_v1_me_audit_export_get","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|csv|pdf)$","default":"json","title":"Format"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50000,"minimum":1,"default":10000,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/audit/{request_id}/result":{"get":{"tags":["account"],"summary":"Full screening result for an audit entry","operationId":"get_me_audit_result_api_v1_me_audit__request_id__result_get","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditResultResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/api-keys":{"get":{"tags":["account"],"summary":"List API keys owned by this account","operationId":"list_my_api_keys_api_v1_me_api_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyListResponse"}}}}}},"post":{"tags":["account"],"summary":"Create an additional owned API key","operationId":"create_my_api_key_api_v1_me_api_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePortalApiKeyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/api-keys/import":{"post":{"tags":["account"],"summary":"Add someone else's API key for use (audit stays with the owner)","operationId":"import_api_key_api_v1_me_api_keys_import_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportApiKeyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyListItem"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/api-keys/import/{key_id}":{"delete":{"tags":["account"],"summary":"Remove an imported API key from your account (does not delete the key)","operationId":"unlink_imported_api_key_api_v1_me_api_keys_import__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Unlink Imported Api Key Api V1 Me Api Keys Import  Key Id  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/api-keys/{key_id}/secret":{"get":{"tags":["account"],"summary":"Reveal the raw secret for an owned API key","operationId":"reveal_my_api_key_secret_api_v1_me_api_keys__key_id__secret_get","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeySecretResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/api-keys/{key_id}/rotate":{"post":{"tags":["account"],"summary":"Rotate an owned API key (hard-deletes the old secret)","operationId":"rotate_owned_api_key_api_v1_me_api_keys__key_id__rotate_post","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/api-keys/{key_id}":{"delete":{"tags":["account"],"summary":"Hard-delete an owned API key","operationId":"delete_owned_api_key_api_v1_me_api_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Owned Api Key Api V1 Me Api Keys  Key Id  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/me/api-key/rotate":{"post":{"tags":["account"],"summary":"Rotate your primary API key","description":"Issues a new secret and hard-deletes the previous primary key. Shown once.","operationId":"rotate_my_api_key_api_v1_me_api_key_rotate_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}}}}}}},"/api/v1/me/api-key/disable":{"patch":{"tags":["account"],"summary":"Disable your primary API key","operationId":"disable_my_api_key_api_v1_me_api_key_disable_patch","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeAccountResponse"}}}}}}},"/api/v1/audit/{request_id}":{"get":{"tags":["admin"],"summary":"Lookup audit logs by request_id","description":"Support endpoint for tracing a screening call. Returns hashed query metadata only — no raw PII. Requires `X-Admin-API-Key`.","operationId":"get_audit_by_request_id_api_v1_audit__request_id__get","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Audit By Request Id Api V1 Audit  Request Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/api-keys":{"post":{"tags":["admin"],"summary":"Create API key","description":"Generate a new client API key for the given plan. The raw `api_key` is returned once — store it securely.","operationId":"create_api_key_api_v1_admin_api_keys_post","parameters":[{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["admin"],"summary":"List API keys","description":"List all API keys (hashed ids only — no raw secrets).","operationId":"list_api_keys_api_v1_admin_api_keys_get","parameters":[{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyPublicResponse"},"title":"Response List Api Keys Api V1 Admin Api Keys Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/api-keys/{key_id}":{"patch":{"tags":["admin"],"summary":"Update API key plan or status","description":"Manually assign a plan (e.g. enterprise) or enable/disable a client key. At least one of `plan` or `enabled` must be provided.","operationId":"update_api_key_api_v1_admin_api_keys__key_id__patch","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUpdateApiKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyPublicResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["admin"],"summary":"Permanently delete an API key","description":"Hard-delete the key, all linked portal users and sessions, rate-limit usage, and matching audit logs. Not reversible.","operationId":"delete_api_key_api_v1_admin_api_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/api-keys/{key_id}/enable":{"patch":{"tags":["admin"],"summary":"Enable API key","operationId":"enable_api_key_api_v1_admin_api_keys__key_id__enable_patch","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyPublicResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/api-keys/{key_id}/disable":{"patch":{"tags":["admin"],"summary":"Disable API key","operationId":"disable_api_key_api_v1_admin_api_keys__key_id__disable_patch","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyPublicResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/api-keys/{key_id}/rotate":{"patch":{"tags":["admin"],"summary":"Rotate API key","description":"Issue a new secret for the same plan/limits, disable the old key. Usage counters do not transfer. Raw key shown once.","operationId":"rotate_api_key_api_v1_admin_api_keys__key_id__rotate_patch","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyRotateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/dashboard":{"get":{"tags":["admin"],"summary":"Admin dashboard metrics","operationId":"admin_dashboard_api_v1_admin_dashboard_get","parameters":[{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminDashboardResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/clients":{"get":{"tags":["admin"],"summary":"List registered clients","operationId":"list_clients_api_v1_admin_clients_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AdminClientItem"},"title":"Response List Clients Api V1 Admin Clients Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/clients/{user_id}":{"delete":{"tags":["admin"],"summary":"Permanently delete a client","description":"Hard-delete the portal user and sessions. If no other account shares the API key, the key, rate-limit rows, and matching audit logs are also removed.","operationId":"delete_client_api_v1_admin_clients__user_id__delete","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/debug/search":{"get":{"tags":["debug"],"summary":"Debug Search Api","operationId":"debug_search_api_api_v1_debug_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Q"}},{"name":"min_score","in":"query","required":false,"schema":{"type":"number","maximum":100,"minimum":0,"default":85.0,"title":"Min Score"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Debug Search Api Api V1 Debug Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/debug/search":{"get":{"tags":["debug"],"summary":"Debug Search Page","operationId":"debug_search_page_debug_search_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"min_score","in":"query","required":false,"schema":{"type":"number","maximum":100,"minimum":0,"default":85.0,"title":"Min Score"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/entities/{entity_id}":{"get":{"tags":["entities"],"summary":"Get OFAC entity by ID","description":"Returns full entity profile including names, aliases, programs, and identifiers. Requires a valid API key or an authenticated portal session.","operationId":"get_entity_api_v1_entities__entity_id__get","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","title":"Entity Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Entity Api V1 Entities  Entity Id  Get"}}}},"401":{"description":"Authentication required"},"404":{"description":"Entity not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/sync":{"post":{"tags":["sync"],"summary":"Sync Ofac Lists","operationId":"sync_ofac_lists_api_v1_sync_post","parameters":[{"name":"force","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Force"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/sync":{"post":{"tags":["admin"],"summary":"Sync","operationId":"sync_api_v1_admin_sync_post","parameters":[{"name":"force","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Force"}},{"name":"X-Admin-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Admin-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/meta/search-fields":{"get":{"tags":["meta"],"summary":"Search Fields","operationId":"search_fields_api_v1_meta_search_fields_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchMetaResponse"}}}}}}},"/api/v1/meta/list-sources":{"get":{"tags":["meta"],"summary":"Sanctions list issuing authorities","description":"Official government and international bodies that publish each sanctions list. Lists are refreshed automatically on a fixed schedule.","operationId":"list_sources_api_v1_meta_list_sources_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSourcesResponse"}}}}}}},"/api/v1/version":{"get":{"tags":["meta"],"summary":"Engine, matcher, and dataset version","description":"Returns component versions and the active sanctions dataset snapshot. Use for compliance records and client-side cache invalidation.","operationId":"api_version_api_v1_version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}}}}},"/ready":{"get":{"tags":["health"],"summary":"Readiness probe","description":"Readiness for load balancers: 200 only when sanctions data is loaded.","operationId":"ready_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/admin":{"get":{"summary":"Admin App","operationId":"admin_app_admin_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/":{"get":{"summary":"Web App","operationId":"web_app__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"AdminClientItem":{"properties":{"user_id":{"type":"string","title":"User Id"},"email":{"type":"string","title":"Email"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"picture":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Picture"},"plan":{"type":"string","title":"Plan"},"api_key_id":{"type":"string","title":"Api Key Id"},"enabled":{"type":"boolean","title":"Enabled"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["user_id","email","name","picture","plan","api_key_id","enabled","created_at"],"title":"AdminClientItem"},"AdminDashboardResponse":{"properties":{"total_clients":{"type":"integer","title":"Total Clients"},"total_api_keys":{"type":"integer","title":"Total Api Keys"},"active_api_keys":{"type":"integer","title":"Active Api Keys"},"disabled_api_keys":{"type":"integer","title":"Disabled Api Keys"},"signups_today":{"type":"integer","title":"Signups Today"},"requests_today":{"type":"integer","title":"Requests Today"},"plan_distribution":{"additionalProperties":{"type":"integer"},"type":"object","title":"Plan Distribution"},"recent_clients":{"items":{"$ref":"#/components/schemas/AdminClientItem"},"type":"array","title":"Recent Clients"}},"type":"object","required":["total_clients","total_api_keys","active_api_keys","disabled_api_keys","signups_today","requests_today","plan_distribution","recent_clients"],"title":"AdminDashboardResponse"},"AdminUpdateApiKeyRequest":{"properties":{"plan":{"anyOf":[{"type":"string","enum":["free","starter","business","enterprise"]},{"type":"null"}],"title":"Plan","description":"Assign subscription plan (e.g. enterprise for unlimited quota)"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled","description":"Enable or disable the API key"}},"type":"object","title":"AdminUpdateApiKeyRequest"},"ApiKeyCreatedResponse":{"properties":{"api_key_id":{"type":"string","title":"Api Key Id"},"plan":{"type":"string","title":"Plan"},"requests_per_minute":{"type":"integer","title":"Requests Per Minute"},"requests_per_month":{"type":"integer","title":"Requests Per Month"},"enabled":{"type":"boolean","title":"Enabled"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"created_at":{"type":"string","title":"Created At"},"owner_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner User Id"},"api_key":{"type":"string","title":"Api Key","description":"Raw secret — shown once at creation"}},"type":"object","required":["api_key_id","plan","requests_per_minute","requests_per_month","enabled","label","created_at","api_key"],"title":"ApiKeyCreatedResponse"},"ApiKeyListItem":{"properties":{"api_key_id":{"type":"string","title":"Api Key Id"},"plan":{"type":"string","title":"Plan"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"enabled":{"type":"boolean","title":"Enabled"},"created_at":{"type":"string","title":"Created At"},"is_primary":{"type":"boolean","title":"Is Primary","default":false},"owner_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner User Id"},"has_secret":{"type":"boolean","title":"Has Secret","default":false},"relation":{"type":"string","enum":["owned","imported"],"title":"Relation","default":"owned"}},"type":"object","required":["api_key_id","plan","label","enabled","created_at"],"title":"ApiKeyListItem"},"ApiKeyListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ApiKeyListItem"},"type":"array","title":"Items"},"primary_api_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Api Key Id"}},"type":"object","required":["items"],"title":"ApiKeyListResponse"},"ApiKeyPublicResponse":{"properties":{"api_key_id":{"type":"string","title":"Api Key Id"},"plan":{"type":"string","title":"Plan"},"requests_per_minute":{"type":"integer","title":"Requests Per Minute"},"requests_per_month":{"type":"integer","title":"Requests Per Month"},"enabled":{"type":"boolean","title":"Enabled"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"created_at":{"type":"string","title":"Created At"},"owner_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner User Id"}},"type":"object","required":["api_key_id","plan","requests_per_minute","requests_per_month","enabled","label","created_at"],"title":"ApiKeyPublicResponse"},"ApiKeyRotateResponse":{"properties":{"api_key_id":{"type":"string","title":"Api Key Id"},"plan":{"type":"string","title":"Plan"},"requests_per_minute":{"type":"integer","title":"Requests Per Minute"},"requests_per_month":{"type":"integer","title":"Requests Per Month"},"enabled":{"type":"boolean","title":"Enabled"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"created_at":{"type":"string","title":"Created At"},"owner_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner User Id"},"api_key":{"type":"string","title":"Api Key","description":"Raw secret — shown once at creation"},"previous_api_key_id":{"type":"string","title":"Previous Api Key Id"}},"type":"object","required":["api_key_id","plan","requests_per_minute","requests_per_month","enabled","label","created_at","api_key","previous_api_key_id"],"title":"ApiKeyRotateResponse"},"ApiKeySecretResponse":{"properties":{"api_key_id":{"type":"string","title":"Api Key Id"},"api_key":{"type":"string","title":"Api Key","description":"Raw secret for the owned key"}},"type":"object","required":["api_key_id","api_key"],"title":"ApiKeySecretResponse"},"AuditLogItem":{"properties":{"request_id":{"type":"string","title":"Request Id"},"screened_at":{"type":"string","title":"Screened At"},"status":{"type":"string","title":"Status"},"source":{"type":"string","title":"Source","default":"api"},"top_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Top Score"},"top_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top Entity Id"},"latency_ms":{"type":"number","title":"Latency Ms"},"endpoint":{"type":"string","title":"Endpoint"},"plan":{"type":"string","title":"Plan"},"units_used":{"type":"integer","title":"Units Used"},"rate_limited":{"type":"boolean","title":"Rate Limited"}},"type":"object","required":["request_id","screened_at","status","top_score","top_entity_id","latency_ms","endpoint","plan","units_used","rate_limited"],"title":"AuditLogItem"},"AuditLogListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AuditLogItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["items","total","limit","offset"],"title":"AuditLogListResponse"},"AuditResultResponse":{"properties":{"request_id":{"type":"string","title":"Request Id"},"request":{"additionalProperties":true,"type":"object","title":"Request"},"response":{"additionalProperties":true,"type":"object","title":"Response"},"screened_at":{"type":"string","title":"Screened At"},"status":{"type":"string","title":"Status"}},"type":"object","required":["request_id","request","response","screened_at","status"],"title":"AuditResultResponse"},"BatchScreenRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ScreenRequest"},"type":"array","minItems":1,"title":"Items","description":"Screening queries to run in one HTTP request (max batch size enforced by server)."},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Url","description":"Optional HTTPS URL to POST batch results when complete"}},"type":"object","required":["items"],"title":"BatchScreenRequest"},"Body_screen_batch_csv_api_v1_screen_batch_csv_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Url"}},"type":"object","required":["file"],"title":"Body_screen_batch_csv_api_v1_screen_batch_csv_post"},"ConnectApiKeyRequest":{"properties":{"api_key":{"type":"string","maxLength":256,"minLength":8,"title":"Api Key","description":"Existing ofac_… secret to attach to the portal session"}},"type":"object","required":["api_key"],"title":"ConnectApiKeyRequest"},"CreateApiKeyRequest":{"properties":{"plan":{"type":"string","enum":["free","starter","business","enterprise"],"title":"Plan"},"label":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Label"},"requests_per_minute":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Requests Per Minute"},"requests_per_month":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Requests Per Month"}},"type":"object","required":["plan"],"title":"CreateApiKeyRequest"},"CreatePortalApiKeyRequest":{"properties":{"plan":{"type":"string","enum":["free","starter","business","enterprise"],"title":"Plan","description":"Plan tier for the new key (one key per plan per account)"},"label":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Label"}},"type":"object","required":["plan"],"title":"CreatePortalApiKeyRequest"},"EntitySummary":{"properties":{"entity_id":{"type":"string","title":"Entity Id"},"list_type":{"type":"string","title":"List Type"},"best_score":{"type":"number","title":"Best Score"},"confidence":{"anyOf":[{"type":"string","enum":["very_high","high","medium_high","medium","low"]},{"type":"null"}],"title":"Confidence"},"aliases_matched":{"items":{"type":"string"},"type":"array","title":"Aliases Matched"}},"type":"object","required":["entity_id","list_type","best_score"],"title":"EntitySummary"},"ErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"}},"type":"object","required":["detail"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ImportApiKeyRequest":{"properties":{"api_key":{"type":"string","maxLength":256,"minLength":8,"title":"Api Key","description":"Existing ofac_… secret belonging to another account"},"label":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Label"}},"type":"object","required":["api_key"],"title":"ImportApiKeyRequest"},"ListHealthItem":{"properties":{"status":{"type":"string","enum":["ok","failed","missing"],"title":"Status","default":"missing"},"last_success_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Success At"},"last_attempt_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Attempt At"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","title":"ListHealthItem"},"ListSourcePublic":{"properties":{"list_type":{"type":"string","title":"List Type"},"label":{"type":"string","title":"Label"},"authority":{"type":"string","title":"Authority","description":"Issuing government or international body"},"jurisdiction":{"type":"string","title":"Jurisdiction"},"description":{"type":"string","title":"Description","default":""}},"type":"object","required":["list_type","label","authority","jurisdiction"],"title":"ListSourcePublic"},"ListSourcesResponse":{"properties":{"sources":{"items":{"$ref":"#/components/schemas/ListSourcePublic"},"type":"array","title":"Sources"},"sync_interval_hours":{"type":"integer","title":"Sync Interval Hours","description":"Automatic refresh interval in hours"},"refresh_policy":{"type":"string","title":"Refresh Policy","default":"All lists are re-downloaded from official sources on each scheduled refresh."}},"type":"object","required":["sources","sync_interval_hours"],"title":"ListSourcesResponse"},"MatchResponse":{"properties":{"score":{"type":"number","title":"Score","description":"Compared-field similarity (0–100) among fields that were actually compared. Not a probability that the subject is sanctioned or that identity is confirmed."},"confidence":{"anyOf":[{"type":"string","enum":["very_high","high","medium_high","medium","low"]},{"type":"null"}],"title":"Confidence","description":"Heuristic evidence-strength band from classification and completeness. Never means '100% sanctioned', 'identity confirmed', or 'safe'."},"evidence_strength":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Evidence Strength","description":"Heuristic similarity of fields that were actually compared (0-1). Not a probability and not raised by unpublished data."},"classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Classification","description":"Per-candidate identity label: exact, potential, possible, or low_likelihood"},"reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason Code"},"evidence_completeness":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Evidence Completeness","description":"Evidence coverage: share of independent identity attributes that were available and compared. Not a probability. A name-only score of 100 still has low coverage when DOB and identifiers were not compared."},"name_correspondence":{"anyOf":[{"type":"string","enum":["exact_primary","exact_alias","fuzzy","partial_or_token","none_or_not_supplied"]},{"type":"null"}],"title":"Name Correspondence","description":"How the query name matched the stored primary name or alias. Derived from typed normalized equality or fuzzy grade — never from a numeric score threshold alone. exact_primary / exact_alias require full normalized-string equality."},"name_similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Name Similarity","description":"Name similarity for the winning name comparison (0–100). Separate from overall score."},"name_match_heading":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name Match Heading","description":"Human-readable name-correspondence heading (e.g. Exact primary-name match)."},"identity_assessment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Identity Assessment","description":"Human-readable identity assessment separate from name correspondence (e.g. Identity not verified · Review required)."},"name_identity_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name Identity Summary","description":"Combined short summary of name match method and identity assessment."},"name_relationship":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name Relationship","description":"Optional structured name relationship such as CORE_NAME_EXACT_MIDDLE_UNPROVIDED. Does not by itself mean Exact identity."},"alignment_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alignment Method","description":"How core name parts were aligned: source_components or token_fallback_3."},"middle_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Middle Status","description":"Middle-name comparison status for core alignment: omitted, matched, conflict, or unknown."},"why_not_exact":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Why Not Exact","description":"When classification is not Exact, a precise reason the Exact routes did not apply."},"review_priority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Priority"},"decision_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision Reason"},"retrieval_methods":{"items":{"type":"string"},"type":"array","title":"Retrieval Methods"},"evidence":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Evidence"},"matched_name":{"type":"string","title":"Matched Name"},"entity_id":{"type":"string","title":"Entity Id"},"list_type":{"type":"string","title":"List Type"},"party_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Party Type"},"programs":{"items":{"type":"string"},"type":"array","title":"Programs"},"matched_fields":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"object","title":"Matched Fields"},"ignored_fields":{"items":{"type":"string"},"type":"array","title":"Ignored Fields"},"mismatched_fields":{"items":{"type":"string"},"type":"array","title":"Mismatched Fields"},"explain":{"additionalProperties":true,"type":"object","title":"Explain"},"names":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Names"},"identifiers":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Identifiers"},"places_of_birth":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Places Of Birth"},"positions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Positions"},"dates":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Dates"},"addresses":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Addresses"},"source":{"anyOf":[{"$ref":"#/components/schemas/SourceMetadata"},{"type":"null"}]}},"type":"object","required":["score","matched_name","entity_id","list_type"],"title":"MatchResponse"},"MeAccountResponse":{"properties":{"api_key_id":{"type":"string","title":"Api Key Id"},"plan":{"type":"string","title":"Plan"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"enabled":{"type":"boolean","title":"Enabled"},"requests_per_minute":{"type":"integer","title":"Requests Per Minute"},"requests_per_month":{"type":"integer","title":"Requests Per Month"},"minute_used":{"type":"integer","title":"Minute Used"},"minute_remaining":{"type":"integer","title":"Minute Remaining"},"month_used":{"type":"integer","title":"Month Used"},"month_remaining":{"type":"integer","title":"Month Remaining"},"created_at":{"type":"string","title":"Created At"},"last_used":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used"},"requests_today":{"type":"integer","title":"Requests Today","default":0},"requests_month":{"type":"integer","title":"Requests Month","default":0}},"type":"object","required":["api_key_id","plan","label","enabled","requests_per_minute","requests_per_month","minute_used","minute_remaining","month_used","month_remaining","created_at"],"title":"MeAccountResponse"},"MeStatsResponse":{"properties":{"plan":{"type":"string","title":"Plan"},"requests_today":{"type":"integer","title":"Requests Today"},"clear":{"type":"integer","title":"Clear"},"possible":{"type":"integer","title":"Possible","default":0},"potential":{"type":"integer","title":"Potential"},"matches":{"type":"integer","title":"Matches"},"avg_latency_ms":{"type":"number","title":"Avg Latency Ms"},"minute_remaining":{"type":"integer","title":"Minute Remaining"},"month_remaining":{"type":"integer","title":"Month Remaining"},"requests_hourly":{"items":{"type":"integer"},"type":"array","title":"Requests Hourly","description":"Request counts per hour for the last 24 hours (oldest first)"}},"type":"object","required":["plan","requests_today","clear","potential","matches","avg_latency_ms","minute_remaining","month_remaining"],"title":"MeStatsResponse"},"ScreenRequest":{"properties":{"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name","description":"Given / first name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"middle_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Middle Name"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type"},"dob":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dob"},"passport":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Passport"},"national_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"National Id"},"tax_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Id"},"registration_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registration Number"},"swift_bic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Swift Bic"},"imo_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Imo Number"},"vessel_call_sign":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vessel Call Sign"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"identifier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Identifier"},"min_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Min Score"},"lists":{"items":{"type":"string","enum":["SDN","CONSOLIDATED","UN","UK","EU"]},"type":"array","title":"Lists","description":"Sanctions lists to screen against (UN, UK, EU when loaded)"},"search_strategy":{"type":"string","enum":["combined","per_field","all_fields"],"title":"Search Strategy","default":"combined"},"active_fields":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Active Fields"}},"type":"object","title":"ScreenRequest","examples":[{"country":"Canada","first_name":"John","last_name":"Doe","lists":["SDN","CONSOLIDATED"],"min_score":85}]},"ScreenResponse":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"Unique request identifier (also in X-Request-ID header)"},"status":{"type":"string","enum":["clear","potential_match","possible_match","match","exact","incomplete_search"],"title":"Status"},"confidence":{"anyOf":[{"type":"string","enum":["very_high","high","medium_high","medium","low"]},{"type":"null"}],"title":"Confidence","description":"Heuristic evidence-strength label from the classification and completeness. Not a probability that the subject is sanctioned, identity-confirmed, or safe."},"match_quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Match Quality","description":"Reason code for a classified result, or a legacy quality code"},"decision_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision Reason","description":"Why the candidate was retrieved and classified, including why it is not Exact"},"search_complete":{"type":"boolean","title":"Search Complete","default":true},"search_notes":{"items":{"type":"string"},"type":"array","title":"Search Notes"},"search_strategy":{"type":"string","enum":["combined","per_field","all_fields"],"title":"Search Strategy"},"search_mode":{"type":"string","enum":["exact","discovery"],"title":"Search Mode","default":"exact"},"query":{"additionalProperties":true,"type":"object","title":"Query"},"matches":{"items":{"$ref":"#/components/schemas/MatchResponse"},"type":"array","title":"Matches"},"low_likelihood":{"items":{"$ref":"#/components/schemas/MatchResponse"},"type":"array","title":"Low Likelihood"},"entities":{"items":{"$ref":"#/components/schemas/EntitySummary"},"type":"array","title":"Entities"},"by_field":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"By Field"},"screened_at":{"type":"string","format":"date-time","title":"Screened At"},"data_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Version"},"records_loaded":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Records Loaded"},"latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency Ms","description":"Server-side screening latency in milliseconds"}},"type":"object","required":["request_id","status","search_strategy","query","matches","screened_at"],"title":"ScreenResponse","examples":[{"confidence":"medium","data_version":"1783098273","decision_reason":"Exact distinctive primary name with no confirming date of birth. Strong identity-data correspondence; review required. This is not a legal determination that the subject is sanctioned.","entities":[{"aliases_matched":["John Doe"],"best_score":100.0,"confidence":"medium","entity_id":"10001","list_type":"SDN"}],"match_quality":"POTENTIAL_NAME_ONLY","matches":[{"classification":"potential","confidence":"medium","entity_id":"10001","evidence_completeness":0.25,"evidence_strength":0.35,"explain":{"country":{"query":"Canada","reason":"not published on this list","status":"ignored"},"name":{"candidate":"John Doe","method":"normalized_exact","name_similarity":100.0,"name_state":"primary_exact","query":"John Doe","score":100.0}},"identity_assessment":"Identity not verified · Review required","ignored_fields":["country","dob"],"list_type":"SDN","matched_fields":{"name":100.0},"matched_name":"John Doe","mismatched_fields":[],"name_correspondence":"exact_primary","name_identity_summary":"Exact primary-name match — identity not verified.","name_match_heading":"Exact primary-name match","name_similarity":100.0,"party_type":"individual","places_of_birth":[],"positions":[],"programs":["EXAMPLE"],"reason_code":"POTENTIAL_NAME_ONLY","score":100.0,"source":{"authority":"OFAC","data_version":"1783098273","last_synced_at":"2026-07-04T08:00:00Z","list":"OFAC SDN"}}],"query":{"country":"Canada","first_name":"John","last_name":"Doe","lists":["SDN","CONSOLIDATED"],"min_score":85},"records_loaded":19571,"request_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","screened_at":"2026-07-04T08:00:00Z","search_complete":true,"search_mode":"exact","search_notes":[],"search_strategy":"combined","status":"potential_match"}]},"SearchFieldMeta":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"group":{"type":"string","title":"Group"},"description":{"type":"string","title":"Description"},"tier":{"type":"string","enum":["essential","secondary","specialized"],"title":"Tier","default":"secondary"},"input_type":{"type":"string","enum":["text","select"],"title":"Input Type","default":"text"},"options":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Options"},"placeholder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Placeholder"}},"type":"object","required":["key","label","group","description"],"title":"SearchFieldMeta"},"SearchMetaResponse":{"properties":{"fields":{"items":{"$ref":"#/components/schemas/SearchFieldMeta"},"type":"array","title":"Fields"},"strategies":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Strategies"},"lists":{"items":{"type":"string"},"type":"array","title":"Lists"},"usage_guide":{"items":{"type":"string"},"type":"array","title":"Usage Guide"}},"type":"object","required":["fields","strategies","lists"],"title":"SearchMetaResponse"},"SignupRequest":{"properties":{"plan":{"type":"string","enum":["free","starter","business","enterprise"],"title":"Plan","default":"free"},"email":{"anyOf":[{"type":"string","maxLength":254},{"type":"null"}],"title":"Email","description":"Optional contact email for your account"}},"type":"object","title":"SignupRequest"},"SourceMetadata":{"properties":{"authority":{"type":"string","title":"Authority","description":"Issuing government or international body"},"list":{"type":"string","title":"List"},"jurisdiction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction"},"data_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Version"},"last_synced_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Synced At"}},"type":"object","required":["authority","list"],"title":"SourceMetadata"},"StatusResponse":{"properties":{"api":{"type":"string","title":"Api"},"data_source":{"type":"string","title":"Data Source"},"ofac_sls":{"type":"string","title":"Ofac Sls"},"last_sync":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Sync"},"last_check":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Check"},"next_sync":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Sync"},"sync_interval_hours":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sync Interval Hours"},"background_sync":{"type":"boolean","title":"Background Sync","default":false},"publication_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publication Date"},"sdn_count":{"type":"integer","title":"Sdn Count"},"consolidated_count":{"type":"integer","title":"Consolidated Count"},"un_count":{"type":"integer","title":"Un Count","default":0},"uk_count":{"type":"integer","title":"Uk Count","default":0},"eu_count":{"type":"integer","title":"Eu Count","default":0},"list_counts":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"List Counts","description":"Record count per list type (SDN, CONSOLIDATED, UN, UK, EU)"},"list_sources":{"anyOf":[{"items":{"$ref":"#/components/schemas/ListSourcePublic"},"type":"array"},{"type":"null"}],"title":"List Sources","description":"Official issuing authorities for each sanctions list"},"list_health":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/ListHealthItem"},"type":"object"},{"type":"null"}],"title":"List Health","description":"Per-list update health (ok / failed / missing)"},"records_loaded":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Records Loaded"},"ready":{"type":"boolean","title":"Ready"},"median_latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Latency Ms","description":"Median screening latency from recent audit logs (robust to cold starts)"},"p95_latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Latency Ms","description":"95th percentile screening latency from recent audit logs"}},"type":"object","required":["api","data_source","ofac_sls","sdn_count","consolidated_count","ready"],"title":"StatusResponse"},"SyncResponse":{"properties":{"status":{"type":"string","title":"Status"},"records_added":{"type":"integer","title":"Records Added"},"records_updated":{"type":"integer","title":"Records Updated"},"records_removed":{"type":"integer","title":"Records Removed"},"publication_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publication Date"},"file_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Hash"},"records_loaded":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Records Loaded"},"synced_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Synced At"}},"type":"object","required":["status","records_added","records_updated","records_removed","publication_date","file_hash"],"title":"SyncResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VersionResponse":{"properties":{"engine":{"type":"string","title":"Engine","description":"Screening engine release"},"matcher":{"type":"string","title":"Matcher","description":"Matching/scoring algorithm release"},"api":{"type":"string","title":"Api","description":"HTTP API release"},"dataset":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dataset","description":"OFAC publication date (YYYY-MM-DD)"},"records":{"type":"integer","title":"Records","description":"Total records loaded"},"ofac":{"type":"string","title":"Ofac","description":"Active list sources, e.g. SDN+CONSOLIDATED"}},"type":"object","required":["engine","matcher","api","dataset","records","ofac"],"title":"VersionResponse"}}},"tags":[{"name":"screening","description":"Screen individuals and entities against OFAC SDN and Consolidated lists. Supports multi-field queries, weighted scoring, and field-level explain."},{"name":"health","description":"Service health and sanctions list status."},{"name":"entities","description":"Retrieve full OFAC entity profiles by `entity_id`."},{"name":"meta","description":"Search field metadata for building screening forms."},{"name":"admin","description":"Administrative operations (API keys, sync, audit lookup). Requires admin API key."}]}