Jobs
A capability call creates one job. The answer, a stream and a webhook all carry the same Job object.
The Job object
Statuses
A job in a terminal status never changes. The first terminal result wins.
A failed job answers 200 with status: "failed". There is one exception: when the capability does not answer, the answer is 503 capability_unavailable. A validation error (400) creates no job.
Read the output
The shape of output depends on the capability. The paperwork capabilities have the result in output.output. An agent job has the result of the run in output.result.
A parse has two output forms, because a job can run on two paths:
Read both forms in your client. The same request can use either path. The inline path reads a source of at most 50 MB: 10 pages with no OCR, or 3 pages with OCR.
A signed URL expires after about 1 hour. GET /v2/jobs/{id} returns new URLs for a job older than 45 minutes, for up to 7 days. GET /v2/jobs returns the stored URLs.
Classify and split answers on the inline path have their fields in output.output, for example output.output.documents and output.output.splits. They do not include the fields that name stored files.
The stored output is at most 1 MiB. A larger output fails the job with output_too_large.
Job error codes
error.code of a job that did not succeed is one of these values:
Use the retryable field of the error. The table shows the usual value.
Read a job
Send Prefer: wait=N to hold the request until the job ends, the job needs input, or the wait ends. The answer is always 200 with the job. Read Sync and async.
List jobs
GET /v2/jobs lists the jobs of the environment of the credential, newest first. It needs the scope jobs:read.
Access to a job
The creating credential can read its own jobs with no extra scope. jobs:read lists the jobs of the environment of the credential. It also reads the jobs of other credentials in the same environment.
Test jobs and live jobs are separate. A credential of the other environment gets 404 job_not_found, also with jobs:read.
Without access, a read gets 404 job_not_found. So the answer does not show that the job exists. For a crt_ token or a JWT, the credential is the trust.
Cancel a job
The answer is 200 with the job in the cancelled status. Only the creating credential can cancel a job. Another credential gets 404 job_not_found, also with jobs:read. A job that ended gets 409 job_not_cancellable. If the capability cannot stop the work now, the answer is 503 capability_unavailable and the job does not change.
Retention
The API keeps a job for 30 days. A later read gets 404 job_not_found.