Quickstart

To follow this quickstart, you need a Clicks account with a configured agent, that agent’s template ID (shown on its API access tab), and curl or Python with the requests library. The code samples on this page use the base URL https://app.us.goclicks.ai/api/orchestrator/v1.

Mint an API key

In the Clicks app, open Agents → your agent → API access → Create key. Clicks shows the full key (ak_…) only once, so copy it and store it in a secret manager. You can’t retrieve the key later. If you lose it, create a new one.

shell

export CLICKS_API_KEY="ak_..."

Create an agent run

Set template_id to the ID of the agent the key belongs to. The key determines which agent runs; the field is only a cross-check. You can find the ID at the top of the same API access tab.

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 first run",
    "template_id": "<your-agent-template-id>",
    "input_text": "Summarize the latest AI news in three bullet points."
  }'

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 first run",
        "template_id": "<your-agent-template-id>",
        "input_text": "Summarize the latest AI news in three bullet points.",
    },
)
resp.raise_for_status()
agent_id = resp.json()["agent_id"]
print(agent_id)

The response is 201 with only the run’s ID. Because execution is asynchronous, everything else comes from polling:

201 Created

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

Poll until it finishes

Poll every few seconds while loop_status is running. Runs commonly take several minutes. For the status values and backoff guidance, see Agent lifecycle and polling.

curl https://app.us.goclicks.ai/api/orchestrator/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $CLICKS_API_KEY"

import os, time, requests

BASE = "https://app.us.goclicks.ai/api/orchestrator/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['CLICKS_API_KEY']}"}

def wait_until_done(agent_id: str) -> dict:
    while True:
        resp = requests.get(f"{BASE}/agents/{agent_id}", headers=HEADERS)
        resp.raise_for_status()
        run = resp.json()
        if run["loop_status"] != "running":
            return run
        time.sleep(5)

run = wait_until_done(agent_id)
for message in run["transcript"]:
    print(f"[{message['role']}] {message['text']}")

Read the transcript

The transcript includes only the inputs the agent accepted and each turn’s final output. It doesn’t include intermediate tool steps. An empty transcript early in a run is normal.

Always send input_text. Without it, the API creates the run but never starts a turn: loop_status stays running until someone provides input in the Clicks app.

Get started

Guides