> ## 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. # List all agents > Retrieve a list of all AI agents available in the organization ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json get /api/agents 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: get: tags: - Agents summary: List all agents description: Retrieve a list of all AI agents available in the organization responses: '200': description: Successful response content: application/json: schema: type: array items: oneOf: - type: object properties: id: type: string description: Unique identifier for the agent organizationId: type: string description: >- Unique identifier of the organization that owns this agent name: type: string description: Human-readable name of the agent description: type: string description: Description of what the agent does and its purpose systemPrompt: type: string description: >- The agent's live system prompt (version history lives in agent_versions) createdAt: type: string description: Timestamp when the agent was created updatedAt: type: string description: Timestamp when the agent was last updated deletedAt: type: - string - 'null' description: >- Timestamp when the agent was soft-deleted, or null if not deleted toolNames: type: array items: type: string description: >- Array of tool names that this agent can use during execution toolSelectionMode: type: string enum: - manual - all_read_only description: How this agent resolves tools at runtime cliNames: type: array items: type: string description: >- Optional array of CLI integration ids that this agent can use during execution toolActionConfigs: type: array items: oneOf: - type: object properties: type: type: string const: slack_sendMessage allowedChannels: type: array items: type: object properties: id: type: string minLength: 1 description: >- Slack channel ID (for example C123ABC456) name: type: string minLength: 1 description: 'Slack channel name without the leading #' required: - id - name additionalProperties: false minItems: 1 description: >- Allowlist of Slack channels this agent may access when using this tool action hideAgentButton: type: boolean description: >- When true, omits the "Open Agent Run in Cotool" button from Slack messages produced by this tool action. Defaults to false (button is shown). required: - type additionalProperties: false - type: object properties: type: type: string const: slack_replyToThread allowedChannels: type: array items: type: object properties: id: type: string minLength: 1 description: >- Slack channel ID (for example C123ABC456) name: type: string minLength: 1 description: 'Slack channel name without the leading #' required: - id - name additionalProperties: false minItems: 1 description: >- Allowlist of Slack channels this agent may access when using this tool action hideAgentButton: type: boolean description: >- When true, omits the "Open Agent Run in Cotool" button from Slack messages produced by this tool action. Defaults to false (button is shown). required: - type additionalProperties: false - type: object properties: type: type: string const: slack_readChannelMessages allowedChannels: type: array items: type: object properties: id: type: string minLength: 1 description: >- Slack channel ID (for example C123ABC456) name: type: string minLength: 1 description: 'Slack channel name without the leading #' required: - id - name additionalProperties: false minItems: 1 description: >- Allowlist of Slack channels this agent may access when using this tool action required: - type - allowedChannels additionalProperties: false - type: object properties: type: type: string const: slack_readThreadMessages allowedChannels: type: array items: type: object properties: id: type: string minLength: 1 description: >- Slack channel ID (for example C123ABC456) name: type: string minLength: 1 description: 'Slack channel name without the leading #' required: - id - name additionalProperties: false minItems: 1 description: >- Allowlist of Slack channels this agent may access when using this tool action required: - type - allowedChannels additionalProperties: false - type: object properties: type: type: string const: slack_waitForUserResponse allowedChannels: type: array items: type: object properties: id: type: string minLength: 1 description: >- Slack channel ID (for example C123ABC456) name: type: string minLength: 1 description: 'Slack channel name without the leading #' required: - id - name additionalProperties: false minItems: 1 description: >- Allowlist of Slack channels this agent may access when using this tool action hideAgentButton: type: boolean description: >- When true, omits the "Open Agent Run in Cotool" button from Slack messages produced by this tool action. Defaults to false (button is shown). timeout: type: object properties: amount: type: integer exclusiveMinimum: 0 description: >- Number of units to wait before an unanswered prompt times out. unit: type: string enum: - minutes - hours - days description: Unit for the timeout amount. required: - amount - unit additionalProperties: false description: >- Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing). required: - type additionalProperties: false description: Configuration for a specific tool action description: Per-tool-action configuration for this agent inputs: type: array items: type: object properties: type: type: string enum: - text - image - pdf - audio - video description: The type of input expected by the agent name: type: string description: The name of the input field description: type: string description: A description of what this input is used for required: type: boolean description: >- Whether this input is required for agent execution required: - type - name - description - required description: >- Array of input configurations defining what inputs the agent expects modelAlias: description: >- Model alias specifying which LLM model to use for this agent contextDocs: type: array items: type: object properties: provider: type: string enum: - googleDocs - notion - confluence - mcp id: type: string name: type: string mimeType: type: string required: - provider - id - name description: >- Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent tinesStoryImportId: type: - string - 'null' description: >- Optional reference to the Tines story import template used to create this agent triggerSummary: type: array items: type: object properties: id: type: string description: Unique identifier for the trigger source: type: string enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone description: >- The source platform or system that triggers the agent name: type: string description: Human-readable name for the trigger enabled: type: boolean description: Whether the trigger is currently enabled required: - id - source - name - enabled description: Optional array of triggers configured for this agent planningMode: type: string enum: - auto - never - always description: Planning behavior mode for the agent structuredOutputSchema: oneOf: - $ref: '#/components/schemas/CotoolJsonSchema' - type: 'null' description: >- Optional JSON schema describing the structured output the agent should emit (may include x-cotool metadata for preset UX; metadata is stripped before sending to the LLM) persistentWorkspaceEnabled: type: boolean description: Whether this agent may use persistent workspace tags: type: array items: type: string minLength: 1 maxLength: 100 description: >- A tag label for categorizing agents (normalized to lowercase) description: Array of tags for categorizing the agent skills: type: array items: type: object properties: skillId: type: string format: uuid description: Unique identifier of an attached skill skillVersionId: type: - string - 'null' format: uuid description: >- Pinned version ID, or null/undefined to track latest invocationCount30d: type: number description: >- Distinct chats for this agent in the last 30 days where the skill was read from the sandbox skill: type: object properties: name: type: string pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ minLength: 1 maxLength: 64 description: >- Machine-safe skill name used in sandbox paths and imports description: type: string description: Skill description requiredTools: type: array items: type: string description: Required tool types for this skill required: - name - description - requiredTools description: Skill metadata snapshot required: - skillId - skill description: Array of reusable skills attached to this agent acceptanceCriteria: type: array items: type: string minLength: 1 maxLength: 500 description: >- A user-configured acceptance criterion that must be satisfied for an agent run maxItems: 20 description: >- Optional list of acceptance criteria evaluated for every run agentType: type: string enum: - response - detection description: >- Type of agent: response (standard) or detection (security detection) origin: type: string enum: - user - orchestrator description: 'Who created this agent: user or orchestrator' syncKey: type: - string - 'null' description: >- Stable logical key for the agent (slug, immutable, unique per org) syncSource: type: - string - 'null' description: >- Sync backend managing this agent (e.g. "github"); null/absent when UI-managed syncFilePath: type: - string - 'null' description: >- Path of the source YAML file for a GitOps-managed agent syncConfigId: type: - string - 'null' description: >- Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed detectionCategory: type: - string - 'null' enum: - baseline_anomaly - first_occurrence - sequence_pattern - privilege_escalation - custom - null description: Category of detection (only for detection agents) detectionQuery: type: - string - 'null' description: >- The SIEM query for the detection (only for detection agents) siemType: type: - string - 'null' description: >- The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents) isSuggestion: type: boolean description: >- Whether this detection is a suggestion (only for detection agents) lastDetectionRunAt: type: - string - 'null' description: >- Timestamp of when this detection was last run (only for detection agents) isBuiltIn: type: boolean const: true description: >- Whether this agent is built in to the system (true for built-in (system-managed) agents) builtInAgentType: type: string enum: - threat-relevancy - threat-research - autonomous-hunt - test-agent description: >- Type of built-in agent (e.g., threat-validation, threat-hunt) required: - id - organizationId - name - description - systemPrompt - createdAt - updatedAt - deletedAt - toolNames - toolSelectionMode - toolActionConfigs - inputs - modelAlias - planningMode - agentType - origin - isBuiltIn - builtInAgentType - type: object properties: id: type: string description: Unique identifier for the agent organizationId: type: string description: >- Unique identifier of the organization that owns this agent name: type: string description: Human-readable name of the agent description: type: string description: Description of what the agent does and its purpose systemPrompt: type: string description: >- The agent's live system prompt (version history lives in agent_versions) createdAt: type: string description: Timestamp when the agent was created updatedAt: type: string description: Timestamp when the agent was last updated deletedAt: type: - string - 'null' description: >- Timestamp when the agent was soft-deleted, or null if not deleted toolNames: type: array items: type: string description: >- Array of tool names that this agent can use during execution toolSelectionMode: type: string enum: - manual - all_read_only description: How this agent resolves tools at runtime cliNames: type: array items: type: string description: >- Optional array of CLI integration ids that this agent can use during execution toolActionConfigs: type: array items: oneOf: - type: object properties: type: type: string const: slack_sendMessage allowedChannels: type: array items: type: object properties: id: type: string minLength: 1 description: >- Slack channel ID (for example C123ABC456) name: type: string minLength: 1 description: 'Slack channel name without the leading #' required: - id - name additionalProperties: false minItems: 1 description: >- Allowlist of Slack channels this agent may access when using this tool action hideAgentButton: type: boolean description: >- When true, omits the "Open Agent Run in Cotool" button from Slack messages produced by this tool action. Defaults to false (button is shown). required: - type additionalProperties: false - type: object properties: type: type: string const: slack_replyToThread allowedChannels: type: array items: type: object properties: id: type: string minLength: 1 description: >- Slack channel ID (for example C123ABC456) name: type: string minLength: 1 description: 'Slack channel name without the leading #' required: - id - name additionalProperties: false minItems: 1 description: >- Allowlist of Slack channels this agent may access when using this tool action hideAgentButton: type: boolean description: >- When true, omits the "Open Agent Run in Cotool" button from Slack messages produced by this tool action. Defaults to false (button is shown). required: - type additionalProperties: false - type: object properties: type: type: string const: slack_readChannelMessages allowedChannels: type: array items: type: object properties: id: type: string minLength: 1 description: >- Slack channel ID (for example C123ABC456) name: type: string minLength: 1 description: 'Slack channel name without the leading #' required: - id - name additionalProperties: false minItems: 1 description: >- Allowlist of Slack channels this agent may access when using this tool action required: - type - allowedChannels additionalProperties: false - type: object properties: type: type: string const: slack_readThreadMessages allowedChannels: type: array items: type: object properties: id: type: string minLength: 1 description: >- Slack channel ID (for example C123ABC456) name: type: string minLength: 1 description: 'Slack channel name without the leading #' required: - id - name additionalProperties: false minItems: 1 description: >- Allowlist of Slack channels this agent may access when using this tool action required: - type - allowedChannels additionalProperties: false - type: object properties: type: type: string const: slack_waitForUserResponse allowedChannels: type: array items: type: object properties: id: type: string minLength: 1 description: >- Slack channel ID (for example C123ABC456) name: type: string minLength: 1 description: 'Slack channel name without the leading #' required: - id - name additionalProperties: false minItems: 1 description: >- Allowlist of Slack channels this agent may access when using this tool action hideAgentButton: type: boolean description: >- When true, omits the "Open Agent Run in Cotool" button from Slack messages produced by this tool action. Defaults to false (button is shown). timeout: type: object properties: amount: type: integer exclusiveMinimum: 0 description: >- Number of units to wait before an unanswered prompt times out. unit: type: string enum: - minutes - hours - days description: Unit for the timeout amount. required: - amount - unit additionalProperties: false description: >- Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing). required: - type additionalProperties: false description: Configuration for a specific tool action description: Per-tool-action configuration for this agent inputs: type: array items: type: object properties: type: type: string enum: - text - image - pdf - audio - video description: The type of input expected by the agent name: type: string description: The name of the input field description: type: string description: A description of what this input is used for required: type: boolean description: >- Whether this input is required for agent execution required: - type - name - description - required description: >- Array of input configurations defining what inputs the agent expects modelAlias: description: >- Model alias specifying which LLM model to use for this agent contextDocs: type: array items: type: object properties: provider: type: string enum: - googleDocs - notion - confluence - mcp id: type: string name: type: string mimeType: type: string required: - provider - id - name description: >- Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent tinesStoryImportId: type: - string - 'null' description: >- Optional reference to the Tines story import template used to create this agent triggerSummary: type: array items: type: object properties: id: type: string description: Unique identifier for the trigger source: type: string enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone description: >- The source platform or system that triggers the agent name: type: string description: Human-readable name for the trigger enabled: type: boolean description: Whether the trigger is currently enabled required: - id - source - name - enabled description: Optional array of triggers configured for this agent planningMode: type: string enum: - auto - never - always description: Planning behavior mode for the agent structuredOutputSchema: oneOf: - $ref: '#/components/schemas/CotoolJsonSchema' - type: 'null' description: >- Optional JSON schema describing the structured output the agent should emit (may include x-cotool metadata for preset UX; metadata is stripped before sending to the LLM) persistentWorkspaceEnabled: type: boolean description: Whether this agent may use persistent workspace tags: type: array items: type: string minLength: 1 maxLength: 100 description: >- A tag label for categorizing agents (normalized to lowercase) description: Array of tags for categorizing the agent skills: type: array items: type: object properties: skillId: type: string format: uuid description: Unique identifier of an attached skill skillVersionId: type: - string - 'null' format: uuid description: >- Pinned version ID, or null/undefined to track latest invocationCount30d: type: number description: >- Distinct chats for this agent in the last 30 days where the skill was read from the sandbox skill: type: object properties: name: type: string pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ minLength: 1 maxLength: 64 description: >- Machine-safe skill name used in sandbox paths and imports description: type: string description: Skill description requiredTools: type: array items: type: string description: Required tool types for this skill required: - name - description - requiredTools description: Skill metadata snapshot required: - skillId - skill description: Array of reusable skills attached to this agent acceptanceCriteria: type: array items: type: string minLength: 1 maxLength: 500 description: >- A user-configured acceptance criterion that must be satisfied for an agent run maxItems: 20 description: >- Optional list of acceptance criteria evaluated for every run agentType: type: string enum: - response - detection description: >- Type of agent: response (standard) or detection (security detection) origin: type: string enum: - user - orchestrator description: 'Who created this agent: user or orchestrator' syncKey: type: - string - 'null' description: >- Stable logical key for the agent (slug, immutable, unique per org) syncSource: type: - string - 'null' description: >- Sync backend managing this agent (e.g. "github"); null/absent when UI-managed syncFilePath: type: - string - 'null' description: >- Path of the source YAML file for a GitOps-managed agent syncConfigId: type: - string - 'null' description: >- Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed detectionCategory: type: - string - 'null' enum: - baseline_anomaly - first_occurrence - sequence_pattern - privilege_escalation - custom - null description: Category of detection (only for detection agents) detectionQuery: type: - string - 'null' description: >- The SIEM query for the detection (only for detection agents) siemType: type: - string - 'null' description: >- The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents) isSuggestion: type: boolean description: >- Whether this detection is a suggestion (only for detection agents) lastDetectionRunAt: type: - string - 'null' description: >- Timestamp of when this detection was last run (only for detection agents) isBuiltIn: type: boolean const: false description: >- Whether this agent is built in to the system (false for custom (user-created) agents) required: - id - organizationId - name - description - systemPrompt - createdAt - updatedAt - deletedAt - toolNames - toolSelectionMode - toolActionConfigs - inputs - modelAlias - planningMode - agentType - origin - isBuiltIn description: >- Agent configuration - can be either a built in (system-managed) or custom (user-created) agent description: Array of all agents in the organization '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 GET "https://app.cotool.ai/api/agents" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" components: schemas: CotoolJsonSchema: type: object properties: type: type: string enum: - string - number - boolean - 'null' - object - array title: type: string description: type: string properties: type: object additionalProperties: $ref: '#/components/schemas/CotoolJsonSchema' items: $ref: '#/components/schemas/CotoolJsonSchema' required: type: array items: type: string enum: type: array items: type: string additionalProperties: type: boolean x-cotool: type: object properties: presetId: type: string enum: - classification - markdown - templatedReport - toolCallEvidence viewerId: type: string additionalProperties: $ref: '#/components/schemas/JsonValue' required: - type description: >- A JSON Schema definition with Cotool-specific extensions for structured output presets 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 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) 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` ````