Knowledge Base
Sync & async
Almost every tool in the API is synchronous — you send one request, the work runs, and the finished result comes back in the response. There are no jobs to poll for the core tools.
Synchronous by default
A synchronous call blocks until the work is done and returns the result directly — a download URL, a streamed file, or an inline JSON payload (see Sending & receiving files). The response also carries X-Credits-Charged, so you know the exact cost the moment the call returns.
This is true of compression, conversion, the page tools, watermarks, OCR, PDF→Markdown, the AI tools, analysis, and the compliance tools — effectively the whole reference.
No job polling
Because the work finishes in-request, the self-serve tools don’t expose a job queue. Some responses include a job_id or conversion_id, but these are fresh identifiers, not queryable job handles — there’s no status endpoint to poll them against, and you shouldn’t build polling loops around them. The result is already in the response you received.
Batch & certificate jobs
The heavyweight async certificate/job system (persisted jobs, progress, WebSocket updates) isn’t part of the live self-serve API. Bulk certificates is synchronous too — it renders every row and streams the ZIP back in one request.Long calls & timeouts
A few tools do real work that takes seconds — an AI translation of a long PDF, a vision OCR pass, a Chromium HTML render. Since these are synchronous, set a generous client-side timeout (tens of seconds, not the default few) so your HTTP client doesn’t abort before the response arrives. The AI tools use map-reduce/chunking internally, so larger inputs take proportionally longer while still returning in a single response.
Where async shows up
The one genuinely asynchronous surface is delivery notifications, not tool execution:
- Webhooks deliver out-of-band after the fact. If you want a push when something happens rather than reading a synchronous response, that’s the mechanism — subject to which events currently fire.
For everything else, model your integration as request → response. It keeps error handling and retries simple — see Idempotency & retries.