> ## Documentation Index > Fetch the complete documentation index at: https://docs.goclicks.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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](/files) and [Errors and retries](/api/errors) guides. ## OpenAPI ````yaml openapi.mintlify.json POST /v1/agents openapi: 3.1.0 info: description: >- Run your configured Clicks agents programmatically: create an agent run and poll its status and transcript. Authenticate with a per-agent API key created on the agent's **API access** tab. Send it as `Authorization: Bearer ` (preferred) or `X-API-Key: `. title: Clicks Agents API version: '1.0' servers: - description: US production url: https://app.us.goclicks.ai security: - bearerAuth: [] - apiKeyHeader: [] tags: - description: Create agent runs and read their status and transcript. name: public-api x-displayName: Agents paths: /v1/agents: post: tags: - public-api summary: Create an agent run description: >- 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. operationId: public_create_agent requestBody: content: application/json: schema: $ref: '#/components/schemas/PublicCreateAgentRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/PublicCreateAgentResponse' description: Successful Response '401': content: application/json: schema: $ref: '#/components/schemas/PublicErrorResponse' description: Missing or invalid API key. '403': content: application/json: schema: $ref: '#/components/schemas/PublicErrorResponse' description: '`template_id` does not match the API key''s agent.' '404': content: application/json: schema: $ref: '#/components/schemas/PublicErrorResponse' description: The API key's agent no longer exists. '409': content: application/json: schema: $ref: '#/components/schemas/PublicErrorResponse' description: The agent is archived. '413': content: application/json: schema: $ref: '#/components/schemas/PublicErrorResponse' description: Combined decoded file size exceeds 10 MiB. '422': description: >- Request validation failed, a file is not valid base64, or the organization has no usable inference model. x-codeSamples: - lang: bash label: cURL source: |- 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": "", "input_text": "Summarize the latest AI news." }' - lang: python label: Python source: |- 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": "", "input_text": "Summarize the latest AI news.", }, ) resp.raise_for_status() print(resp.json()["agent_id"]) components: schemas: 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 properties: 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. items: $ref: '#/components/schemas/PublicAgentFileInput' maxItems: 10 title: Files type: array input_text: anyOf: - type: string - type: 'null' 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. title: Input Text name: description: Display name for the run, shown in the Clicks app. maxLength: 200 minLength: 1 title: Name type: string 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. format: uuid title: Template Id type: string required: - name - template_id title: PublicCreateAgentRequest type: object PublicCreateAgentResponse: description: Returned immediately; the run executes asynchronously. examples: - agent_id: 0f4d3f9a-6b1c-4a2e-8c7d-5e9b0a1f2c3d properties: agent_id: description: >- The ID of the created run. Poll `GET /v1/agents/{agent_id}` for its status and transcript. format: uuid title: Agent Id type: string required: - agent_id title: PublicCreateAgentResponse type: object PublicErrorResponse: description: |- Error body for failures other than request validation. 422 schema violations use FastAPI's list-of-issues ``detail`` shape instead. properties: detail: description: Human-readable reason for the failure. title: Detail type: string required: - detail title: PublicErrorResponse type: object PublicAgentFileInput: description: A file delivered to the agent's workspace before it starts working. properties: 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. minLength: 1 title: Content Base64 type: string 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. maxLength: 255 minLength: 1 title: Filename type: string required: - filename - content_base64 title: PublicAgentFileInput type: object securitySchemes: bearerAuth: description: API key (`ak_...`) as a Bearer token. Preferred. scheme: bearer type: http apiKeyHeader: description: >- API key (`ak_...`) as a header. Used only when the `Authorization` header is missing or not a Bearer credential. in: header name: X-API-Key type: apiKey ````