Guides

Asking questions

Questions answered while a document is read, and follow-up questions afterwards, with cited answers.

In short: send the questions you already know with the file, and ask new ones later. Each answer comes with its page and quote, or not_found: true when the document does not say.

With the file: options.queries

Up to 50 questions, answered while the document is being read (20 to a model call). Answers land in result.answers in the order you asked. The cheapest way to ask.

Later: POST /documents/{id}/queries

One question at a time, on a completed document. Add a JSON schema to get an object back instead of a sentence, instructions to steer it, or model to choose the model.

A question usually answers in a few seconds with 200. If it takes longer than three minutes, or you send "async": true, you get 202 and a poll_url instead. Handle both.
The first question caches the document for five minutes, and each question after it resets the clock. Questions in that window pay about a tenth of the price for the document part, whatever their schema. Ask a batch one after another, not all at once, so the first one has cached it.
Questions you send with the upload (queries) share that cache with the extraction, so the document is paid in full once, not once per call.
Questions see the document's images too, for as long as the document is kept.

terminal

# answered during ingest, while the document is already in context
curl -X POST "$NORTHDOC_API/documents" \
  -H "Authorization: Bearer $NORTHDOC_KEY" \
  -F file=@contract.pdf \
  -F 'options={"queries":["Who are the parties?","What is the governing law?"]}'
# -> result.answers[], in the order you asked

# asked afterwards, with a structured answer
curl -X POST "$NORTHDOC_API/documents/$DOC_ID/queries" \
  -H "Authorization: Bearer $NORTHDOC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "question": "What are the payment terms?",
        "schema": {"type":"object","properties":{"net_days":{"type":"integer"}},"required":["net_days"]}
      }'
# -> answer.answer is an object matching your schema, with page citations