Files and structured output

Attach files to a run, and shape the response into a JSON schema you control.

POST /v1/agents/{agent_id}/run takes two flavours of body. Use JSON for text-only runs; use multipart/form-data whenever you need to attach files.

Attach one or more files

Send the request as multipart/form-data and add a files field per attachment.

cURL

curl -X POST https://agents.nanonets.com/api/v1/agents/$AGENT_ID/run \
  -H "Authorization: Bearer $NANONETS_API_KEY" \
  -F "query=Extract line items from this invoice." \
  -F "files=@invoice.pdf" \
  -F "files=@invoice-back.pdf"

Either query or at least one file is required. You can send files with no text query if the agent’s system prompt fully covers what to do with them.

Shape the output with output_config

By default, the agent’s extracted_data follows the key definitions configured in the dashboard. To override that per-task, send an output_config object:

{
  "output_config": {
    "output_schema": "{\"line_items\": [{\"sku\": \"string\", \"qty\": \"number\"}]}",
    "instructions": "Group multi-line descriptions into a single SKU."
  }
}

Both fields are optional individually:

• output_schema: a JSON or natural-language schema describing the desired shape. Strings, numbers, arrays, and nested objects are all supported. This overrides any dashboard-defined keys for this task.
• instructions: free-text guidance appended to the LLM’s output-format prompt. Use this for hints that don’t fit cleanly in the schema (“dates as YYYY-MM-DD”, “skip header rows”, etc.).

JSON body: text + schema

cURL

curl -X POST https://agents.nanonets.com/api/v1/agents/$AGENT_ID/run \
  -H "Authorization: Bearer $NANONETS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Extract line items from this purchase order.",
    "output_config": {
      "output_schema": "{\"line_items\": [{\"sku\": \"string\", \"qty\": \"number\"}]}",
      "instructions": "Group multi-line descriptions into a single SKU."
    }
  }'

Multipart body: files + schema

When sending files, output_config is a string field carrying the JSON payload:

curl -X POST https://agents.nanonets.com/api/v1/agents/$AGENT_ID/run \
  -H "Authorization: Bearer $NANONETS_API_KEY" \
  -F "query=Extract line items from this invoice." \
  -F "files=@invoice.pdf" \
  -F 'output_config={"output_schema":"{\"line_items\":[{\"sku\":\"string\",\"qty\":\"number\"}]}"}'

The multipart output_config value must be a JSON-encoded string. JSON inside multipart is a string field by convention; the server parses it after upload.

Reading the structured result

The schema’d object has its own endpoint. /summary returns the agent’s final written answer and /result returns the whole reasoning transcript — neither is the structured payload.

curl https://agents.nanonets.com/api/v1/tasks/$TASK_ID/structured-response \
  -H "Authorization: Bearer $NANONETS_API_KEY"

Response

{
  "task_id": "f1c2a3b4-...",
  "agent_id": "9a8b7c6d-...",
  "status": "completed",
  "structured_response": {
    "line_items": [
      { "sku": "ABC-001", "qty": 12 },
      { "sku": "ABC-002", "qty": 4 }
    ]
  }
}

Short of an infrastructure failure, the call answers 200 whenever the task exists in your workspace, so branch on which field came back rather than on the status code:

Field	Meaning
structured_response	The output is ready.
message	The run is still going (pending, queued, running, waiting_for_input, awaiting_review). Poll again.
error	Nothing will arrive — no output schema is configured, or the run finished without writing one.

Running with ?async=false&result=structured returns this same payload on the run call itself, so a short run needs no polling at all. See Async and polling.

Citations: where each value came from

Add ?include_citations=true to get the place in the source document each value was read from, so a field can be linked or highlighted back to the page it came from.

curl "https://agents.nanonets.com/api/v1/tasks/$TASK_ID/structured-response?include_citations=true" \
  -H "Authorization: Bearer $NANONETS_API_KEY"

Response

{
  "structured_response": {
    "invoice_number": {
      "value": "INV-1043",
      "bounding_boxes": [
        {
          "citation_id": 41,
          "file": "invoice.pdf",
          "page": 1,
          "bounding_box": [812, 190, 1015, 222],
          "normalized_bounding_box": [
            { "x": 0.477, "y": 0.086 },
            { "x": 0.596, "y": 0.086 },
            { "x": 0.596, "y": 0.101 },
            { "x": 0.477, "y": 0.101 }
          ]
        }
      ]
    }
  },
  "documents": [
    {
      "file": "invoice.pdf",
      "url": "https://files.nanonets.com/...",
      "pages": [{ "page": 1, "width": 1700, "height": 2200 }]
    }
  ]
}

Two switches, and both must be on:

1. Keep citations on the agent (Configure → structured output) decides whether citations are produced. Off by default.
2. include_citations=true on the request decides whether they are returned.

They are separate so that switching the agent setting on for the dashboard never changes the bytes an existing API client already parses. Without the query parameter you always get plain values, citations or not; with it on an agent that keeps none, the payload comes back unchanged and documents is omitted — not an error.

Reading the boxes:

• Only leaves with a document source get wrapped. A value from a database lookup or computed by the agent stays a plain value, so handle both shapes.
• Prefer normalized_bounding_box — polygon vertices in 0–1, origin top-left. It renders at any scale. bounding_box is [x1, y1, x2, y2] in absolute pixels and only means something against the width/height for that file and page in documents.
• Always read file. A run that split or processed several documents folds them all into one structured output, so a page number alone does not identify a page.
• Spreadsheet sources carry sheet/cell/row/column and text sources carry line_start/line_end instead of a box.
• documents[].url is time-limited, and absent for a file that cannot be resolved (deleted, or generated by a tool rather than uploaded). The citation is still valid; it just cannot be rendered from that response.

include_citations=true also works on POST /v1/agents/{agent_id}/run with async=false&result=structured, where the documents block comes back as result_documents.

Use /result if you need the full reasoning trail (every tool call the agent made along the way). It’s useful during development, overkill in production.