Skip to main content
GET
/
api
/
agents
cURL
curl -X GET "https://app.cotool.ai/api/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
[
  {
    "id": "<string>",
    "organizationId": "<string>",
    "name": "<string>",
    "description": "<string>",
    "systemPrompt": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "deletedAt": "<string>",
    "toolNames": [
      "<string>"
    ],
    "toolActionConfigs": [
      {
        "type": "<string>",
        "allowedChannels": [
          {
            "id": "<string>",
            "name": "<string>"
          }
        ],
        "hideAgentButton": true
      }
    ],
    "inputs": [
      {
        "name": "<string>",
        "description": "<string>",
        "required": true
      }
    ],
    "modelAlias": "<unknown>",
    "isBuiltIn": true,
    "cliNames": [
      "<string>"
    ],
    "contextDocs": [
      {
        "id": "<string>",
        "name": "<string>",
        "mimeType": "<string>"
      }
    ],
    "tinesStoryImportId": "<string>",
    "triggerSummary": [
      {
        "id": "<string>",
        "name": "<string>",
        "enabled": true
      }
    ],
    "structuredOutputSchema": {
      "title": "<string>",
      "description": "<string>",
      "properties": {},
      "items": "<unknown>",
      "required": [
        "<string>"
      ],
      "enum": [
        "<string>"
      ],
      "additionalProperties": true,
      "x-cotool": {
        "viewerId": "<string>"
      }
    },
    "persistentWorkspaceEnabled": true,
    "tags": [
      "<string>"
    ],
    "skills": [
      {
        "skillId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "skill": {
          "name": "<string>",
          "description": "<string>",
          "requiredTools": [
            "<string>"
          ]
        },
        "skillVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "invocationCount30d": 123
      }
    ],
    "acceptanceCriteria": [
      "<string>"
    ],
    "syncKey": "<string>",
    "syncSource": "<string>",
    "syncFilePath": "<string>",
    "syncConfigId": "<string>",
    "detectionQuery": "<string>",
    "siemType": "<string>",
    "isSuggestion": true,
    "lastDetectionRunAt": "<string>"
  }
]

Authorizations

Authorization
string
header
required

API Key authentication for programmatic access. Include your API key in the Authorization header as: Bearer your_api_key_here

Response

Successful response

Agent configuration - can be either a built in (system-managed) or custom (user-created) agent

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

deletedAt
string | null
required

Timestamp when the agent was soft-deleted, or null if not deleted

toolNames
string[]
required

Array of tool names that this agent can use during execution

toolSelectionMode
enum<string>
required

How this agent resolves tools at runtime

Available options:
manual,
all_read_only
toolActionConfigs
object[]
required

Per-tool-action configuration for this agent

Configuration for a specific tool action

inputs
object[]
required

Array of input configurations defining what inputs the agent expects

modelAlias
any
required

Model alias specifying which LLM model to use for this agent

planningMode
enum<string>
required

Planning behavior mode for the agent

Available options:
auto,
never,
always
agentType
enum<string>
required

Type of agent: response (standard) or detection (security detection)

Available options:
response,
detection
origin
enum<string>
required

Who created this agent: user or orchestrator

Available options:
user,
orchestrator
isBuiltIn
boolean
required

Whether this agent is built in to the system (true for built-in (system-managed) agents)

builtInAgentType
enum<string>
required

Type of built-in agent (e.g., threat-validation, threat-hunt)

Available options:
threat-relevancy,
threat-research,
autonomous-hunt,
test-agent
cliNames
string[]

Optional array of CLI integration ids that this agent can use during execution

contextDocs
object[]

Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent

tinesStoryImportId
string | null

Optional reference to the Tines story import template used to create this agent

triggerSummary
object[]

Optional array of triggers configured for this agent

structuredOutputSchema
object

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
boolean

Whether this agent may use persistent workspace

tags
string[]

Array of tags for categorizing the agent

A tag label for categorizing agents (normalized to lowercase)

Required string length: 1 - 100
skills
object[]

Array of reusable skills attached to this agent

acceptanceCriteria
string[]

Optional list of acceptance criteria evaluated for every run

Maximum array length: 20

A user-configured acceptance criterion that must be satisfied for an agent run

Required string length: 1 - 500
syncKey
string | null

Stable logical key for the agent (slug, immutable, unique per org)

syncSource
string | null

Sync backend managing this agent (e.g. "github"); null/absent when UI-managed

syncFilePath
string | null

Path of the source YAML file for a GitOps-managed agent

syncConfigId
string | null

Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed

detectionCategory
enum<string> | null

Category of detection (only for detection agents)

Available options:
baseline_anomaly,
first_occurrence,
sequence_pattern,
privilege_escalation,
custom,
null
detectionQuery
string | null

The SIEM query for the detection (only for detection agents)

siemType
string | null

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 | null

Timestamp of when this detection was last run (only for detection agents)