Agents
Integrating an AI agent directly against the Aletheia API, the error model, limits and idempotency
This page describes stable protocol behaviour for an AI agent integrating programmatically against Aletheia, without the MCP server (see MCP server if you want typed tool calls instead). Terse and schema-cited. The authoritative machine-readable contract is the OpenAPI document, rendered in the reference; request/response schemas, security schemes, and error bodies are defined there. Implementation details of the server are deliberately omitted.
Authentication
There are two auth modes; which one applies is a server-side deployment setting. Production multi-tenant deployments use Mode A; Mode B exists for local and staging tooling.
Mode A, production multi-tenant
- Tenant API key as bearer token:
Authorization: Bearer fsk_<8-char-prefix>_<secret>. - Optional mTLS: where a tenant opts into connection-level client-certificate auth, the reverse
proxy sets
X-Client-Cert-Verify: SUCCESSandX-Client-Cert-DN: CN=<tenant-cn>,...on every inbound request. You never set these yourself. Not required by default, see mTLS.
The tenant identity is derived from the key, not from a header. X-Tenant-ID is ignored in this
mode. Keys are issued by IDCanopy (no self-service).
On failure the middleware returns 401 with {"detail": "authentication required"} and no
enumeration of which check failed.
Mode B, local and staging single-tenant
Authorization: Bearer <shared-service-token>
X-Tenant-ID: <tenant-slug> # honoured only in this modeThe shared service token (32 characters or more) is provided to you by IDCanopy for the relevant environment. Never commit or log it. This mode is for local and staging tooling, not production traffic.
Pending verification: the Aletheia team's guide says "staging" here; the sandbox page says a sandbox tenant receives a
fsk_tenant key (Mode A) and that non-production hosts carry a-sbx,-testor-devsuffix. Which mode a sandbox tenant runs in is being confirmed.
Ingestion paths
See Submitting a case for the complete overview (stateless, stateful, ZIP, outbound webhook). The notes here focus on what an AI-agent integrator needs.
Path 1, stateless POST /analyze
- Returns a synchronous
ForensicResult(HTTP 200). - Side effects: none. No applicant state is persisted, no outbound webhook fires.
- Use when: one-off checks, smoke tests, integrations that manage their own state.
Request: multipart/form-data
| Field | Type | Required |
|---|---|---|
files | repeated file | yes, 1 to 15 files |
applicant_id | string | no, caller-supplied label, not persisted |
case_meta | JSON string | no |
case_type, manifest, master_data | string, JSON string, JSON string | no, see Case types |
curl -X POST "$ALETHEIA_BASE_URL/analyze" \
-H "Authorization: Bearer $FORENSIC_API_TOKEN" \
-F "files=@/tmp/payslip.pdf" \
-F "files=@/tmp/statement.pdf" \
-F 'applicant_id=test-001'import httpx, pathlib
def analyze(token: str, doc_paths: list[str], base_url: str = "https://aletheia.api-umbrella.io") -> dict:
files = [("files", (pathlib.Path(p).name, open(p, "rb"))) for p in doc_paths]
r = httpx.post(
f"{base_url}/analyze",
headers={"Authorization": f"Bearer {token}"},
files=files,
timeout=120,
)
r.raise_for_status()
return r.json()Path 2, stateful v1 lifecycle
Three sequential calls; applicant row and documents are persisted.
POST /v1/applicants -> 201 CreateApplicantResponse
POST /v1/applicants/{id}/documents -> 201 UploadDocumentResponse
POST /v1/applicants/{id}/analyze -> 200 ForensicResult
GET /v1/applicants/{id}/findings -> 200 (read after analyze)Duplicate applicant_id (same tenant): POST /v1/applicants returns 409. Callers must
supply a stable applicant_id and handle 409 as "already exists".
No documents uploaded: POST /v1/applicants/{id}/analyze returns 409.
The outbound result webhook fires for any tenant that has a callback URL and an outbound HMAC
secret provisioned. Where the request originated from the inbound URL-fetch webhook, the outbound
payload also echoes that submission's external_applicant_id.
# 1. create
APP=$(curl -sX POST "$ALETHEIA_BASE_URL/v1/applicants" \
-H "Authorization: Bearer $FORENSIC_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"applicant_id":"app-001"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['applicant_id'])")
# 2. upload (multipart, repeated 'files' field)
curl -X POST "$ALETHEIA_BASE_URL/v1/applicants/$APP/documents" \
-H "Authorization: Bearer $FORENSIC_API_TOKEN" \
-F "files=@/tmp/payslip.pdf"
# 3. analyze
curl -X POST "$ALETHEIA_BASE_URL/v1/applicants/$APP/analyze" \
-H "Authorization: Bearer $FORENSIC_API_TOKEN"Inbound push webhook
For partners who push applicants to Aletheia rather than calling the paths above, there is a
URL-fetch inbound webhook at POST /v1/integrations/inbound/webhook (the tenant is derived from
the bearer key; enrolment requires a provisioned inbound webhook secret). Generic AI-agent
integrators do not call this directly; they go through paths 1 or 2. See
Submitting a case.
ForensicResult schema
Defined in the OpenAPI document as #/components/schemas/ForensicResult.
{
"applicant_id": "app-001",
"case_type": "account_application",
"verdict": {
"verdict": "REJECT", // REJECT | ESCALATE | PENDING | CONDITIONAL | PASS
"reason_codes": ["MRZ_CHECKSUM_FAIL"],
"override_rules_fired": ["I1"],
"verdict_explanation": ""
},
"findings": [
{
"check_id": "mrz_checksum_failure",
"check_category": "identity",
"severity": "HIGH",
"summary": "MRZ check digit mismatch on birth date",
"evidence_quote": "expected=3, computed=7",
"source_document_id": "doc-uuid",
"message": { "what": "...", "what_to_do": "..." },
"metadata": {}
}
],
"advisory_score": 12, // 0-100, informational only, does not drive verdict
"advisory_band": "HIGH_RISK", // HIGH_RISK | REVIEW | LOW_RISK
"checker_version": "0.5.1-phase4",
"analysis_ts": "2026-05-31T10:00:00Z",
"recommended_action": "Request current payslip",
"verdict_message": { "what": "...", "what_to_do": "..." },
"tenant_config_hash": "sha256:..." // null when no tenant configuration applies
}Verdict order (severity): REJECT > ESCALATE > PENDING > CONDITIONAL > PASS.
Stable check_id, reason_code and override_rules_fired values are catalogued in
check-catalog.json; tolerate unknown codes (forward-compatible).
message and verdict_message carry the operator texts from the
message catalogue. Typed case types add code,
item_id and references per finding and risk_indicator, consistency_result, items and
missing on the result, see Case types.
Error model
Extraction failures resolve to PENDING
Two distinct failure points both resolve to verdict = "PENDING":
Finding check_id | Origin | Rule | Meaning |
|---|---|---|---|
extraction_failed | Check-level extraction call failure | Q3 | A single document-extraction call failed (HTTP 4xx/5xx, timeout, parse error). Evidence is incomplete; verdict deferred. |
Q3_EXTRACTION_FAILURE | Case-level extraction abort | (finding itself) | The entire extraction stage failed. All evidence is unavailable; verdict deferred. |
Both yield ForensicResult.verdict.verdict = "PENDING", but they surface differently:
- Check-level
extraction_failedfires override rule Q3, soverdict.override_rules_firedcontains"Q3". - Case-level
Q3_EXTRACTION_FAILUREbuilds a direct PENDING verdict withverdict.override_rules_fired = []andverdict.reason_codes = ["Q3_EXTRACTION_FAILURE"](no override rule fires).
Retry: resubmit when the extraction provider is healthy. No verdict is produced until extraction succeeds.
MRZ composite corroboration
When a composite MRZ checksum field (a check digit that covers multiple fields) mismatches:
forensic_id state | Severity emitted | Verdict floor |
|---|---|---|
forensic_id_authentic | INFO | none |
forensic_id_flagged | HIGH | review floor (ESCALATE) |
forensic_id_unavailable | HIGH | review floor (ESCALATE) |
mrz_checksum_failure is not emitted for composite-only mismatches. The outcome is
review-flagged at most; it is not an automatic REJECT.
HTTP error codes
Error bodies are ProblemDetails: {"detail": "..."}, plus trace_id on 5xx from the
stateless /analyze endpoints. 429 uses RateLimitError instead, see below.
| Code | Meaning |
|---|---|
| 400 | No files submitted; or a batch below the async threshold on POST /v1/batch/analyze |
| 401 | Auth failed |
| 404 | Unknown applicant or job, or one belonging to another tenant |
| 409 | Duplicate applicant_id (v1) or no documents uploaded before analyze (v1) |
| 413 | Too many files, file too large, or body too large |
| 422 | Unsupported file extension, malformed JSON, invalid case-type fields, or tenant not configured (for example no inbound webhook secret) |
| 429 | Rate limit exceeded, see the Retry-After header |
| 502 | Document URL fetch failed (inbound webhook) |
| 500 | Internal error. trace_id in the body only on stateless /analyze; v1 endpoints return plain {"detail": "..."} without a trace id |
Limits
File upload
| Limit | Value |
|---|---|
| Max files per request | 15 |
| Max size per file | 20 MB |
| Max total body | 50 MB |
| Accepted extensions | .pdf .jpg .jpeg .heic .heif .png .tif .tiff |
Upload field name is files (repeated). Example with two files:
multipart/form-data:
files: <bytes of payslip.pdf>
files: <bytes of statement.pdf>Rate limiting
Active in production.
- 60 requests per minute per tenant (default; overridable via tenant configuration).
- Breach: HTTP
429with aRetry-After: <seconds-to-next-window>header and the body{"error": "rate_limit_exceeded", "retry_after": N}(theRateLimitErrorschema). /v1/batch/*is exempt from per-request rate limiting, as are/healthz,/metrics,/docsand/v1/billing/*.
Idempotency
Applies to POST /v1/integrations/inbound/webhook only.
- Header:
X-Idempotency-Key: <caller-supplied UUID>. - Replay window: 24 hours. A second call with the same key within 24 h returns the cached
202response with"idempotency_replay": true. The key is optional; if omitted, the request is treated as fresh and no de-duplication occurs.
For the v1 stateful path, idempotency is the caller's responsibility:
- Supply a stable, unique
applicant_idat creation time. POST /v1/applicantswith a duplicate id returns409; handle it as "already registered".
Pagination and polling, explicit non-goals
- No applicant-list endpoint. There is no paginated
GET /v1/applicants. POST /analyzeandPOST /v1/applicants/{id}/analyzeare synchronous. No polling needed; the response is the result.- After
POST /v1/applicants/{id}/analyze, useGET /v1/applicants/{id}/findingsto retrieve stored findings for that applicant. - Polling applies only to ZIP jobs (
GET /analyze/zip/{job_id}),/v1/batch/*async jobs and inbound-webhook portfolio sweep jobs (GET /v1/batch/jobs/{job_id}). All other paths return results directly.