Skip to main content
GET
/
api
/
agents
/
{agentId}
cURL
curl -X GET "https://app.cotool.ai/api/agents/:agentId" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
{
  "id": "<string>",
  "organizationId": "<string>",
  "name": "<string>",
  "description": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>",
  "toolNames": [
    "<string>"
  ],
  "inputs": [
    {
      "type": "text",
      "name": "<string>",
      "description": "<string>",
      "required": true
    }
  ],
  "modelAlias": "<unknown>",
  "planningMode": "auto",
  "agentType": "response",
  "isBuiltIn": true,
  "builtInAgentType": "threat-relevancy",
  "contextDocs": [
    {
      "provider": "googleDocs",
      "id": "<string>",
      "name": "<string>",
      "mimeType": "<string>"
    }
  ],
  "tinesStoryImportId": "<string>",
  "triggerSummary": [
    {
      "id": "<string>",
      "source": "jira",
      "name": "<string>",
      "enabled": true
    }
  ],
  "structuredOutputSchema": {
    "type": "string",
    "title": "<string>",
    "description": "<string>",
    "properties": {},
    "items": "<unknown>",
    "required": [
      "<string>"
    ],
    "enum": [
      "<string>"
    ],
    "x-cotool": {
      "presetId": "classification"
    }
  },
  "detectionCategory": "baseline_anomaly",
  "detectionQuery": "<string>",
  "siemType": "<string>",
  "detectionCadence": "hourly",
  "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

Path Parameters

​
agentId
string<uuid>
required

Unique identifier of the agent to retrieve

Response

200 - application/json

Successful response

Complete agent configuration and metadata

​
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

​
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

​
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
​
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
​
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)

​
detectionCategory
enum<string> | null

Category of detection (only for detection agents)

Available options:
baseline_anomaly,
first_occurrence,
sequence_pattern,
privilege_escalation,
custom,
​
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)

​
detectionCadence
enum<string> | null

How often the detection runs: hourly, daily, or weekly (only for detection agents)

Available options:
hourly,
daily,
weekly,
​
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)