curl -X POST "https://app.cotool.ai/api/detections" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"string","description":"string","detectionCategory":"baseline_anomaly","systemPrompt":"string","detectionQuery":"string","siemType":"string","toolNames":["string"],"cliNames":["string"],"toolActionConfigs":null,"skills":[{"skillId":"string","skillVersionId":"string"}],"detectionCadence":"hourly","customCronSchedule":"string"}'import requests
url = "https://app.cotool.ai/api/detections"
payload = {
"name": "<string>",
"systemPrompt": "<string>",
"description": "<string>",
"detectionQuery": "<string>",
"siemType": "<string>",
"toolNames": ["<string>"],
"cliNames": ["<string>"],
"toolActionConfigs": [
{
"type": "slack_sendMessage",
"allowedChannels": [
{
"id": "<string>",
"name": "<string>"
}
],
"hideAgentButton": True
}
],
"skills": [
{
"skillId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"skillVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
],
"customCronSchedule": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
systemPrompt: '<string>',
description: '<string>',
detectionQuery: '<string>',
siemType: '<string>',
toolNames: ['<string>'],
cliNames: ['<string>'],
toolActionConfigs: [
{
type: 'slack_sendMessage',
allowedChannels: [{id: '<string>', name: '<string>'}],
hideAgentButton: true
}
],
skills: [
{
skillId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
skillVersionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
}
],
customCronSchedule: '<string>'
})
};
fetch('https://app.cotool.ai/api/detections', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://app.cotool.ai/api/detections")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"systemPrompt\": \"<string>\",\n \"description\": \"<string>\",\n \"detectionQuery\": \"<string>\",\n \"siemType\": \"<string>\",\n \"toolNames\": [\n \"<string>\"\n ],\n \"cliNames\": [\n \"<string>\"\n ],\n \"toolActionConfigs\": [\n {\n \"type\": \"slack_sendMessage\",\n \"allowedChannels\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\"\n }\n ],\n \"hideAgentButton\": true\n }\n ],\n \"skills\": [\n {\n \"skillId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"skillVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n }\n ],\n \"customCronSchedule\": \"<string>\"\n}")
.asString();package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.cotool.ai/api/detections"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"systemPrompt\": \"<string>\",\n \"description\": \"<string>\",\n \"detectionQuery\": \"<string>\",\n \"siemType\": \"<string>\",\n \"toolNames\": [\n \"<string>\"\n ],\n \"cliNames\": [\n \"<string>\"\n ],\n \"toolActionConfigs\": [\n {\n \"type\": \"slack_sendMessage\",\n \"allowedChannels\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\"\n }\n ],\n \"hideAgentButton\": true\n }\n ],\n \"skills\": [\n {\n \"skillId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"skillVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n }\n ],\n \"customCronSchedule\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "<string>",
"organizationId": "<string>",
"name": "<string>",
"description": "<string>",
"systemPrompt": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>",
"deletedAt": "<string>",
"toolNames": [
"<string>"
],
"toolSelectionMode": "manual",
"toolActionConfigs": [
{
"type": "slack_sendMessage",
"allowedChannels": [
{
"id": "<string>",
"name": "<string>"
}
],
"hideAgentButton": true
}
],
"inputs": [
{
"type": "text",
"name": "<string>",
"description": "<string>",
"required": true
}
],
"modelAlias": "<unknown>",
"planningMode": "auto",
"agentType": "response",
"origin": "user",
"isBuiltIn": true,
"builtInAgentType": "threat-relevancy",
"cronSchedule": "<string>",
"enabled": true,
"invocationCount": 1,
"invocationCount30d": 1,
"lastInvokedAt": "<string>",
"cliNames": [
"<string>"
],
"contextDocs": [
{
"provider": "googleDocs",
"id": "<string>",
"name": "<string>",
"mimeType": "<string>"
}
],
"tinesStoryImportId": "<string>",
"triggerSummary": [
{
"id": "<string>",
"source": "jira",
"name": "<string>",
"enabled": true,
"eventMode": "direct",
"createsAlert": true
}
],
"structuredOutputSchema": {
"type": "string",
"title": "<string>",
"description": "<string>",
"properties": {},
"items": "<unknown>",
"minItems": 1,
"maxItems": 1,
"required": [
"<string>"
],
"enum": [
"<string>"
],
"additionalProperties": true,
"x-cotool": {
"presetId": "classification",
"viewerId": "<string>"
}
},
"persistentWorkspaceEnabled": true,
"createAlertsForApiRuns": 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>"
],
"slackReplyScope": "anyone",
"syncKey": "<string>",
"syncSource": "<string>",
"syncFilePath": "<string>",
"syncConfigId": "<string>",
"detectionCategory": "baseline_anomaly",
"detectionQuery": "<string>",
"siemType": "<string>",
"isSuggestion": true,
"lastDetectionRunAt": "<string>",
"legacyDetection": true,
"activeSystemPrompt": {
"agentVersionId": "<string>",
"prompt": "<string>",
"description": "<string>"
},
"runs30d": 123,
"runningRuns30d": 123,
"hits30d": 123,
"avgEvalScore30d": 123,
"threatModelSnippet": "<string>",
"threatModelVersion": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version": 123,
"isCurrent": true
}
}{
"error": "<string>",
"issues": [
{}
]
}{
"error": "<string>"
}{
"error": "<string>",
"missingPerms": [
"<string>"
]
}{
"error": "<string>"
}Create detection
Create a new detection.
curl -X POST "https://app.cotool.ai/api/detections" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"string","description":"string","detectionCategory":"baseline_anomaly","systemPrompt":"string","detectionQuery":"string","siemType":"string","toolNames":["string"],"cliNames":["string"],"toolActionConfigs":null,"skills":[{"skillId":"string","skillVersionId":"string"}],"detectionCadence":"hourly","customCronSchedule":"string"}'import requests
url = "https://app.cotool.ai/api/detections"
payload = {
"name": "<string>",
"systemPrompt": "<string>",
"description": "<string>",
"detectionQuery": "<string>",
"siemType": "<string>",
"toolNames": ["<string>"],
"cliNames": ["<string>"],
"toolActionConfigs": [
{
"type": "slack_sendMessage",
"allowedChannels": [
{
"id": "<string>",
"name": "<string>"
}
],
"hideAgentButton": True
}
],
"skills": [
{
"skillId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"skillVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
],
"customCronSchedule": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
systemPrompt: '<string>',
description: '<string>',
detectionQuery: '<string>',
siemType: '<string>',
toolNames: ['<string>'],
cliNames: ['<string>'],
toolActionConfigs: [
{
type: 'slack_sendMessage',
allowedChannels: [{id: '<string>', name: '<string>'}],
hideAgentButton: true
}
],
skills: [
{
skillId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
skillVersionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
}
],
customCronSchedule: '<string>'
})
};
fetch('https://app.cotool.ai/api/detections', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://app.cotool.ai/api/detections")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"systemPrompt\": \"<string>\",\n \"description\": \"<string>\",\n \"detectionQuery\": \"<string>\",\n \"siemType\": \"<string>\",\n \"toolNames\": [\n \"<string>\"\n ],\n \"cliNames\": [\n \"<string>\"\n ],\n \"toolActionConfigs\": [\n {\n \"type\": \"slack_sendMessage\",\n \"allowedChannels\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\"\n }\n ],\n \"hideAgentButton\": true\n }\n ],\n \"skills\": [\n {\n \"skillId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"skillVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n }\n ],\n \"customCronSchedule\": \"<string>\"\n}")
.asString();package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.cotool.ai/api/detections"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"systemPrompt\": \"<string>\",\n \"description\": \"<string>\",\n \"detectionQuery\": \"<string>\",\n \"siemType\": \"<string>\",\n \"toolNames\": [\n \"<string>\"\n ],\n \"cliNames\": [\n \"<string>\"\n ],\n \"toolActionConfigs\": [\n {\n \"type\": \"slack_sendMessage\",\n \"allowedChannels\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\"\n }\n ],\n \"hideAgentButton\": true\n }\n ],\n \"skills\": [\n {\n \"skillId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"skillVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n }\n ],\n \"customCronSchedule\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "<string>",
"organizationId": "<string>",
"name": "<string>",
"description": "<string>",
"systemPrompt": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>",
"deletedAt": "<string>",
"toolNames": [
"<string>"
],
"toolSelectionMode": "manual",
"toolActionConfigs": [
{
"type": "slack_sendMessage",
"allowedChannels": [
{
"id": "<string>",
"name": "<string>"
}
],
"hideAgentButton": true
}
],
"inputs": [
{
"type": "text",
"name": "<string>",
"description": "<string>",
"required": true
}
],
"modelAlias": "<unknown>",
"planningMode": "auto",
"agentType": "response",
"origin": "user",
"isBuiltIn": true,
"builtInAgentType": "threat-relevancy",
"cronSchedule": "<string>",
"enabled": true,
"invocationCount": 1,
"invocationCount30d": 1,
"lastInvokedAt": "<string>",
"cliNames": [
"<string>"
],
"contextDocs": [
{
"provider": "googleDocs",
"id": "<string>",
"name": "<string>",
"mimeType": "<string>"
}
],
"tinesStoryImportId": "<string>",
"triggerSummary": [
{
"id": "<string>",
"source": "jira",
"name": "<string>",
"enabled": true,
"eventMode": "direct",
"createsAlert": true
}
],
"structuredOutputSchema": {
"type": "string",
"title": "<string>",
"description": "<string>",
"properties": {},
"items": "<unknown>",
"minItems": 1,
"maxItems": 1,
"required": [
"<string>"
],
"enum": [
"<string>"
],
"additionalProperties": true,
"x-cotool": {
"presetId": "classification",
"viewerId": "<string>"
}
},
"persistentWorkspaceEnabled": true,
"createAlertsForApiRuns": 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>"
],
"slackReplyScope": "anyone",
"syncKey": "<string>",
"syncSource": "<string>",
"syncFilePath": "<string>",
"syncConfigId": "<string>",
"detectionCategory": "baseline_anomaly",
"detectionQuery": "<string>",
"siemType": "<string>",
"isSuggestion": true,
"lastDetectionRunAt": "<string>",
"legacyDetection": true,
"activeSystemPrompt": {
"agentVersionId": "<string>",
"prompt": "<string>",
"description": "<string>"
},
"runs30d": 123,
"runningRuns30d": 123,
"hits30d": 123,
"avgEvalScore30d": 123,
"threatModelSnippet": "<string>",
"threatModelVersion": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version": 123,
"isCurrent": true
}
}{
"error": "<string>",
"issues": [
{}
]
}{
"error": "<string>"
}{
"error": "<string>",
"missingPerms": [
"<string>"
]
}{
"error": "<string>"
}Authorizations
API Key authentication for programmatic access. Include your API key in the Authorization header as: Bearer your_api_key_here
Body
Name of the detection
1 - 255System prompt for the detection agent
1Optional description
1000Category of detection (required for legacy detections, omit for intent-based)
baseline_anomaly, first_occurrence, sequence_pattern, privilege_escalation, custom The SIEM query for the detection (required for legacy detections, omit for intent-based)
1The SIEM platform type (e.g., splunk, elastic)
Tool names available to the detection agent
CLI integration ids available to the detection agent
Optional per-tool-action configuration for the detection agent
Configuration for a specific tool action
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
Show child attributes
Show child attributes
Optional set of skills to attach to the detection agent
Show child attributes
Show child attributes
How often the detection runs: hourly, daily, or weekly (standard cadences)
hourly, daily, weekly, null Custom cron expression for detection schedule (takes precedence over detectionCadence if provided). Must not run more frequently than hourly.
Response
Successful response
- Option 1
- Option 2
Agent configuration - can be either a built in (system-managed) or custom (user-created) agent
Unique identifier for the agent
Unique identifier of the organization that owns this agent
Human-readable name of the agent
Description of what the agent does and its purpose
The agent's live system prompt (version history lives in agent_versions)
Timestamp when the agent was created
Timestamp when the agent was last updated
Timestamp when the agent was soft-deleted, or null if not deleted
Array of tool names that this agent can use during execution
How this agent resolves tools at runtime
manual, all_read_only Per-tool-action configuration for this agent
Configuration for a specific tool action
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
Show child attributes
Show child attributes
Array of input configurations defining what inputs the agent expects
Show child attributes
Show child attributes
Model alias specifying which LLM model to use for this agent
Planning behavior mode for the agent
auto, never, always Type of agent: response (standard) or detection (security detection)
response, detection Who created this agent: user or orchestrator
user, orchestrator Whether this agent is built in to the system (true for built-in (system-managed) agents)
Type of built-in agent (e.g., threat-validation, threat-hunt)
threat-relevancy, threat-research, autonomous-hunt, code-detection-tuner, test-agent The cron schedule expression from the trigger (e.g., "0 * * * *" for hourly). Use cronToCadence() to derive display cadence.
Whether the detection schedule is enabled (from cron trigger)
All-time number of top-level invocations of this agent
x >= 0Number of top-level invocations of this agent in the last 30 days
x >= 0Timestamp of the most recent top-level invocation, or null if the agent has never been invoked
Optional array of CLI integration ids that this agent can use during execution
Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent
Show child attributes
Show child attributes
Optional reference to the Tines story import template used to create this agent
Optional array of triggers configured for this agent
Show child attributes
Show child attributes
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
Show child attributes
Whether this detection may use persistent workspace
Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)
Array of tags for categorizing the agent
A tag label for categorizing agents (normalized to lowercase)
1 - 100Array of reusable skills attached to this agent
Show child attributes
Show child attributes
Optional list of acceptance criteria evaluated for every run
20A user-configured acceptance criterion that must be satisfied for an agent run
1 - 500Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)
anyone, cotool_users, null Stable logical key for the agent (slug, immutable, unique per org)
Sync backend managing this agent (e.g. "github"); null/absent when UI-managed
Path of the source YAML file for a GitOps-managed agent
Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed
Category of detection (only for detection agents)
baseline_anomaly, first_occurrence, sequence_pattern, privilege_escalation, custom, null The SIEM query for the detection (only for detection agents)
The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)
Whether this detection is a suggestion (only for detection agents)
Timestamp of when this detection was last run (only for detection agents)
Client-side marker for a migrated legacy customer detection remapped to a unified agent
The currently active system prompt for this detection
Show child attributes
Show child attributes
Total runs in last 30 days
Total active runs in last 30 days
Recorded detection hits in last 30 days
Average LLM judge evaluation score (0-100) over last 30 days
Verbatim quote from the threat model version this agent was grounded in. Powers the "Why this agent?" drawer. Null for user-created agents.
Threat model version this orchestrator agent was built against. Null for user-created agents.
Show child attributes
Show child attributes
Was this page helpful?