{"openapi":"3.1.0","info":{"title":"Clicks Agents API","description":"Run your configured Clicks agents programmatically: create an agent run and poll its status and transcript.\n\nAuthenticate with a per-agent API key created on the agent's **API access** tab. Send it as `Authorization: Bearer <key>` (preferred) or `X-API-Key: <key>`.","version":"1.0"},"paths":{"/v1/agents":{"post":{"tags":["public-api"],"summary":"Create an agent run","description":"Start a new agent run from the API key's agent.\n\nThe key alone determines the organization and agent. ``template_id`` is\nonly a cross-check: if it doesn't match the key's agent, the API returns\n403. The API delivers files to the agent's workspace before it processes\n``input_text``. The API responds immediately with the run's ID. Because\nexecution is asynchronous, poll ``GET /v1/agents/{agent_id}`` for progress.\n\nBesides schema validation, the API also returns 422 when a file is not\nvalid base64 or when the organization has no usable inference model.\n\nSee the [Sending files](/files) and\n[Errors and retries](/api/errors) guides.","operationId":"public_create_agent","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCreateAgentRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCreateAgentResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"403":{"description":"`template_id` does not match the API key's agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"404":{"description":"The API key's agent no longer exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"409":{"description":"The agent is archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"413":{"description":"Combined decoded file size exceeds 10 MiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"422":{"description":"Request validation failed, a file is not valid base64, or the organization has no usable inference model."}}}},"/v1/agents/{agent_id}":{"get":{"tags":["public-api"],"summary":"Get an agent run","description":"Return an agent run's status and transcript.\n\nPoll every 3 to 10 seconds while ``loop_status`` is ``running``. Runs\ncommonly take several minutes. For the status values, see the\n[Agent lifecycle and polling](/agent-lifecycle) guide.\n\nThe response is scoped to the API key: a run that belongs to another\norganization or agent returns 404, so a key can't enumerate or inspect\nruns it doesn't own.","operationId":"public_get_agent","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentStatusResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"404":{"description":"No run with this ID is visible to the API key. Runs that belong to another organization or agent also return 404, the same as a nonexistent ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"502":{"description":"The event history lookup failed. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"503":{"description":"Event history is temporarily unavailable. Retry with backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/openapi.json":{"get":{"tags":["public-api"],"summary":"Download the OpenAPI schema","description":"Return the OpenAPI 3.1 document that describes this API.\n\nThe document is the same contract this reference renders from. Use it to\ngenerate typed clients. The endpoint requires no authentication.","operationId":"public_get_openapi_schema","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Public Get Openapi Schema"}}}}},"security":[]}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PublicAgentFileInput":{"properties":{"filename":{"type":"string","maxLength":255,"minLength":1,"title":"Filename","description":"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."},"content_base64":{"type":"string","minLength":1,"title":"Content Base64","description":"The file's bytes as standard base64 with padding. The API validates it strictly, so don't include MIME line wrapping or newlines."}},"type":"object","required":["filename","content_base64"],"title":"PublicAgentFileInput","description":"A file delivered to the agent's workspace before it starts working."},"PublicAgentStatusResponse":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"loop_status":{"type":"string","enum":["running","finished","technical_error","terminated"],"title":"Loop Status","description":"`running`: the agent is working, which includes startup. `finished`: the agent is idle; when it ended its turn normally, the output for the last input is complete. `technical_error`: the run hit an internal error. `terminated`: the run was stopped or deleted."},"transcript":{"items":{"$ref":"#/components/schemas/TranscriptMessage"},"type":"array","title":"Transcript","description":"The inputs the agent accepted and each turn's final output, ordered oldest first. It doesn't include intermediate tool steps. An empty transcript early in a run is normal."}},"type":"object","required":["agent_id","loop_status","transcript"],"title":"PublicAgentStatusResponse","examples":[{"agent_id":"0f4d3f9a-6b1c-4a2e-8c7d-5e9b0a1f2c3d","loop_status":"finished","transcript":[{"role":"input_to_agent","text":"Summarize report.pdf in three bullet points."},{"role":"output_from_agent","text":"1. Revenue grew 12% ..."}]}]},"PublicCreateAgentRequest":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Display name for the run, shown in the Clicks app."},"template_id":{"type":"string","format":"uuid","title":"Template Id","description":"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."},"input_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Input Text","description":"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."},"files":{"items":{"$ref":"#/components/schemas/PublicAgentFileInput"},"type":"array","maxItems":10,"title":"Files","description":"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."}},"type":"object","required":["name","template_id"],"title":"PublicCreateAgentRequest","examples":[{"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"}]},"PublicCreateAgentResponse":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"The ID of the created run. Poll `GET /v1/agents/{agent_id}` for its status and transcript."}},"type":"object","required":["agent_id"],"title":"PublicCreateAgentResponse","description":"Returned immediately; the run executes asynchronously.","examples":[{"agent_id":"0f4d3f9a-6b1c-4a2e-8c7d-5e9b0a1f2c3d"}]},"PublicErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail","description":"Human-readable reason for the failure."}},"type":"object","required":["detail"],"title":"PublicErrorResponse","description":"Error body for failures other than request validation. 422 schema\nviolations use FastAPI's list-of-issues ``detail`` shape instead."},"TranscriptMessage":{"properties":{"role":{"type":"string","enum":["input_to_agent","output_from_agent"],"title":"Role","description":"`input_to_agent` is an input the agent accepted; `output_from_agent` is a turn's final output."},"text":{"type":"string","title":"Text"}},"type":"object","required":["role","text"],"title":"TranscriptMessage"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (`ak_...`) as a Bearer token. Preferred."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key (`ak_...`) as a header. Used only when the `Authorization` header is missing or not a Bearer credential."}}},"tags":[{"name":"public-api","description":"Create agent runs and read their status and transcript.","x-displayName":"Agents"}],"servers":[{"url":"https://app.us.goclicks.ai/api/orchestrator","description":"US production"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}]}