Inline is for the first file
wait=true is the right call while you inspect Markdown and DocIR. It is a poor contract for a file that takes longer than the request should stay open.
The same endpoint accepts multipart, raw bytes with x-filename, or a permitted HTTPS URL.
The job has states
A production client needs to tell queued, running, succeeded, failed, and canceled apart. A pending result is not a 404 and not an empty document.
Idempotency keys stop a retry from parsing the same upload twice. The free workspace allows one active job.
Webhooks leave the network
A webhook is an outbound request. Sign it. Allow only the hosts the workspace listed. Reject private addresses and recheck redirects.
If delivery fails, the job result is still available to poll. The webhook is a notification, not the only copy of the parse.
Status codes worth branching on
wait=true returns 200 when the inline parse finishes. The default, without that flag, returns 202 while the job is queued, running, or retrying, and the body includes links to poll. A trial workspace allows one active job, 20 text-based documents, 200 MB per month, and 20 MB per upload.
A trial request that sets fastMode, highFidelity, or suspectedScanned, or that uploads an image, returns 403. The message says trial workspaces use deterministic parsing only. An Idempotency-Key reused with a different body returns 409. Poll the job when the webhook does not arrive.
The 202 body is the job acceptance, not the Markdown. Poll the links until the job is no longer queued, running, or retrying. A finished inline call is HTTP 200. The trial allows one active job. A second request while that job is still active returns 429 and the message Tenant concurrent job capacity is exhausted. Retry after the returned delay. The 409 message is Idempotency-Key was already used with a different request. Polling remains the fallback. A free job slot does not change the 403 on image, fastMode, highFidelity, or suspectedScanned.
- Use wait=true while you inspect the first file.
- Branch on 200, 202, 403, and 409.
- Send Idempotency-Key on retries.
- Treat the webhook as a notification and keep polling as the fallback.
The file to send
Run the curl below first. wait=true returns HTTP 200 and result.markdown is in that body. Drop the flag when the client should accept HTTP 202 and poll the job links. The 202 body is acceptance, not Markdown.
The trial allows one active job. A second request while that job is still active returns HTTP 429, Tenant concurrent job capacity is exhausted, with retryAfter. It does not wait on the server. A free slot does not remove the HTTP 403 on image, fastMode, highFidelity, or suspectedScanned.
- Poll if the webhook never arrives.
- Send a new Idempotency-Key when the bytes change.
- The same key with a different body returns HTTP 409.
export DOCPARSE_URL="https://docparse.genedai.me"
export DOCPARSE_API_KEY="your_key"
curl -fsS -X POST \
"$DOCPARSE_URL/v1/parse?wait=true" \
-H "Authorization: Bearer $DOCPARSE_API_KEY" \
-F "file=@document.pdf" \
-F "mode=both" \
-o result.json
jq -r '.result.markdown' result.json
jq '.result.document.schemaVersion, .result.document.pages[0].blockIds' result.json
jq '.result.manifest.decision.route, .result.manifest.parserVersion' result.json
Frequently asked questions
Questions this guide answers
When should I set wait=true?
Set wait=true for a short file while you inspect Markdown and DocIR. The response is 200 when that inline parse finishes. Leave the flag off when the file should return 202 and continue as a job.
How many jobs can a free workspace run?
One active job. The trial also allows 20 text-based documents, 200 MB per month, and 20 MB per upload. Image uploads and fastMode, highFidelity, or suspectedScanned return 403.
What if the webhook never arrives?
Poll the job links from the 202 response. The webhook is a signed notification to an allowed host. The parse result remains available on the job when delivery fails.