API ACCESS

Your own tools.
The same workspace.

An API key acts as its account on the job and file routes.
API access is available on the Enterprise plan only.

ONE HEADER

Send the key. Send nothing else.

Create a key on your Account page while your account is on Enterprise. It is shown once; keep it in your own secret store. Send it on every request, with no cookie beside it. A key on any other plan is refused with auth.api_plan_required.

Authorization: Bearer hk_…

The eight routes

Route	What it does
`POST /api/v1/files`	Declare an upload; answers a presigned PUT.
`POST /api/v1/files/{id}/finalize`	Confirm the bytes arrived; the file becomes ready.
`POST /api/v1/files/{id}/download`	Mint a short-lived download link for a ready file.
`GET /api/v1/files/{id}`	Read one file.
`POST /api/v1/jobs`	Start a separation or transcription job. Needs Idempotency-Key.
`GET /api/v1/jobs`	List your jobs.
`POST /api/v1/jobs/{id}/cancel`	Cancel a job that has not finished.
`GET /api/v1/jobs/{id}`	Poll one job: status, queue position, outputs.

From a file to a result

POST /api/v1/files with the file's name, type and size. The answer's upload holds a presigned url, the method (PUT) and the headers to send with it.
```
{
  "filename": "interview.wav",
  "content_type": "audio/wav",
  "content_length": 1048576
}
```
PUT the bytes to upload.url with exactly those headers. The bytes go straight to storage, not through the API.
POST /api/v1/files/{id}/finalize. The file is checked and becomes ready.
POST /api/v1/jobs with an Idempotency-Key header (any unique string per job; a retry with the same key and body returns the same job).
```
{
  "kind": "separation",
  "file_id": "file_…"
}
```
Poll GET /api/v1/jobs/{id} until the job has finished; its output_file_ids name the results.
POST /api/v1/files/{id}/download for each result, and fetch the url it answers.

When a request is refused

Every refusal is application/problem+json with a stable code. These are the ones a key's caller should expect; the error reference lists them all.

Code	When
`auth.unauthenticated`	The key is unknown, revoked, malformed or removed.
`auth.api_plan_required`	The key is real, but its account is not on Enterprise.
`auth.principal_forbidden`	The route is not one of the eight: account, billing and key management stay in the browser.
`auth.ambiguous_credential`	A session cookie was sent beside the key.
`legal.acceptance_required`	The account has not accepted the current Terms and Privacy Policy.
`api_key.limit_reached`	Creating a sixth key on the Account page.

Your own tools. The same workspace.

Send the key. Send nothing else.

The eight routes

From a file to a result

When a request is refused

Your own tools.
The same workspace.