Sync and async
The client says how long it holds the connection. A slow call never fails because it is slow. It changes to async, and the job continues.
Wait
Prefer: wait=N accepts a whole number from 1 to 90. With no preference, the default of most capabilities is 30. Another value gives 400 wait_out_of_range.
If the job still runs at the end of the wait, the answer is 202 with the same job:
?wait=N is an alias of Prefer: wait=N. The header wins when both are present. The answer has Preference-Applied when the API applied a preference of the client.
Behind a proxy with a 60-second idle timeout, use wait=55 or less. The status code goes out only at the end of the wait, so the API cannot send bytes to keep the connection open. A cut connection loses nothing: the job continues.
Set the timeout of your HTTP client higher than the wait. The SDK uses a default timeout of 100 seconds.
Respond async
Prefer: respond-async answers 202 at once:
With Prefer: respond-async, wait=N, the API holds the request for up to N seconds, then answers 202. Preference-Applied names respond-async only on a 202.
An inline job does not answer at once. Read Inline jobs.
Inline jobs
generate, convert, and the redline export and apply jobs are inline jobs. An inline job does all of its work inside the request, so it has a time limit:
A job that runs longer fails with capability_lost. Send a smaller file, or split a large convert into more jobs.
With Prefer: respond-async, the API holds the request while the job runs, for at most 30 seconds. This gives the job the same time as the default wait. A job that ends in that time answers 200 with its output, and the answer has no Preference-Applied. A job that still runs answers 202, and the job continues. A webhook comes in both cases.
Defaults
With no preference, the capability sets the default:
A sign job never answers 200 from the first call: a person signs later. An agent can run for a long time. Send a preference for agents.
After a 202
Use one of these methods:
- Webhooks: the API calls your endpoint when the job ends. Read Webhooks.
- A stream:
GET /v2/jobs/{id}withAccept: text/event-stream. Read Streaming. - A wait:
GET /v2/jobs/{id}withPrefer: wait=N. The server holds the request until the job ends, needs input, or the wait ends. The answer is200with the job. Checkstatus, and call again if the job still runs.
A wait also ends when the job reaches needs_input, because a client cannot wait for a person.
Body fields
These fields are in the JSON body of a capability call, next to the input of the capability: