---
title: "List all agents"
method: GET
path: "/api/agents"
tags: ["Agents"]
---

# List all agents

`GET /api/agents`

## Request

- Base URL: `https://app.cotool.ai`
- URL: `https://app.cotool.ai/api/agents`
- Auth: HTTP bearer

Retrieve a list of all AI agents available in the organization

## Response `200`

Successful response

- union[]: Array of all agents in the organization
  - union: Agent configuration - can be either a built in (system-managed) or custom (user-created) agent
    - object
      - `id` string, required: Unique identifier for the agent
      - `organizationId` string, required: Unique identifier of the organization that owns this agent
      - `name` string, required: Human-readable name of the agent
      - `description` string, required: Description of what the agent does and its purpose
      - `systemPrompt` string, required: The agent's live system prompt (version history lives in agent_versions)
      - `createdAt` string, required: Timestamp when the agent was created
      - `updatedAt` string, required: Timestamp when the agent was last updated
      - `createdByUserId` string, nullable: User ID that created this agent, or null for system-created or unknown authorship
      - `updatedByUserId` string, nullable: User ID that last edited this agent, or null for system edits or unknown authorship
      - `createdBy` object, nullable: Display identity of the user that created this agent
        - `name` string, nullable, required: The user's profile display name, falling back to their email
        - `imageUrl` string, nullable, required: The user's profile image URL, if one is available
      - `updatedBy` object, nullable: Display identity of the user that last edited this agent
        - `name` string, nullable, required: The user's profile display name, falling back to their email
        - `imageUrl` string, nullable, required: The user's profile image URL, if one is available
      - `deletedAt` string, nullable, required: Timestamp when the agent was soft-deleted, or null if not deleted
      - `invocationCount` integer: All-time number of top-level invocations of this agent
      - `invocationCount30d` integer: Number of top-level invocations of this agent in the last 30 days
      - `lastInvokedAt` string, nullable: Timestamp of the most recent top-level invocation, or null if the agent has never been invoked
      - `toolNames` string[], required: Array of tool names that this agent can use during execution
      - `toolSelectionMode` 'manual' | 'all_read_only' | 'all_read_only_plus_selected', required: How this agent resolves tools at runtime
      - `cliNames` string[]: Optional array of CLI integration ids that this agent can use during execution
      - `toolActionConfigs` union[], required: Per-tool-action configuration for this agent
        - union: Configuration for a specific tool action
          - object
            - `type` 'cotool-email_sendEmail', required
            - `allowedRecipients` string[], required: Email addresses and domains this agent may send email to. A domain allows every address at that domain, not its subdomains. With no entries the agent cannot send email.
          - object
            - `type` 'slack_sendMessage', required
            - `allowedChannels` object[]: Allowlist of Slack channels this agent may access when using this tool action
              - …
            - `hideAgentButton` boolean: When true, omits the "Open in Cotool" run link and the agent name from the footer of Slack messages produced by this tool action. Defaults to false (link is shown).
          - object
            - `type` 'slack_replyToThread', required
            - `allowedChannels` object[]: Allowlist of Slack channels this agent may access when using this tool action
              - …
            - `hideAgentButton` boolean: When true, omits the "Open in Cotool" run link and the agent name from the footer of Slack messages produced by this tool action. Defaults to false (link is shown).
          - object
            - `type` 'slack_readChannelMessages', required
            - `allowedChannels` object[], required: Allowlist of Slack channels this agent may access when using this tool action
              - …
          - object
            - `type` 'slack_readThreadMessages', required
            - `allowedChannels` object[], required: Allowlist of Slack channels this agent may access when using this tool action
              - …
          - object
            - `type` 'slack_downloadMessageFiles', required
            - `allowedChannels` object[], required: Allowlist of Slack channels this agent may access when using this tool action
              - …
          - object
            - `type` 'slack_waitForUserResponse', required
            - `allowedChannels` object[]: Allowlist of Slack channels this agent may access when using this tool action
              - …
            - `hideAgentButton` boolean: When true, omits the "Open in Cotool" run link and the agent name from the footer of Slack messages produced by this tool action. Defaults to false (link is shown).
            - `timeout` object: Optional fixed timeout for unanswered prompts. When omitted, the wait follows the severity of the run's alert: 15 minutes for critical, 1 hour for high, 4 hours for medium, 24 hours for low, and 24 hours when the run has no alert.
              - …
      - `modelAlias` unknown, required
      - `reasoningEffort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'null', nullable: Reasoning level the agent runs its model with, from the levels the model offers. Null keeps the model default. Applies with token-based pricing.
      - `fastMode` boolean: Whether the agent runs its model in fast mode, at the fast-mode price. Only models with a fast mode use it. Applies with token-based pricing.
      - `contextDocs` object[]: Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent
        - `provider` 'googleDocs' | 'notion' | 'confluence' | 'mcp', required
        - `id` string, required
        - `name` string, required
        - `mimeType` string
      - `tinesStoryImportId` string, nullable: Optional reference to the Tines story import template used to create this agent
      - `triggerSummary` object[]: Optional array of triggers configured for this agent
        - `id` string, required: Unique identifier for the trigger
        - `source` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon', required: The source platform or system that triggers the agent
        - `name` string, required: Human-readable name for the trigger
        - `enabled` boolean, required: Whether the trigger is currently enabled
        - `eventMode` 'direct' | 'alert_source': Whether this event runs the agent directly or creates an alert first
        - `createsAlert` boolean: Legacy compatibility projection of eventMode
      - `planningMode` 'auto' | 'never' | 'always', required: Planning behavior mode for the agent
      - `structuredOutputSchema` CotoolJsonSchema: A JSON Schema definition with Cotool-specific extensions for structured output presets
        - `type` 'string' | 'number' | 'boolean' | 'null' | 'object' | 'array', required
        - `title` string
        - `description` string
        - `properties` object
        - `items` CotoolJsonSchema (recursive)
        - `minItems` integer
        - `maxItems` integer
        - `required` string[]
        - `enum` string[]
        - `additionalProperties` boolean
        - `x-cotool` object
          - `presetId` 'classification' | 'markdown' | 'templatedReport' | 'toolCallEvidence'
          - `viewerId` string
      - `persistentWorkspaceEnabled` boolean: Whether this agent may use persistent workspace
      - `tags` string[]: Array of tags for categorizing the agent
      - `skills` object[]: Array of reusable skills attached to this agent
        - `skillId` string, uuid, required: Unique identifier of an attached skill
        - `skillVersionId` string, uuid, nullable: Pinned version ID, or null/undefined to track latest
        - `invocationCount30d` number: Distinct chats for this agent in the last 30 days where the skill was read from the sandbox
        - `skill` object, required: Skill metadata snapshot
          - `name` string, required: Machine-safe skill name used in sandbox paths and imports
          - `description` string, required: Skill description
          - `requiredTools` string[], required: Required tool types for this skill
      - `acceptanceCriteria` string[]: Optional list of acceptance criteria evaluated for every run
      - `agentType` 'response' | 'detection', required: Type of agent: response (standard) or detection (security detection)
      - `slackReplyScope` 'anyone' | 'cotool_users' | 'null', nullable: Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)
      - `origin` 'user' | 'orchestrator', required: Who created this agent: user or orchestrator
      - `syncKey` string, nullable: Stable logical key for the agent (slug, immutable, unique per org)
      - `syncSource` string, nullable: Sync backend managing this agent (e.g. "github"); null/absent when UI-managed
      - `syncFilePath` string, nullable: Path of the source YAML file for a GitOps-managed agent
      - `syncConfigId` string, nullable: Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed
      - `syncSourceUrl` string, nullable: Link to the source YAML file on GitHub for a GitOps-managed agent. Only returned when retrieving a single agent; null when the agent is UI-managed or its repository is not configured
      - `detectionCategory` 'baseline_anomaly' | 'first_occurrence' | 'sequence_pattern' | 'privilege_escalation' | 'custom' | 'null', nullable: Category of detection (only for detection agents)
      - `detectionQuery` string, nullable: The SIEM query for the detection (only for detection agents)
      - `siemType` string, nullable: The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)
      - `isSuggestion` boolean: Whether this detection is a suggestion (only for detection agents)
      - `lastDetectionRunAt` string, nullable: Timestamp of when this detection was last run (only for detection agents)
      - `legacyDetection` boolean: Client-side marker for a migrated legacy customer detection remapped to a unified agent
      - `isBuiltIn` true, required: Whether this agent is built in to the system (true for built-in (system-managed) agents)
      - `builtInAgentType` 'threat-relevancy' | 'threat-research' | 'autonomous-hunt' | 'detection-engineer' | 'code-detection-tuner' | 'detection-calibrator' | 'test-agent', required: Type of built-in agent (e.g., threat-validation, threat-hunt)
    - object
      - `id` string, required: Unique identifier for the agent
      - `organizationId` string, required: Unique identifier of the organization that owns this agent
      - `name` string, required: Human-readable name of the agent
      - `description` string, required: Description of what the agent does and its purpose
      - `systemPrompt` string, required: The agent's live system prompt (version history lives in agent_versions)
      - `createdAt` string, required: Timestamp when the agent was created
      - `updatedAt` string, required: Timestamp when the agent was last updated
      - `createdByUserId` string, nullable: User ID that created this agent, or null for system-created or unknown authorship
      - `updatedByUserId` string, nullable: User ID that last edited this agent, or null for system edits or unknown authorship
      - `createdBy` object, nullable: Display identity of the user that created this agent
        - `name` string, nullable, required: The user's profile display name, falling back to their email
        - `imageUrl` string, nullable, required: The user's profile image URL, if one is available
      - `updatedBy` object, nullable: Display identity of the user that last edited this agent
        - `name` string, nullable, required: The user's profile display name, falling back to their email
        - `imageUrl` string, nullable, required: The user's profile image URL, if one is available
      - `deletedAt` string, nullable, required: Timestamp when the agent was soft-deleted, or null if not deleted
      - `invocationCount` integer: All-time number of top-level invocations of this agent
      - `invocationCount30d` integer: Number of top-level invocations of this agent in the last 30 days
      - `lastInvokedAt` string, nullable: Timestamp of the most recent top-level invocation, or null if the agent has never been invoked
      - `toolNames` string[], required: Array of tool names that this agent can use during execution
      - `toolSelectionMode` 'manual' | 'all_read_only' | 'all_read_only_plus_selected', required: How this agent resolves tools at runtime
      - `cliNames` string[]: Optional array of CLI integration ids that this agent can use during execution
      - `toolActionConfigs` union[], required: Per-tool-action configuration for this agent
        - union: Configuration for a specific tool action
          - object
            - `type` 'cotool-email_sendEmail', required
            - `allowedRecipients` string[], required: Email addresses and domains this agent may send email to. A domain allows every address at that domain, not its subdomains. With no entries the agent cannot send email.
          - object
            - `type` 'slack_sendMessage', required
            - `allowedChannels` object[]: Allowlist of Slack channels this agent may access when using this tool action
              - …
            - `hideAgentButton` boolean: When true, omits the "Open in Cotool" run link and the agent name from the footer of Slack messages produced by this tool action. Defaults to false (link is shown).
          - object
            - `type` 'slack_replyToThread', required
            - `allowedChannels` object[]: Allowlist of Slack channels this agent may access when using this tool action
              - …
            - `hideAgentButton` boolean: When true, omits the "Open in Cotool" run link and the agent name from the footer of Slack messages produced by this tool action. Defaults to false (link is shown).
          - object
            - `type` 'slack_readChannelMessages', required
            - `allowedChannels` object[], required: Allowlist of Slack channels this agent may access when using this tool action
              - …
          - object
            - `type` 'slack_readThreadMessages', required
            - `allowedChannels` object[], required: Allowlist of Slack channels this agent may access when using this tool action
              - …
          - object
            - `type` 'slack_downloadMessageFiles', required
            - `allowedChannels` object[], required: Allowlist of Slack channels this agent may access when using this tool action
              - …
          - object
            - `type` 'slack_waitForUserResponse', required
            - `allowedChannels` object[]: Allowlist of Slack channels this agent may access when using this tool action
              - …
            - `hideAgentButton` boolean: When true, omits the "Open in Cotool" run link and the agent name from the footer of Slack messages produced by this tool action. Defaults to false (link is shown).
            - `timeout` object: Optional fixed timeout for unanswered prompts. When omitted, the wait follows the severity of the run's alert: 15 minutes for critical, 1 hour for high, 4 hours for medium, 24 hours for low, and 24 hours when the run has no alert.
              - …
      - `modelAlias` unknown, required
      - `reasoningEffort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'null', nullable: Reasoning level the agent runs its model with, from the levels the model offers. Null keeps the model default. Applies with token-based pricing.
      - `fastMode` boolean: Whether the agent runs its model in fast mode, at the fast-mode price. Only models with a fast mode use it. Applies with token-based pricing.
      - `contextDocs` object[]: Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent
        - `provider` 'googleDocs' | 'notion' | 'confluence' | 'mcp', required
        - `id` string, required
        - `name` string, required
        - `mimeType` string
      - `tinesStoryImportId` string, nullable: Optional reference to the Tines story import template used to create this agent
      - `triggerSummary` object[]: Optional array of triggers configured for this agent
        - `id` string, required: Unique identifier for the trigger
        - `source` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon', required: The source platform or system that triggers the agent
        - `name` string, required: Human-readable name for the trigger
        - `enabled` boolean, required: Whether the trigger is currently enabled
        - `eventMode` 'direct' | 'alert_source': Whether this event runs the agent directly or creates an alert first
        - `createsAlert` boolean: Legacy compatibility projection of eventMode
      - `planningMode` 'auto' | 'never' | 'always', required: Planning behavior mode for the agent
      - `structuredOutputSchema` CotoolJsonSchema: A JSON Schema definition with Cotool-specific extensions for structured output presets
        - `type` 'string' | 'number' | 'boolean' | 'null' | 'object' | 'array', required
        - `title` string
        - `description` string
        - `properties` object
        - `items` CotoolJsonSchema (recursive)
        - `minItems` integer
        - `maxItems` integer
        - `required` string[]
        - `enum` string[]
        - `additionalProperties` boolean
        - `x-cotool` object
          - `presetId` 'classification' | 'markdown' | 'templatedReport' | 'toolCallEvidence'
          - `viewerId` string
      - `persistentWorkspaceEnabled` boolean: Whether this agent may use persistent workspace
      - `tags` string[]: Array of tags for categorizing the agent
      - `skills` object[]: Array of reusable skills attached to this agent
        - `skillId` string, uuid, required: Unique identifier of an attached skill
        - `skillVersionId` string, uuid, nullable: Pinned version ID, or null/undefined to track latest
        - `invocationCount30d` number: Distinct chats for this agent in the last 30 days where the skill was read from the sandbox
        - `skill` object, required: Skill metadata snapshot
          - `name` string, required: Machine-safe skill name used in sandbox paths and imports
          - `description` string, required: Skill description
          - `requiredTools` string[], required: Required tool types for this skill
      - `acceptanceCriteria` string[]: Optional list of acceptance criteria evaluated for every run
      - `agentType` 'response' | 'detection', required: Type of agent: response (standard) or detection (security detection)
      - `slackReplyScope` 'anyone' | 'cotool_users' | 'null', nullable: Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)
      - `origin` 'user' | 'orchestrator', required: Who created this agent: user or orchestrator
      - `syncKey` string, nullable: Stable logical key for the agent (slug, immutable, unique per org)
      - `syncSource` string, nullable: Sync backend managing this agent (e.g. "github"); null/absent when UI-managed
      - `syncFilePath` string, nullable: Path of the source YAML file for a GitOps-managed agent
      - `syncConfigId` string, nullable: Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed
      - `syncSourceUrl` string, nullable: Link to the source YAML file on GitHub for a GitOps-managed agent. Only returned when retrieving a single agent; null when the agent is UI-managed or its repository is not configured
      - `detectionCategory` 'baseline_anomaly' | 'first_occurrence' | 'sequence_pattern' | 'privilege_escalation' | 'custom' | 'null', nullable: Category of detection (only for detection agents)
      - `detectionQuery` string, nullable: The SIEM query for the detection (only for detection agents)
      - `siemType` string, nullable: The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)
      - `isSuggestion` boolean: Whether this detection is a suggestion (only for detection agents)
      - `lastDetectionRunAt` string, nullable: Timestamp of when this detection was last run (only for detection agents)
      - `legacyDetection` boolean: Client-side marker for a migrated legacy customer detection remapped to a unified agent
      - `isBuiltIn` false, required: Whether this agent is built in to the system (false for custom (user-created) agents)

## Other responses

- `400`: Bad request — input validation failed or the request was malformed
- `401`: Unauthorized — missing or invalid API key / session
- `403`: Forbidden — the authenticated user lacks the required permissions
- `500`: Internal server error

---

[API](https://skmtc.dev/cotool/apis/cotool-api.md) - [All operations](https://skmtc.dev/cotool/apis/cotool-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cotool/apis/cotool-api/revisions/f5abe0add203?raw)