Choosing an endpoint

Three ways to extract, one price sheet, one result shape. The same JSON comes back from all three, so the choice is about latency and volume rather than capability.

endpoint	answers in	fits
POST /v1/extract	one request, 10–120 s	a small deed, a first try
POST /v1/extracts + poll	milliseconds, then poll	anything that might run long
POST /v1/batches	milliseconds, then poll	volume, and the lowest per-document rate

Synchronous: POST /v1/extract

One document in, the whole extraction back in the same request. Extraction takes 10 to 120 seconds, and a multi-tract instrument can take four minutes.

The catch is the edge: it closes an idle connection at 180 seconds, so this is the wrong shape for a long document. The extraction completes and bills on the server, and then fails in transit before you see a word of it. Curling one small deed and getting JSON back in a single request is worth keeping; a multi-tract instrument belongs on the next path.

Submit and poll: POST /v1/extracts

Answers in milliseconds with a job id and holds nothing open, so the edge timeout stops applying to extraction at all.

job=$(curl -sX POST https://api.easting.ai/v1/extracts \
  -H "authorization: Bearer $EASTING_KEY" \
  -H "content-type: application/pdf" \
  -H "x-document-name: deed.pdf" \
  --data-binary @deed.pdf | jq -r .job)

# Poll every 3 seconds. Cancelling the poll never cancels the extraction:
# the result stays collectable.
until curl -s "https://api.easting.ai/v1/extracts/$job" \
  -H "authorization: Bearer $EASTING_KEY" | jq -e '.status == "succeeded"'; do
  sleep 3
done

A typical deed settles in well under a minute. The quota check happens at submit, counting work already in flight, so a job never settles into a bill you did not agree to. There are no webhooks today: completion is polled, and webhooks arrive when integrators ask for them.

GET /v1/extracts/{job} returns the whole extraction when it is done. Collecting starts the retention clock: the result is cleared seven days after the first fetch and thirty days if nobody ever collects it.

Batch: POST /v1/batches

Up to 50 documents in one submission, all handed to extraction at once. Most batches settle inside an hour and the ceiling is 24. Poll GET /v1/batches/{id}, then fetch GET /v1/batches/{id}/results when the status is ended. The same retention clock applies.

Batch trades latency for cost. On the metered plan the rate slopes to $0.25 a document above 10,000 a month, half the base rate, and that rung requires batch: it is what the volume price pays for. It is also the right path for volume on latency alone: nothing holds a connection open, no concurrency limit applies, and a thousand documents settle together.

A batch is admitted whole or refused whole. A batch past the remaining quota 402s with the numbers before anything runs, because a partly-admitted batch gives you a job you cannot reason about.

Size limits, on every path

path	ceiling
direct body	4.5 MB per request
staged via POST /v1/uploads	32 MB per document
batch, multipart	4.5 MB for the whole body
batch, staged ids	32 MB each, no shared ceiling

The 4.5 MB comes from the hosting platform base64-encoding request bodies, so a batch of five ordinary one-megabyte scans already exceeds it. For anything bigger, POST /v1/uploads returns a presigned slot: PUT the document there, then pass the id in X-Upload-Id (single paths) or an uploads list (batch). The staged object is deleted as it is read, on every plan.

Which one, in one sentence each

• Small deed, interactive use, first integration: /v1/extract.
• Anything that might run long, which in practice is any multi-tract instrument: /v1/extracts.
• A stack of documents, or the $0.25 rate: /v1/batches.

Pricing itself is on the billing page; a failed extraction never bills on any path.