> ## 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. # Send task message > Append a user message to an existing task. Used when an agent is in `waiting_for_input` (it called `ask_user`) or when continuing a conversational task. The orchestrator queues a `new_message` event so the agent can resume. The message is processed asynchronously — poll `GET /v1/tasks/{task_id}` to observe the status change. ## OpenAPI ````yaml POST /api/v1/tasks/{task_id}/message 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/tasks/{task_id}/message: post: tags: - Tasks summary: Send a follow-up message to a task description: > Append a user message to an existing task. Used when an agent is in `waiting_for_input` (it called `ask_user`) or when continuing a conversational task. The orchestrator queues a `new_message` event so the agent can resume. The message is processed asynchronously — poll `GET /v1/tasks/{task_id}` to observe the status change. operationId: sendTaskMessage parameters: - $ref: '#/components/parameters/TaskIdPath' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendMessageRequest' responses: '201': description: Message accepted and queued for the agent. content: application/json: schema: $ref: '#/components/schemas/SendMessageResponse' '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: TaskIdPath: name: task_id in: path required: true description: UUID of the task. schema: type: string format: uuid schemas: SendMessageRequest: type: object required: - message properties: message: type: string description: Text to deliver to the agent as a user message. SendMessageResponse: type: object required: - task_id - message_id - status - message - created_at properties: task_id: type: string format: uuid message_id: type: string format: uuid description: ID of the newly created task message. status: $ref: '#/components/schemas/TaskStatus' message: type: string description: Human-readable acknowledgement. created_at: type: string format: date-time 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`. ````