Skip to navigation

Sync and async

Use one route for both. The Prefer header says how long you hold the connection.
View as Markdown

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.

Client sendsServer does
Prefer: wait=30Holds the request for up to 30 seconds. 200 with the job when it ends. 202 when it does not.
Prefer: respond-asyncAnswers 202 at once. An inline job holds the request while it runs. Read Inline jobs.
Accept: text/event-streamStreams the events of the job. Read Streaming.
notify in the bodySends a signed webhook. Read Webhooks. It works with every mode.
No preferenceThe default of the capability.

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.

curl -s -i -X POST "https://$CRK_SLUG.cloudraker.run/v2/parse" \
-H "Authorization: Bearer $CRK_API_KEY" \
-H "Content-Type: application/json" \
-H "Prefer: wait=30" \
-d '{ "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf" } }'

If the job still runs at the end of the wait, the answer is 202 with the same job:

HTTP/1.1 202 Accepted
Location: /v2/jobs/job_01JC9M…
Retry-After: 5
Preference-Applied: wait=30
{ "object": "job", "id": "job_01JC9M…", "capability": "parse", "status": "running" }

?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:

HTTP/1.1 202 Accepted
Location: /v2/jobs/job_01JC9M…
Retry-After: 5
Preference-Applied: respond-async

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:

PreferenceThe job must end within
No preference, Prefer: respond-async, or a wait of 25 or more55 seconds after the request
Prefer: wait=N with N below 25N + 30 seconds

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:

CapabilitiesDefault
parse, extract, classify, split, fill, redact, generate, convert, redlinewait=30
sign, transcriberespond-async

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} with Accept: text/event-stream. Read Streaming.
  • A wait: GET /v2/jobs/{id} with Prefer: wait=N. The server holds the request until the job ends, needs input, or the wait ends. The answer is 200 with the job. Check status, 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:

FieldMeaning
deadlineWhen the work must finish. Only "asap". Another value gives 400 deadline_not_supported.
notify{ "url": "https://…" } or { "endpoint": "whe_…" }. Read Webhooks.
metadataA JSON object of at most 10 KiB. The API checks it and does not store it. The Job object has no metadata.