Jobs — API reference

Asking for work and finding out how it went.

GET /v1/jobs

List jobs

Parameters

Name	In	Requirement	Description
`limit`	query	Optional	Page size.
`starting_after`	query	Optional	Cursor from the previous page’s `next_cursor`.
`state`	query	Optional	Filter by job state.
`project_id`	query	Optional	Filter by project.

Responses

Status	Description
`200`	A page of jobs, newest first.
`400`	Codes: invalid_request, unsupported_file, file_too_large, corrupted_file, encrypted_file, unsupported_operation.
`401`	Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query.
`403`	Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted.
`429`	Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted.
`500`	Codes: internal_error.
`503`	Codes: processing_unavailable, dependency_unavailable.
`504`	Codes: timeout.

POST /v1/jobs

Accepts the work and returns immediately with 202. Credits are reserved atomically at this point — a job that would exceed the balance is refused here rather than discovered on an invoice. Supply exactly one of operation or preset.

Parameters

Name	In	Requirement	Description
`Idempotency-Key`	header	Required	Client-generated key, scoped to (organization, endpoint) and retained 24 hours. A replay with the same body returns the stored response without re-executing or re-billing; a replay with a different body returns 409.

Request body

Field	Type	Requirement	Description
`file_id`	`string`	Required	The file to process.
`operation`	`string`	Optional
`preset`	`ai-ready` · `document` · `image` · `avatar` · `inspect`	Optional
`options`	`object`	Optional	Operation-specific parameters.

Responses

Status	Description
`202`	Accepted. The job is queued; subscribe to a webhook or poll `GET /v1/jobs/{job_id}`.
`400`	Codes: invalid_request, unsupported_file, file_too_large, corrupted_file, encrypted_file, unsupported_operation.
`401`	Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query.
`403`	Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted.
`404`	Not found. A resource belonging to another organization returns 404, never 403 — a 403 would confirm it exists. Codes: not_found.
`409`	Codes: idempotency_conflict, upload_session_consumed, conflict.
`422`	Codes: malware_detected, policy_violation, validation_failed, output_validation_failed, unsupported_input.
`429`	Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted.
`500`	Codes: internal_error.
`503`	Codes: processing_unavailable, dependency_unavailable.
`504`	Codes: timeout.

GET /v1/jobs/{job_id}

Retrieve a job

Parameters

Name	In	Requirement	Description
`job_id`	path	Required	Job identifier.

Responses

Status	Description
`200`	The job.
`401`	Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query.
`403`	Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted.
`404`	Not found. A resource belonging to another organization returns 404, never 403 — a 403 would confirm it exists. Codes: not_found.
`429`	Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted.
`500`	Codes: internal_error.
`503`	Codes: processing_unavailable, dependency_unavailable.
`504`	Codes: timeout.

POST /v1/batches

One operation across up to 100 files, accepted atomically: every member is admitted and priced in a single transaction, or the batch does not exist. Members are then ordinary jobs — same queues, same retries, same webhooks, same settlement — and a member that fails is a per-item error, charged nothing, while the rest proceed.

Parameters

Name	In	Requirement	Description
`Idempotency-Key`	header	Required	Client-generated key, scoped to (organization, endpoint) and retained 24 hours. A replay with the same body returns the stored response without re-executing or re-billing; a replay with a different body returns 409.

Request body

Field	Type	Requirement	Description
`file_ids`	array of `string`	Required
`operation`	`string`	Optional
`preset`	`ai-ready` · `document` · `image` · `avatar` · `inspect`	Optional
`options`	`object`	Optional	Operation-specific parameters, applied to every member.

Responses

Status	Description
`202`	Accepted. Every member is queued; poll `GET /v1/batches/{batch_id}` or subscribe to job webhooks.
`400`	Codes: invalid_request, unsupported_file, file_too_large, corrupted_file, encrypted_file, unsupported_operation.
`401`	Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query.
`403`	Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted.
`404`	Not found. A resource belonging to another organization returns 404, never 403 — a 403 would confirm it exists. Codes: not_found.
`422`	Codes: malware_detected, policy_violation, validation_failed, output_validation_failed, unsupported_input.
`429`	Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted.
`500`	Codes: internal_error.
`503`	Codes: processing_unavailable, dependency_unavailable.
`504`	Codes: timeout.

GET /v1/batches/{batch_id}

Aggregated state counts, credits estimated and charged, and the per-item outcomes. state is completed once every member is terminal — individual failures are items, not a batch failure.

Parameters

Name	In	Requirement	Description
`batch_id`	path	Required	Batch identifier.

Responses

Status	Description
`200`	The batch and its members.
`401`	Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query.
`403`	Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted.
`404`	Not found. A resource belonging to another organization returns 404, never 403 — a 403 would confirm it exists. Codes: not_found.
`429`	Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted.
`500`	Codes: internal_error.
`503`	Codes: processing_unavailable, dependency_unavailable.
`504`	Codes: timeout.

POST /v1/jobs/{job_id}/cancel

Only queued work can be reclaimed. A job the worker already claimed keeps running — compute cannot be un-spent — and answers 409 with its state. Subscribers hear job.cancelled.

Parameters

Name	In	Requirement	Description
`job_id`	path	Required	Job identifier.
`Idempotency-Key`	header	Required	Client-generated key, scoped to (organization, endpoint) and retained 24 hours. A replay with the same body returns the stored response without re-executing or re-billing; a replay with a different body returns 409.

Responses

Status	Description
`200`	Cancelled.
`401`	Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query.
`403`	Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted.
`404`	Not found. A resource belonging to another organization returns 404, never 403 — a 403 would confirm it exists. Codes: not_found.
`409`	Codes: idempotency_conflict, upload_session_consumed, conflict.
`429`	Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted.
`500`	Codes: internal_error.
`503`	Codes: processing_unavailable, dependency_unavailable.
`504`	Codes: timeout.