Skip to main content
POST
/
v1
/
agents
cURL
curl -X POST \
  "https://app.us.goclicks.ai/v1/agents" \
  -H "Authorization: Bearer $CLICKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My run",
    "template_id": "<your-agent-template-id>",
    "input_text": "Summarize the latest AI news."
  }'
import os, requests

resp = requests.post(
    "https://app.us.goclicks.ai/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['CLICKS_API_KEY']}"},
    json={
        "name": "My run",
        "template_id": "<your-agent-template-id>",
        "input_text": "Summarize the latest AI news.",
    },
)
resp.raise_for_status()
print(resp.json()["agent_id"])
{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
{
  "detail": "<string>"
}
{
  "detail": "<string>"
}
{
  "detail": "<string>"
}
{
  "detail": "<string>"
}
{
  "detail": "<string>"
}

Authorizations

​
Authorization
string
header
required

API key (ak_...) as a Bearer token. Preferred.

Body

application/json
​
name
string
required

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

Required string length: 1 - 200
​
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.

​
files
PublicAgentFileInput · object[]

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.

Maximum array length: 10
​
input_text
string | null

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.

Response

Successful Response

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.