Run an agent - Nanonets Agents Platform

curl --request POST \ --url https://agents.nanonets.com/api/v1/agents/{agent_id}/run \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: multipart/form-data' \ --form 'query=<string>' \ --form 'files=<string>' \ --form 'output_config=<string>' \ --form files.items='@example-file'

Authorizations

Authorization

string

header

required

Workspace API key issued from the web app. Pass as Authorization: Bearer YOUR_API_KEY.

Path Parameters

agent_id

string<uuid>

required

UUID of the agent.

Body

query

string

Prompt text. Optional when one or more files are attached.

files

file[]

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.

output_config

string

JSON-encoded TaskOutputConfig — submitted as a string field in multipart bodies. Supports output_schema and instructions. See the RunAgentRequest schema for the structured equivalent.

Response

Task created.

task_id

string<uuid>

required

agent_id

string<uuid>

required

status

enum<string>

required

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

Available options:

pending,

queued,

running,

waiting_for_input,

awaiting_review,

completed,

failed,

stopped

message

string

required

Human-readable hint, e.g. "Task created successfully. Use GET /v1/tasks/{task_id} to check status."

created_at

string<date-time>

required