One engine, four ways in.

An owner creates and revokes keys on the Team page, or from the command line; a member asks an owner. The key is shown once, starts with dk_, and is sent as Authorization: Bearer dk_.... A revoked key's next call is refused with 401.

$ docuoria account keys create --label "My flow"

curl -X POST "https://api.docuoria.com/extract?template=vendor-invoice&ledger=vendor-bills&format=json" \
  -H "Authorization: Bearer dk_..." \
  -H "Content-Type: application/pdf" \
  -H 'Content-Disposition: attachment; filename="vendor-messageId.pdf"' \
  --data-binary @invoice.pdf

To send the PDF in two steps, open a ticket with POST /uploads, send the file with PUT /uploads/{ticket} using the ticket's token and a Content-Disposition header, then call POST /extract with JSON {"document":"<id>","template":"vendor-invoice"}, where the id is the upload receipt's documentId.

Reading the result

A document that does not extract is still HTTP 200. Branch on status (extracted, partial or no-match), then on ledger.action: a row was written only when it is appended, and ledger is null unless status is extracted. Name the template with template=<id>; without it, a document extracts only when it strongly matches one of your saved templates, and a new organisation has none. Add ledger=<id> and format=json to the query; the first document extracted into it creates the ledger, and until then GET /ledgers/{id} answers 404. The result carries output, ledger.rowsAdded and ledger.totalRows.

File names

The file name comes from the Content-Disposition header, as attachment; filename="vendor-messageId.pdf", and is the ledger's key for a document it has seen. A second invoice.pdf returns 200 with ledger.action already-present and no row, although the PDF was read again. Name each file uniquely.

Reading a ledger

GET /ledgers/{id} returns the CSV in content up to 200 KB. Above that, content is null and downloadUrl is a single-use link, GET /downloads/{id}, valid for 10 minutes: fetch it at once.

Authoring over REST

Author a template over REST, in this order: GET /reference for the rules, POST /inspect with the PDF, write the template JSON, POST /validate-template, POST /dry-run with the PDF, then POST /templates to save it. Extract with the saved id as template.

Rate limits

On Free, execute and ledger-append calls are limited to 20 a minute. Run a flow one document at a time, and retry after a delay on 429 and 503.

Errors

A refused call returns application/problem+json with code, title and detail. A 401 means a missing or revoked key; owners manage keys on the Team page. A 402 means the organisation holds no live plan; see the Plan page in your account. A 429 means the allowance or the minute window is spent; wait and retry.