curl -X POST \
"https://app.us.goclicks.ai/api/orchestrator/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/api/orchestrator/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": "0f4d3f9a-6b1c-4a2e-8c7d-5e9b0a1f2c3d"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}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.
curl -X POST \
"https://app.us.goclicks.ai/api/orchestrator/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/api/orchestrator/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": "0f4d3f9a-6b1c-4a2e-8c7d-5e9b0a1f2c3d"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}Authorizations
API key (ak_...) as a Bearer token. Preferred.
Body
Display name for the run, shown in the Clicks app.
1 - 200The 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.
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.
10Show child attributes
Show child attributes
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.
The ID of the created run. Poll GET /v1/agents/{agent_id} for its status and transcript.