Design preview
API request lifecycle preview
Small text operations can return synchronously. Files and deeper media analysis fit an asynchronous job model with idempotent creation, polling and optional signed webhooks.
Synchronous pattern
- Authenticate
Send a scoped credential over TLS.
- Validate
The service checks content type, input bounds and capability access.
- Process
A bounded text operation completes inside the request window.
- Return
The response includes a stable request identifier, result and usage fields.
Asynchronous pattern
create job → receive job_id → poll status → fetch typed result
↘ optional signed completion webhookUploads and deeper media scans benefit from jobs because runtime depends on file size, OCR, scan profile and available workers. The final contract should define terminal states, retry behavior and retention clearly.
Reliability controls
- Idempotency keys on create operations
- Request IDs on every response and error
- Explicit retry guidance for 429 and temporary 5xx responses
- Webhook signatures with timestamp tolerance
- Owner-scoped job reads and expiring upload references