{ "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", "description": "Attach a saved ofac_… key to your portal session. Multiple accounts may share one key — usage quotas are synchronized per key.", "operationId": "connect_api_key_api_v1_auth_connect_key_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectApiKeyRequest" } } }, "required": true }, "responses": { "200": { "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" } } ], "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" } } ], "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" } } ], "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", "parameters": [ { "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": { "$ref": "#/components/schemas/MeAccountResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/me/stats": { "get": { "tags": [ "account" ], "summary": "Dashboard statistics for today", "operationId": "get_me_stats_api_v1_me_stats_get", "parameters": [ { "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": { "$ref": "#/components/schemas/MeStatsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/me/audit": { "get": { "tags": [ "account" ], "summary": "Search audit logs for your API key", "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" } }, { "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": { "$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)$", "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" } }, { "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": {} } } }, "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" } }, { "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": { "$ref": "#/components/schemas/AuditResultResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/me/api-key/rotate": { "post": { "tags": [ "account" ], "summary": "Rotate your API key", "description": "Issues a new secret and disables the current key. Shown once.", "operationId": "rotate_my_api_key_api_v1_me_api_key_rotate_post", "parameters": [ { "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": { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/me/api-key/disable": { "patch": { "tags": [ "account" ], "summary": "Disable your API key", "operationId": "disable_my_api_key_api_v1_me_api_key_disable_patch", "parameters": [ { "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": { "$ref": "#/components/schemas/MeAccountResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/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}/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/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" }, "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" }, "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" }, "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" } }, "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" }, "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" }, "AuditLogItem": { "properties": { "request_id": { "type": "string", "title": "Request Id" }, "screened_at": { "type": "string", "title": "Screened At" }, "status": { "type": "string", "title": "Status" }, "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" }, "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" }, "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" }, "confidence": { "anyOf": [ { "type": "string", "enum": [ "very_high", "high", "medium_high", "medium", "low" ] }, { "type": "null" } ], "title": "Confidence" }, "evidence_strength": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Evidence Strength", "description": "Compliance-oriented evidence strength (0-1), separate from raw score" }, "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" }, "matches": { "type": "integer", "title": "Matches" }, "potential": { "type": "integer", "title": "Potential" }, "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", "matches", "potential", "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": "Russia", "dob": "1952-10-07", "first_name": "Vladimir", "last_name": "Putin", "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", "match", "exact" ], "title": "Status" }, "confidence": { "anyOf": [ { "type": "string", "enum": [ "very_high", "high", "medium_high", "medium", "low" ] }, { "type": "null" } ], "title": "Confidence", "description": "Compliance-oriented confidence derived from matched and ignored fields" }, "match_quality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Match Quality", "description": "Machine-readable match quality code, e.g. strong_name_country_no_dob" }, "decision_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decision Reason", "description": "Human-readable explanation of the screening decision" }, "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" }, "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": "high", "data_version": "1783098273", "decision_reason": "Strong name match and date of birth match.", "entities": [ { "aliases_matched": [ "Putin Vladimir Vladimirovich" ], "best_score": 96.86, "confidence": "high", "entity_id": "35096", "list_type": "SDN" } ], "match_quality": "strong_name_dob", "matches": [ { "confidence": "high", "entity_id": "35096", "evidence_strength": 0.85, "explain": { "country": { "query": "Russia", "reason": "candidate has no country data", "status": "ignored" }, "dob": { "candidate": "1952-10-7", "query": "1952-10-07", "score": 95.0 }, "name": { "candidate": "Putin Vladimir", "method": "token_set + wratio + phonetic", "query": "Vladimir Putin", "score": 97.63 } }, "ignored_fields": [ "country" ], "list_type": "SDN", "matched_fields": { "dob": 95.0, "name": 97.63 }, "matched_name": "Putin Vladimir Vladimirovich", "mismatched_fields": [], "party_type": "individual", "places_of_birth": [], "positions": [], "programs": [ "RUSSIA-EO14024" ], "score": 96.86, "source": { "authority": "OFAC", "data_version": "1783098273", "last_synced_at": "2026-07-04T08:00:00Z", "list": "OFAC SDN" } } ], "query": { "country": "Russia", "dob": "1952-10-07", "first_name": "Vladimir", "last_name": "Putin", "lists": [ "SDN", "CONSOLIDATED" ], "min_score": 85 }, "records_loaded": 19571, "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "screened_at": "2026-07-04T08:00:00Z", "search_mode": "exact", "search_strategy": "combined", "status": "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" }, "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." } ] }