Quickstart

This walkthrough kicks off an agent, polls its status, and fetches the final answer: the minimum end-to-end flow.

Prerequisites

A Nanonets workspace with at least one agent.
A workspace API key. See Authentication for how to mint one.
The agent’s UUID, visible in the dashboard URL when you open the agent.

1. Start a task

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": "Summarize the attached document."}'

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": "Summarize the attached document."},
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
print("Task:", task_id)

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}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: "Summarize the attached document." }),
  },
);
const { task_id } = await res.json();
console.log("Task:", task_id);

The response returns a task_id immediately; the agent runs asynchronously.

Response

{
  "task_id": "f1c2a3b4-...",
  "agent_id": "...",
  "status": "running",
  "message": "Task created successfully. Use GET /v1/tasks/{task_id} to check status.",
  "created_at": "2026-05-11T10:15:00Z"
}

2. Attach files (optional)

For agents that take documents as input, send multipart/form-data instead:

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\"}]}"}'

Multiple files are supported; pass files once per file.

3. Poll for the result

Lightweight status check:

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

When status becomes completed, fetch the answer:

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

Use /summary for production polling; it returns just the final result. Use /result during development to see the full reasoning trace.

4. Reply when the agent asks

If the agent needs more input mid-task, the status becomes waiting_for_input. Continue the conversation with:

curl -X POST https://agents.nanonets.com/api/v1/tasks/$TASK_ID/message \
  -H "Authorization: Bearer $NANONETS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Use the second invoice line, not the first."}'

The task resumes asynchronously; poll again until status is terminal.

Terminal vs non-terminal status

Status	Meaning	Next action
`pending`, `queued`, `running`	Still working	Keep polling
`waiting_for_input`	Agent called `ask_user`	Send a `message`
`awaiting_review`	Human approval needed	Approve in the dashboard
`completed`	Done, answer is ready	Fetch `/summary`
`failed`, `stopped`	Terminal, no answer	Inspect `/result` for details

Getting started

Build your agent

Teach your agent

Run tasks & get results

Manage your account

Working with the API

Prerequisites

1. Start a task

2. Attach files (optional)

3. Poll for the result

4. Reply when the agent asks

Terminal vs non-terminal status

​Prerequisites

​1. Start a task

​2. Attach files (optional)

​3. Poll for the result

​4. Reply when the agent asks

​Terminal vs non-terminal status

Prerequisites

1. Start a task

2. Attach files (optional)

3. Poll for the result

4. Reply when the agent asks

Terminal vs non-terminal status