API · Queries

Ask a question

POST


        /api/v1/documents/{id}/queries

Model tokens (the document is cached after the first question)

Answers from the document's text and images with page citations. Give a JSON schema to get a structured answer. Runs synchronously and returns 200 when it finishes in time; send "async": true (or wait for a 202) and poll the query instead. When the workspace already has several questions running it also answers 202, and the question runs in the background. Repeated questions over the same document reuse a cached prompt prefix.

A 200 can carry status: "failed" with an error: type is insufficient_credits (the credit left cannot cover this question's estimate), document_too_large (too long for the model you chose), document_expired, schema_mismatch or query_failed. A 402 means the workspace has no credit left at all.

Path parameters

id string required

The document's id.

Body application/json

question string required

What you want to know, in plain words.

at most 4000 characters
async boolean optional default false

true answers 202 straight away with a poll_url, instead of waiting for the answer.
instructions string optional

How to answer: length, units, what to do when unsure.

at most 4000 characters
model auto | swift | summit optional default auto

Which model answers: swift (fast, economical), summit (most capable) or auto (by the document's size).
schema object optional

A JSON Schema (type: object) the answer must follow. With one, answer.answer is an object you can store; without, it is a sentence.

Returns 200

Answered

id string

The query's id.
object string

Always query.
answer QueryAnswer

The answer, once status is completed. See QueryAnswer.
4 fields
- answer object
  
  A string, or an object following the query's schema.
- citations array of object
  
  Every page and quote the answer came from.
  2 fields
  
  page integer
  
  quote string
- confidence number
  
  How sure the model is, from 0 to 1.
  
  at least 0 · at most 1
- not_found boolean
  
  true when the document does not answer the question.
completed_at string

When it was answered.
cost object

Held, then charged, in micro-USD.
2 fields
- estimated_micro integer
- settled_micro integer
created_at string

When you asked.
document_id string

The document it was asked of.
error object

Why it failed.
2 fields
- message string
- type insufficient_credits | document_too_large | document_expired | schema_mismatch | query_failed
instructions string

The instructions you sent, if any.
model object

The model you asked for and the one that answered.
2 fields
- requested string
- used string
question string

What you asked.
schema object

The JSON Schema you asked the answer to follow, if any.
status queued | processing | completed | failed

completed means answer is ready; failed means read error.

Errors

401
Missing, revoked or expired key
402
No credits left, or (for an upload) not enough for its estimated cost. A URL document or a question whose estimate the credit cannot cover is accepted and then fails with error.type: insufficient_credits.
404
No document or query with that id for this key (documents are scoped to the key's workspace and live/test mode)
409
The document has not finished processing
410
Retention ran out and the result was purged
422
Body or options failed validation (details lists the fields), or the document is too large (document_too_large)
429
Per-second burst limit for the plan exceeded; retry after Retry-After seconds

Every error has the same shape. See Errors.

Request

curl -X POST "$NORTHDOC_API/documents/$DOC_ID/queries" \
  -H "Authorization: Bearer $NORTHDOC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Who are the parties to this agreement?"}'

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"},
            "late_fee_pct":   {"type": "number"},
            "currency":       {"type": "string"}
          },
          "required": ["net_days"]
        }
      }'

curl -X POST "$NORTHDOC_API/documents/$DOC_ID/queries" \
  -H "Authorization: Bearer $NORTHDOC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "question": "Summarise the indemnity obligations.",
        "instructions": "Answer in at most three sentences. Quote clause numbers. Say so if the document is silent.",
        "model": "summit"
      }'

curl -X POST "$NORTHDOC_API/documents/$DOC_ID/queries" \
  -H "Authorization: Bearer $NORTHDOC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "List every obligation with its deadline.", "async": true}'

Returns 200 with the answer when it finishes in time. citations point at the pages and quotes the answer came from; not_found is true when the document does not say.

Response

{
  "id": "c0de1234-…",
  "status": "completed",
  "answer": {
    "answer": "Acme Robotics (vendor) and Jane Doe (purchaser).",
    "citations": [{"page": 1, "quote": "between Acme Robotics and Jane Doe"}],
    "confidence": 0.92,
    "not_found": false
  }
}

{
  "status": "completed",
  "answer": {
    "answer": {"net_days": 30, "late_fee_pct": 1.5, "currency": "USD"},
    "citations": [{"page": 3, "quote": "Payment is due net 30 days"}],
    "confidence": 0.88,
    "not_found": false
  }
}

{
  "id": "c0de1234-…",
  "object": "query",
  "document_id": "8f1c2d3e-…",
  "status": "queued",
  "poll_url": "https://northdoc.northcape.tech/api/v1/documents/8f1c2d3e-…/queries/c0de1234-…"
}

{
  "answer": {
    "answer": "Acme Robotics (vendor) and Jane Doe (purchaser).",
    "citations": [
      {
        "page": 1,
        "quote": "between Acme Robotics and Jane Doe"
      }
    ],
    "confidence": 0.92,
    "not_found": false
  },
  "cost": {
    "estimated_micro": 2400,
    "settled_micro": 1975
  },
  "document_id": "8f1c…",
  "id": "c0de…",
  "model": {
    "requested": "auto",
    "used": "northdoc-swift-1"
  },
  "object": "query",
  "question": "Who are the parties to this agreement?",
  "status": "completed"
}

{
  "document_id": "8f1c…",
  "id": "c0de…",
  "object": "query",
  "poll_url": "https://northdoc.northcape.tech/api/v1/documents/8f1c…/queries/c0de…",
  "status": "queued"
}

{
  "error": {
    "message": "Missing or invalid API key.",
    "type": "unauthorized"
  }
}

{
  "error": {
    "balance_micro": 0,
    "message": "Your workspace has no credits left.",
    "top_up_url": "https://northdoc.northcape.tech/app/acme-robotics/billing",
    "type": "insufficient_credits"
  }
}

{
  "error": {
    "message": "No such document.",
    "type": "not_found"
  }
}

{
  "error": {
    "message": "The document is processing; queries need a completed document.",
    "status": "processing",
    "type": "document_not_ready"
  }
}

{
  "error": {
    "message": "The document has expired and its results were purged.",
    "type": "document_expired"
  }
}

{
  "error": {
    "details": {
      "markdown": [
        "requires analysis \"layout\""
      ]
    },
    "message": "Invalid options.",
    "type": "invalid_request"
  }
}

{
  "error": {
    "limit": 2,
    "message": "Too many requests. Limit is 2 per second.",
    "retry_after": 1,
    "type": "rate_limited"
  }
}