API design
Practice this questionWANT TO UNDERSTAND THE CONCEPT FIRST?Learn API design
| API | Contract |
|---|---|
POST /ai/conversations | Create an authorized session; server assigns ownership |
POST /ai/conversations/:id/messages | Validate bounded message, record it, return safe stream or run reference |
GET /ai/runs/:id | Return public phase, outcome, safe errors, and review requirement after ownership check |
POST /documents | Validate upload intent and permissions; issue restricted upload path; return document/job IDs |
GET /documents/:id/status | Return parse/index/review status without exposing unauthorized sources |
POST /claim-drafts | Create validated proposal with source references and version |
PATCH /claim-drafts/:id | Require expected version; edits produce new hash and invalidate prior approval |
POST /claim-drafts/:id/approvals | Bind authenticated decision to exact version/hash/action; never accept model-generated approval |
POST /claim-drafts/:id/submit | Require valid approval and scoped idempotency key; return durable receipt or explicit pending outcome |
POST /ai/runs/:id/resume | Authenticate ownership/reviewer; validate pending input event; reject stale/duplicate invalid resumes |
POST /support-tickets | Create a permitted, deduplicated escalation with bounded case context |
- Apply CSRF protection where cookie-authenticated mutation routes require it, enforce origin/authentication policy, and use appropriate error semantics.
- A pending task may return
202; a chat sentence claiming success cannot substitute for a claim receipt.
Adapted from 13_AI.MD · “API design”. Code examples are study fragments. Difficulty and core labels are editorial estimates; version-specific behavior should be checked against your project.