Create an agent run

Start a new agent run from the API key's agent.

The key alone determines the organization and agent. template_id is only a cross-check: if it doesn't match the key's agent, the API returns 403. The API delivers files to the agent's workspace before it processes input_text. The API responds immediately with the run's ID. Because execution is asynchronous, poll GET /v1/agents/{agent_id} for progress.

Besides schema validation, the API also returns 422 when a file is not valid base64 or when the organization has no usable inference model.

See the Sending files and Errors and retries guides.

Request body

input_textstring nullable

The agent's first input. Always send it: without it, the API creates the run but never starts a turn — the idle run reports finished until someone provides input in the Clicks app, and may be stopped automatically.

namestring required

Display name for the run, shown in the Clicks app.

template_idstring uuid required

The ID of the agent that the API key belongs to. The key determines which agent runs; this field is only a cross-check, and a mismatch returns 403.

Example request

{
  "files": [
    {
      "content_base64": "JVBERi0xLjcK...",
      "filename": "report.pdf"
    }
  ],
  "input_text": "Summarize report.pdf in three bullet points.",
  "name": "Weekly report run",
  "template_id": "8a03e45e-1c2b-4f6a-9b1e-3d5c7a9e0f42"
}

Response

Successful Response

agent_idstring uuid required

The ID of the created run. Poll GET /v1/agents/{agent_id} for its status and transcript.

Example response

{
  "agent_id": "0f4d3f9a-6b1c-4a2e-8c7d-5e9b0a1f2c3d"
}