Core concepts

AI

Upload a PDF, then analyze it, review risk, summarize it, detect signature zones, or chat about the file.

Ingest

POST /api/ai/documents accepts multipart (file, optional external_id) or JSON (filename + content_base64 or storage_path). The 201 response includes document_id, status (often pending), and a job_id. Poll GET /api/ai/documents/{id}/status until ready or failed (pending → extracting → indexing).

Capabilities

Call	Body / query	What you get
`POST .../analyze`	`async=true` → 202	doc_type, parties, dates, amounts, clauses, obligations
`POST .../risk-review`	optional reference_model_id	`risk_score` 0–100, `risk_level` (`faible`\|`moyen`\|`eleve`)
`POST .../summary`	`length` = `court`\|`standard`\|`detaille`	`resume`, `points_cles`, `alertes`
`POST .../validator-summary`	required step and role	Shorter summary for a workflow validator
`POST .../signature-zones`	`mode` = `rules_only`\|`rules_then_vision`\|`vision_only`	Boxes with `page`, `x0,y0,x1,y1`, `confidence`

Async jobs return 202 { "job_id": "…", "status": "queued" }. Poll GET /api/ai/jobs/{job_id} (queued → running → done / failed). When done, result is the full analysis payload.

Document chat

Start a conversation with ingested document ids — not a free-form first message:

json

POST /api/ai/conversations
{ "type": "document", "document_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"] }

→ 201 { "conversation_id": "…" }

Then POST /api/ai/conversations/{id}/messages with { "content": "What is the termination clause?" } (1–2000 characters). The response is answer plus citations[] (document_id, page, extrait).

Jobs and quotas

Usage is GET /api/ai/usage/me and GET /api/ai/usage/company (company-admin) with from, to (YYYY-MM-DD), and granularity (day|month). The company payload includes quota.tokens_allocated, tokens_used, and a per-member breakdown. Super-admin model configuration is not on this gateway.