Create a new agent - Cotool Documentation

cURL

curl -X POST "https://app.cotool.ai/api/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","description":"string","systemPrompt":"string","toolNames":["string"],"inputs":[{"type":"text","name":"string","description":"string","required":true}],"modelAlias":null,"contextDocs":[{"provider":"googleDocs","id":"string","name":"string","mimeType":"string"}],"tinesStoryImportId":"string","planningMode":"never","structuredOutputSchema":null}'

{
  "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>"
}

POST

api

agents

cURL

curl -X POST "https://app.cotool.ai/api/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","description":"string","systemPrompt":"string","toolNames":["string"],"inputs":[{"type":"text","name":"string","description":"string","required":true}],"modelAlias":null,"contextDocs":[{"provider":"googleDocs","id":"string","name":"string","mimeType":"string"}],"tinesStoryImportId":"string","planningMode":"never","structuredOutputSchema":null}'

{
  "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

Body

application/json

Request body for creating a new AI agent with configuration

name

string

required

Name of the agent

description

string

required

Description of what the agent does

systemPrompt

string

required

System prompt that defines the agent behavior and instructions

toolNames

string[]

required

Array of tool names that this agent can use

inputs

object[]

required

Input configuration defining what inputs the agent expects

Show child attributes

modelAlias

any

required

Model alias must be a valid model from the registry

contextDocs

object[]

Optional context documents to provide to the agent

Show child attributes

tinesStoryImportId

string<uuid> | null

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

planningMode

enum<string>

Optional planning behavior; defaults to auto

Available options:

never,

always,

auto

structuredOutputSchema

object

Optional structured output schema definition for this agent

Show child attributes

Response

200 - application/json

Successful response

Option 1
Option 2

The newly created agent with generated ID and timestamps

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

Show child attributes

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

Show child attributes

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

Show child attributes

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)

Show child attributes

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)

List all agents

Get agent

⌘I

Endpoints

Authorizations

Body

Response