Workflow semantics
A complete job is more than one POST request.
Durable IDs separate caller timeouts from job state. Every integration should persist identifiers, inspect outcomes, and retrieve only organization-owned outputs.
1. Discover
GET /v1/capabilities before enabling a source or profile. Cache briefly, but refresh when the API version or client configuration changes.
2. Prepare the source
Direct text and approved URLs can enter a job. Files first use an upload intent, exact headers, a checksum-bound PUT, and a completion request.
3. Create idempotently
POST /v1/jobs with one Idempotency-Key per logical intent. Reuse the key only for a byte-equivalent retry. Persist the job ID before polling.
4. Observe to a terminal state
Poll the canonical Location, honor Retry-After, add jitter, and stop at succeeded, failed, canceled, or expired. A transport timeout is not a job failure.
5. Evaluate and retrieve
Inspect progress, warnings, expiry, output status, format, profile, and manifest checksums. Read bounded content pages or follow a signed artifact URL before it expires.
6. Retain or delete intentionally
Ephemeral and temporary outputs expire automatically. Account retention persists until policy expiry or explicit deletion. Deletion is asynchronous and organization-scoped.