> ## 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. # Run an agent > Create a new task for the specified agent. Two body formats are accepted: - **`multipart/form-data`** — when you need to attach files (PDFs, images, spreadsheets, etc.). Send one `files` part per attachment, plus optional `query` and `output_config` (the latter as a JSON-encoded string field). - **`application/json`** — for text-only runs. Send `query` and an optional structured `output_config` object. Either `query` or at least one file must be provided. The response returns immediately with the new `task_id`. The task itself runs asynchronously — poll `GET /v1/tasks/{task_id}` or `GET /v1/tasks/{task_id}/summary` to retrieve the result. ## OpenAPI ````yaml POST /api/v1/agents/{agent_id}/run openapi: 3.1.0 info: title: Nanonets Agents Platform — Public API version: 1.0.0 summary: >- Programmatically run AI agents, send follow-up messages, fetch results, and update agent prompts. description: > The Nanonets Agents Platform Public API lets you trigger agents, stream task progress, and integrate agent outputs into your own systems. ## Authentication All requests must include a workspace API key as a Bearer token: ``` Authorization: Bearer YOUR_API_KEY ``` Workspace API keys are minted from the web app under **Settings → API Keys**. Each key is scoped to a single workspace; requests against agents or tasks outside that workspace return `403`. ## Lifecycle A typical integration is three calls: 1. `POST /v1/agents/{agent_id}/run` — start a task. Returns a `task_id` immediately. 2. Poll `GET /v1/tasks/{task_id}` until `status` is a terminal value (`completed`, `failed`, or `stopped`), **or** wait until it reaches `waiting_for_input` to respond with `POST /v1/tasks/{task_id}/message`. 3. `GET /v1/tasks/{task_id}/summary` for the final answer, or `/result` for the full reasoning trace. ## Errors Every error response is `{"error": ""}`. The HTTP status indicates the class: | Status | Meaning | |--------|---------| | 400 | Malformed request (bad UUID, missing required field, file too large) | | 401 | Missing or invalid API key | | 403 | API key is valid but the agent/task belongs to a different workspace | | 404 | Agent or task not found | | 500 | Server error — safe to retry with backoff | contact: name: Nanonets Support url: https://nanonets.com/support license: name: Proprietary servers: - url: https://agents.nanonets.com description: Production security: - bearerAuth: [] tags: - name: Agents description: Manage agents — create, list, update, run, and version. - name: Tasks description: >- Inspect task status, fetch results, list and cancel tasks, and send follow-up messages. paths: /api/v1/agents/{agent_id}/run: post: tags: - Agents summary: Run an agent description: > Create a new task for the specified agent. Two body formats are accepted: - **`multipart/form-data`** — when you need to attach files (PDFs, images, spreadsheets, etc.). Send one `files` part per attachment, plus optional `query` and `output_config` (the latter as a JSON-encoded string field). - **`application/json`** — for text-only runs. Send `query` and an optional structured `output_config` object. Either `query` or at least one file must be provided. The response returns immediately with the new `task_id`. The task itself runs asynchronously — poll `GET /v1/tasks/{task_id}` or `GET /v1/tasks/{task_id}/summary` to retrieve the result. operationId: runAgent parameters: - $ref: '#/components/parameters/AgentIdPath' requestBody: required: true content: multipart/form-data: schema: type: object properties: query: type: string description: Prompt text. Optional when one or more files are attached. files: type: array description: > One or more file attachments (PDF, image, Word, Excel, etc.). Repeat the `files` field per attachment. The legacy field name `file` is also accepted for a single upload. items: type: string format: binary output_config: type: string description: > JSON-encoded `TaskOutputConfig` — submitted as a string field in multipart bodies. Supports `output_schema` and `instructions`. See the `RunAgentRequest` schema for the structured equivalent. version: type: integer description: >- Optional. Run a specific published version. See the `RunAgentRequest` schema. required: [] application/json: schema: $ref: '#/components/schemas/RunAgentRequest' examples: simple: summary: Text-only query value: query: Summarize the attached invoice. withSchema: summary: Query + structured output schema value: 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. responses: '201': description: Task created. content: application/json: schema: $ref: '#/components/schemas/RunAgentResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' components: parameters: AgentIdPath: name: agent_id in: path required: true description: UUID of the agent. schema: type: string format: uuid schemas: RunAgentRequest: type: object description: >- JSON variant of the run-agent request body. See the multipart variant for file uploads. properties: query: type: string description: >- Prompt or instruction for the agent. Required unless files are attached (multipart only). output_config: $ref: '#/components/schemas/TaskOutputConfig' version: type: integer description: > Optional. Run this specific published version (e.g. `2`). When omitted, the agent's active published version runs. The API always runs a published version — it cannot run the working draft, so publish a version to test it. An agent with nothing published yet returns `409 no_published_version`. RunAgentResponse: type: object required: - task_id - agent_id - status - message - created_at properties: task_id: type: string format: uuid agent_id: type: string format: uuid status: $ref: '#/components/schemas/TaskStatus' message: type: string description: >- Human-readable hint, e.g. "Task created successfully. Use GET /v1/tasks/{task_id} to check status." created_at: type: string format: date-time TaskOutputConfig: type: object description: > Optional per-task output shaping. Both fields are optional individually but at least one should be set if the object is provided. properties: output_schema: type: string description: > JSON or natural-language schema describing the desired `extracted_data` shape. Overrides any dashboard-defined key definitions for this task. instructions: type: string description: Plain-text instructions appended to the LLM's output-format prompt. TaskStatus: type: string description: > Lifecycle status of a task. - `pending` — created, not yet picked up - `queued` — held back by admission control (agent at concurrent-task limit) - `running` — being processed by the worker - `waiting_for_input` — agent called `ask_user`; reply with `POST /tasks/{id}/message` - `awaiting_review` — agent is paused for human approval of a sensitive step - `completed` — terminal: finished successfully - `failed` — terminal: errored out - `stopped` — terminal: cancelled by a user or system enum: - pending - queued - running - waiting_for_input - awaiting_review - completed - failed - stopped Error: type: object required: - error properties: error: type: string description: Human-readable error message. examples: - Invalid agent_id format responses: BadRequest: description: >- Malformed request — invalid UUID, missing required field, or oversized file. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: API key is valid but the resource belongs to a different workspace. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Agent or task not found. content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: Unexpected server error. Safe to retry with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: | Workspace API key issued from the web app. Pass as `Authorization: Bearer YOUR_API_KEY`. ````