> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run your first agent in under five minutes.

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](/docs/authentication) for how to mint one.
* The agent's UUID, visible in the dashboard URL when you open the agent.

## 1. Start a task

<CodeGroup>
  ```bash cURL theme={null}
  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."}'
  ```

  ```python Python theme={null}
  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)
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</CodeGroup>

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

```json Response theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
curl https://agents.nanonets.com/api/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $NANONETS_API_KEY"
```

When `status` becomes `completed`, fetch the answer:

```bash theme={null}
curl https://agents.nanonets.com/api/v1/tasks/$TASK_ID/summary \
  -H "Authorization: Bearer $NANONETS_API_KEY"
```

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

## 4. Reply when the agent asks

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

```bash theme={null}
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 |