---
title: "Create an agent run"
method: POST
path: "/v1/agents"
tags: ["public-api"]
---

# Create an agent run

`POST /v1/agents`

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](/files) and
[Errors and retries](/api/errors) guides.

## Request body

- PublicCreateAgentRequest
  - `files` PublicAgentFileInput[] — Up to 10 files with a combined decoded size of 10 MiB. The API delivers them to the agent's workspace before it processes `input_text`, so the input can reference them by filename.
    - `content_base64` string, required — The file's bytes as standard base64 with padding. The API validates it strictly, so don't include MIME line wrapping or newlines.
    - `filename` string, required — The name the file is saved under in the agent's workspace. The API strips path components and leading dots, and may shorten or sanitize unsafe names.
  - `input_text` string, 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.
  - `name` string, required — Display name for the run, shown in the Clicks app.
  - `template_id` string, 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.

## Response `201`

Successful Response

- PublicCreateAgentResponse — Returned immediately; the run executes asynchronously.
  - `agent_id` string, uuid, required — The ID of the created run. Poll `GET /v1/agents/{agent_id}` for its status and transcript.

## Other responses

- `401` — Missing or invalid API key.
- `403` — `template_id` does not match the API key's agent.
- `404` — The API key's agent no longer exists.
- `409` — The agent is archived.
- `413` — Combined decoded file size exceeds 10 MiB.
- `422` — Request validation failed, a file is not valid base64, or the organization has no usable inference model.

---

[API](https://skmtc.dev/goclicks/apis/clicks-agents-api.md) · [All operations](https://skmtc.dev/goclicks/apis/clicks-agents-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/goclicks/clicks-agents-api/revisions/48c124d6f633/schema)