Acorn API/Reference

API details, without the tutorial.

Endpoints, job types, status values, webhooks, and errors in a surface built to stay open while you work.

Endpoints →QuickstartFull job submission guide
Endpoints

The shipped surface.

POST/api/v1/jobsSubmit a job from a fetchable input URL. Returns 202 + job_id.GA
POST/api/v1/jobs/batchSubmit up to 100 jobs. Returns 207 with one result per item.GA
POST/v1/audio/transcriptionsOpenAI-compatible multipart transcription. Synchronous pilot path.Pilot
GET/api/v1/jobs/{job_id}Fetch status and result.GA
GET/api/v1/jobs/{job_id}/resultFetch the finished result.GA
GET/api/v1/jobs/{job_id}/shardsInspect a long job's shards.GA
GET/api/v1/jobs/{job_id}/eventsRead the state-transition audit trail.GA
GET/api/v1/jobsList recent jobs, paginated and filterable.GA
GET/api/v1/modelsList available catalog models.GA
GET/api/v1/usage/summaryRead account usage and spend. Requires a partner API key; a global client key is not sufficient.GA
Job types

One job envelope, room to grow.

The native jobs API is organized by job type so a second workload can land without changing the reference structure.

LIVEtranscribeFetchable audio in; transcript and timing metadata out.GA
Status values

A small, stable state machine.

ingestingfetching and preparing audio
pendingready, waiting for a worker
claimedassigned to a worker
processingwork is running
completedresult available
failedjob failed
failed_partialone or more shards failed; a best-effort partial result may be available
cancelledjob was cancelled
OpenAI compatibility · pilot

A supported pilot path, with limits.

POST /v1/audio/transcriptions is a supported pilot path, not a full OpenAI Audio clone.

● Supported: multipart upload · json / verbose_json / text / srt / vtt · whisper-* aliases · client or partner API keys ● Sync only: the request holds open to the 600s server deadline. Use POST /api/v1/jobs with callback_url for async work ● Timeouts: deadline_exceeded keeps the backend job alive; poll it, or resubmit with {"audio_url":"https://example.com/audio.mp3","callback_url":"https://yourapp.com/hooks/acorn"} ● Setup: multipart uploads require ACORN_ALLOW_LOCAL_AUDIO_JOBS=true; otherwise the route returns local_audio_not_enabled
Webhooks

Signed, retried, replayable.

When a partner callback secret is configured, deliveries include X-Acorn-Timestamp and X-Acorn-Signature: sha256=<hex digest>. Verify the digest with HMAC-SHA256 over the timestamp header, a period, and the raw request body using your callback secret. Compare in constant time, reject missing signatures or timestamps outside five minutes, and use job_id for idempotency. Deliveries are at least once.

Errors & retries

Stable codes, actionable retries.

Errors include a stable code, message, and X-Request-ID. Retry 429 and 503 according to Retry-After; fix other 4xx requests before retrying.

HTTP 422 · invalid_audio_duration
{ "error": { "code": "invalid_audio_duration",
  "message": "audio_duration must be zero or greater.",
  "request_id": "7f3a92c1b04d4e6f" } }
Roadmap

Not shipping yet.

These routes return 404 today and keep an OpenAI-compatible shape when they land.

POST /v1/embeddings Batch text → vectors. Up to 512 inputs per request. Not available
POST /v1/images/generations Async image generation queue. Webhook on completion. Not available
POST /v1/chat/completions Async chat completion. Non-streaming. OpenAI-compatible shape. Not available
POST /v1/batch Submit a multi-job manifest with a bring-your-own MLX checkpoint. Planned · Q4

Bring-your-own MLX checkpoint path POST /v1/batch is planned, not available. Contact us if you need an early checkpoint evaluation.