> ## Documentation Index > Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run agent synchronously > Execute an agent run in a blocking manner and return the complete result once finished. ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json post /api/agents/{agentId}/run-sync openapi: 3.1.0 info: title: Cotool API version: 1.0.0 description: >- # Cotool API Documentation The Cotool API allows you to interact with the Cotool platform programmatically, enabling you to build powerful integrations and automate your workflows. ## Getting an API Key Follow these steps to generate your API key: 1. **Log in** to the Cotool web interface 2. **Navigate** to `/settings/api-keys` 3. **Click** "Generate Key" 4. **Copy and store** your API key securely ⚠️ *It won't be shown again* ## API Key Authentication For programmatic access and integrations, use your API key with the Authorization header: ```http Authorization: Bearer your_api_key_here ``` ```bash curl -X GET "https://app.cotool.ai/api/endpoint" \ -H "Authorization: Bearer your_api_key_here" \ -H "Content-Type: application/json" ``` servers: - url: https://app.cotool.ai description: Production server security: - ApiKeyAuth: [] paths: /api/agents/{agentId}/run-sync: post: tags: - Agents summary: Run agent synchronously description: >- Execute an agent run in a blocking manner and return the complete result once finished. parameters: - in: path name: agentId description: Unique identifier of the agent to execute schema: type: string format: uuid description: Unique identifier of the agent to execute required: true requestBody: content: application/json: schema: type: object properties: inputs: type: object additionalProperties: {} description: >- Input values for agent execution based on agent input configuration. This can be any JSON object and will be stringified as input to the agent. attachments: type: array items: type: object properties: fileId: type: string description: Unique identifier of the uploaded file fileName: type: string description: Name of the file size: type: number description: Size of the file in bytes fileType: type: string enum: - image - pdf - spreadsheet - document - presentation - file description: Semantic file type for iconography previewText: type: string description: Optional text preview for text-like files required: - fileId - fileName - size additionalProperties: false description: >- Optional array of file attachments to include with the agent execution required: - inputs description: >- Input values for agent execution based on agent input configuration responses: '200': description: Successful response content: application/json: schema: type: object properties: finalAssistantMessage: type: string description: The final text response from the assistant allToolCallsMade: type: array items: type: object properties: type: type: string const: tool-call toolCallId: type: string toolName: type: string args: {} required: - type - toolCallId - toolName description: All tool calls made during the agent run allToolResultsReceived: type: array items: type: object properties: type: type: string const: tool-result toolCallId: type: string toolName: type: string result: {} isError: type: boolean required: - type - toolCallId - toolName description: All tool results received during the agent run messages: type: array items: anyOf: - type: object properties: role: type: string const: system content: type: string required: - role - content - type: object properties: role: type: string const: user content: anyOf: - type: string - type: array items: anyOf: - type: object properties: type: type: string const: text text: type: string required: - type - text - type: object properties: type: type: string const: image image: {} mimeType: type: string required: - type - type: object properties: type: type: string const: file data: {} mimeType: type: string required: - type required: - role - content - type: object properties: role: type: string const: assistant content: anyOf: - type: string - type: array items: anyOf: - type: object properties: type: type: string const: text text: type: string required: - type - text - type: object properties: type: type: string const: tool-call toolCallId: type: string toolName: type: string args: {} required: - type - toolCallId - toolName - type: object properties: type: type: string const: reasoning text: type: string signature: type: string required: - type - text - type: object properties: type: type: string const: tool-result toolCallId: type: string toolName: type: string result: {} isError: type: boolean required: - type - toolCallId - toolName - type: object properties: type: type: string const: file data: {} mimeType: type: string required: - type required: - role - content - type: object properties: role: type: string const: tool content: type: array items: type: object properties: type: type: string const: tool-result toolCallId: type: string toolName: type: string result: {} isError: type: boolean required: - type - toolCallId - toolName required: - role - content description: Complete message history from the agent run structuredOutputResult: oneOf: - $ref: '#/components/schemas/JsonValue' - type: 'null' description: Structured output generated after the run, if available required: - finalAssistantMessage - allToolCallsMade - allToolResultsReceived - messages description: Complete result of synchronous agent execution '400': description: Bad request — input validation failed or the request was malformed content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized — missing or invalid API key / session content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — the authenticated user lacks the required permissions content: application/json: schema: $ref: '#/components/schemas/PermissionError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: shell label: cURL source: |- curl -X POST "https://app.cotool.ai/api/agents/:agentId/run-sync" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"inputs":null,"attachments":[{"fileId":"string","fileName":"string","size":0,"fileType":"image","previewText":"string"}]}' components: schemas: JsonValue: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: $ref: '#/components/schemas/JsonValue' - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' description: A JSON value (string, number, boolean, null, array, or object) ValidationError: type: object properties: error: type: string description: Error message describing what went wrong issues: type: array description: >- Detailed validation issues, present when request or response schema validation fails items: type: object additionalProperties: true required: - error Error: type: object properties: error: type: string description: Error message describing what went wrong required: - error PermissionError: type: object properties: error: type: string description: Error message describing what went wrong missingPerms: type: array description: Permissions the authenticated user is missing for this operation items: type: string required: - error securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- API Key authentication for programmatic access. Include your API key in the Authorization header as: `Bearer your_api_key_here` ````