Files and structured output

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 -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"

import os, requests

files = [
    ("files", ("invoice.pdf", open("invoice.pdf", "rb"), "application/pdf")),
    ("files", ("invoice-back.pdf", open("invoice-back.pdf", "rb"), "application/pdf")),
]
resp = requests.post(
    f"https://agents.nanonets.com/api/v1/agents/{os.environ['AGENT_ID']}/run",
    headers={"Authorization": f"Bearer {os.environ['NANONETS_API_KEY']}"},
    data={"query": "Extract line items from this invoice."},
    files=files,
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["task_id"])

import fs from "node:fs";

const form = new FormData();
form.append("query", "Extract line items from this invoice.");
form.append("files", new Blob([fs.readFileSync("invoice.pdf")]), "invoice.pdf");
form.append("files", new Blob([fs.readFileSync("invoice-back.pdf")]), "invoice-back.pdf");

const res = await fetch(
  `https://agents.nanonets.com/api/v1/agents/${process.env.AGENT_ID}/run`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.NANONETS_API_KEY}` },
    body: form,
  },
);
const { task_id } = await res.json();

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 -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."
    }
  }'

import os, requests

resp = requests.post(
    f"https://agents.nanonets.com/api/v1/agents/{os.environ['AGENT_ID']}/run",
    headers={"Authorization": f"Bearer {os.environ['NANONETS_API_KEY']}"},
    json={
        "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

When the task completes, the structured payload is in the summary response under extracted_data:

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

Response

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

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

Getting started

Build your agent

Teach your agent

Run tasks & get results

Manage your account

Working with the API

Attach one or more files

Shape the output with `output_config`

JSON body: text + schema

Multipart body: files + schema

Reading the structured result

​Attach one or more files

​Shape the output with output_config

​JSON body: text + schema

​Multipart body: files + schema

​Reading the structured result

Attach one or more files

Shape the output with `output_config`

JSON body: text + schema

Multipart body: files + schema

Reading the structured result