{"openapi":"3.1.0","info":{"title":"Cotool API","version":"1.0.0","description":"The Cotool REST API. Authenticate with an API key from `/settings/api-keys` sent as `Authorization: Bearer <key>`.\n\nAuthentication, error formats, pagination, and common integration recipes are documented in the [API overview](https://docs.cotool.ai/api-reference/introduction). Endpoints marked **Deprecated** keep working; each one's description names its replacement."},"servers":[{"url":"https://app.cotool.ai","description":"Production server"}],"tags":[{"name":"Agents","description":"Create, update, run, and version agents."},{"name":"Agent Runs","description":"Inspect agent runs, submit feedback, and read evaluation metrics."},{"name":"Agent Triggers","description":"Webhook, schedule, and integration triggers that start agent runs."},{"name":"Agents as Code","description":"Validate agents and skills defined as YAML in a Git repository."},{"name":"Skills","description":"Reusable instructions and tool grants attached to agents."},{"name":"Chat","description":"Chat sessions and their transcripts."},{"name":"Alerts","description":"Alert triage, routing, and escalation notifications."},{"name":"Output Destinations","description":"Webhook, Slack, Jira, and Linear destinations for agent output."},{"name":"Detections","description":"Detection agents, detection hits, and the Cotool detection library."},{"name":"Hunt","description":"Autonomous hunt threats, gaps, and settings."},{"name":"Intel","description":"Threat-intelligence feed items, indicators, and sources."},{"name":"Threat Model","description":"The organization threat model and its version history."},{"name":"MITRE Coverage","description":"MITRE ATT&CK coverage across detections."},{"name":"Tools","description":"Connected tool integrations and captured tool output."},{"name":"CLIs","description":"Connected CLI integrations."},{"name":"Artifacts","description":"Files and reports produced by agent runs."},{"name":"Audit Logs","description":"Organization audit log export and event catalog."},{"name":"Users","description":"Users, memberships, and the current session."},{"name":"Roles","description":"Role-based permissions."},{"name":"Organizations","description":"Organization-level metrics."}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/agents/{agentId}/trigger":{"get":{"summary":"List agent triggers","description":"Retrieve all triggers configured for a specific agent.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents/:agentId/trigger\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"]},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"First-class event behavior. Missing only on legacy serialized snapshots."},"name":{"type":"string"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"cronSchedule":{"type":["string","null"]},"emailAddress":{"type":["string","null"]},"config":{"type":"object","additionalProperties":{}},"lastRunAttemptedAt":{"type":["string","null"]},"lastRunSucceededAt":{"type":["string","null"]}},"required":["id","agentId","organizationId","source","name","enabled","createdAt","updatedAt","config"]},"description":"Array of trigger configurations for the specified agent"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/trigger/{triggerId}/secret":{"get":{"summary":"Retrieve an agent trigger secret","description":"Retrieve a trigger signing secret. Requires edit access to the owning agent.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents/:agentId/trigger/:triggerId/secret\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true},{"in":"path","name":"triggerId","description":"Unique identifier of the trigger","schema":{"type":"string","format":"uuid","description":"Unique identifier of the trigger"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"string","description":"Decrypted webhook signing secret"}},"required":["secret"],"description":"Webhook signing secret for a trigger"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/trigger/{triggerId}/status":{"patch":{"summary":"Update trigger status","description":"Enable or disable a trigger for the specified agent.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PATCH \"https://app.cotool.ai/api/agents/:agentId/trigger/:triggerId/status\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"enabled\":true}'"}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true},{"in":"path","name":"triggerId","description":"Unique identifier of the trigger","schema":{"type":"string","format":"uuid","description":"Unique identifier of the trigger"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the trigger should be enabled or disabled"}},"required":["enabled"],"description":"Request body for updating trigger status"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the status update was successful"},"enabled":{"type":"boolean","description":"Current enabled state of the trigger after update"}},"required":["success","enabled"],"description":"Response confirming trigger status update"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/trigger/{triggerId}":{"delete":{"summary":"Delete trigger","description":"Delete an existing trigger from an agent.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X DELETE \"https://app.cotool.ai/api/agents/:agentId/trigger/:triggerId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true},{"in":"path","name":"triggerId","description":"Unique identifier of the trigger","schema":{"type":"string","format":"uuid","description":"Unique identifier of the trigger"},"required":true}],"responses":{"200":{"description":"Successful response - no content"},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update trigger definition","description":"Modify metadata or configuration of an existing trigger.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/agents/:agentId/trigger/:triggerId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\",\"description\":\"string\",\"source\":\"slack\",\"allowedUserIds\":[\"string\"],\"allowedUsergroupIds\":[\"string\"],\"allowedChannelIds\":[\"string\"],\"replyScope\":\"anyone\",\"reactionEmojis\":[\"rotating_light\"],\"eventMode\":\"direct\",\"createAlert\":true}'"}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true},{"in":"path","name":"triggerId","description":"Unique identifier of the trigger","schema":{"type":"string","format":"uuid","description":"Unique identifier of the trigger"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","const":"slack"},"allowedUserIds":{"type":"array","items":{"type":"string"}},"allowedUsergroupIds":{"type":"array","items":{"type":"string"}},"allowedChannelIds":{"type":"array","items":{"type":"string"}},"replyScope":{"type":"string","enum":["anyone","cotool_users"],"description":"Who may reply in a Slack thread to continue this agent: anyone (any Slack user) or cotool_users (only mapped Cotool users with execute permission)"},"reactionEmojis":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Slack emoji short names (no colons) that trigger this agent when added as a reaction to a message, e.g. [\"rotating_light\"]. Empty or absent means reactions do not trigger this agent.","example":["rotating_light"]},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"createAlert":{"type":"boolean"}},"required":["name","source"]},{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","const":"jira"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"createAlert":{"type":"boolean"}},"required":["name","source"]},{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","const":"jira-automation"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"createAlert":{"type":"boolean"}},"required":["name","source"]},{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","const":"linear"},"linearMode":{"type":"string","enum":["agent-session","legacy-webhook"]},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"createAlert":{"type":"boolean"}},"required":["name","source"]},{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","const":"cron"},"schedule":{"type":"string"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"createAlert":{"type":"boolean"}},"required":["name","source"]},{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","const":"webhook"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"createAlert":{"type":"boolean"}},"required":["name","source"]},{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","const":"email"},"emailAddress":{"type":"string"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"createAlert":{"type":"boolean"}},"required":["name","source","emailAddress"]},{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","const":"bugcrowd"},"secret":{"type":"string","minLength":1},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"createAlert":{"type":"boolean"}},"required":["name","source"]},{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","const":"hackerone"},"secret":{"type":"string","minLength":1},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"createAlert":{"type":"boolean"}},"required":["name","source"]},{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","const":"zscaler"},"secret":{"type":"string","minLength":1},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"createAlert":{"type":"boolean"}},"required":["name","source"]},{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string","const":"darktrace"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"createAlert":{"type":"boolean"}},"required":["name","source"]}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"]},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"First-class event behavior. Missing only on legacy serialized snapshots."},"name":{"type":"string"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secret":{"type":["string","null"]},"cronSchedule":{"type":["string","null"]},"emailAddress":{"type":["string","null"]},"config":{"type":"object","additionalProperties":{}},"lastRunAttemptedAt":{"type":["string","null"]},"lastRunSucceededAt":{"type":["string","null"]}},"required":["id","agentId","organizationId","source","name","enabled","createdAt","updatedAt","config"]}},"required":["success","data"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/trigger/{source}/fields":{"get":{"summary":"Get webhook fields","description":"Generate a webhook URL, secret, and any additional fields required to configure an external webhook for a trigger.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents/:agentId/trigger/:source/fields\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true},{"in":"path","name":"source","description":"Source type for the trigger (e.g., jira, slack, linear, hackerone)","schema":{"type":"string","description":"Source type for the trigger (e.g., jira, slack, linear, hackerone)"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the webhook fields were generated successfully"},"data":{"type":"object","properties":{"secret":{"type":"string","description":"Generated secret for webhook authentication"},"webhookUrl":{"type":"string","description":"Generated webhook URL for external services to call"},"additionalFields":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"jira"},"jiraUrl":{"type":"string","description":"URL to Jira webhook configuration page"}},"required":["type","jiraUrl"]},{"type":"object","properties":{"type":{"type":"string","const":"jira-automation"},"authHeader":{"type":"string","description":"Header name for authentication (X-Webhook-Auth)"},"instructions":{"type":"string","description":"Instructions for Jira Automation Send web request setup"}},"required":["type","authHeader","instructions"]},{"type":"object","properties":{"type":{"type":"string","const":"slack"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"linear"},"workspaceName":{"type":"string","description":"Name of the Linear workspace"}},"required":["type","workspaceName"]},{"type":"object","properties":{"type":{"type":"string","const":"webhook"},"authHeader":{"type":"string","description":"Header name for authentication (X-Webhook-Auth)"},"instructions":{"type":"string","description":"Simple instructions for webhook setup"}},"required":["type","authHeader","instructions"]},{"type":"object","properties":{"type":{"type":"string","const":"hackerone"},"signatureHeader":{"type":"string","description":"Header HackerOne uses to sign deliveries (X-H1-Signature)"},"instructions":{"type":"string","description":"Instructions for HackerOne webhook setup"}},"required":["type","signatureHeader","instructions"]},{"type":"object","properties":{"type":{"type":"string","const":"bugcrowd"},"signatureHeader":{"type":"string","description":"Header Bugcrowd uses to sign deliveries (X-Bugcrowd-Digest)"},"instructions":{"type":"string","description":"Instructions for configuring an Outgoing Webhook in Bugcrowd"}},"required":["type","signatureHeader","instructions"]},{"type":"object","properties":{"type":{"type":"string","const":"zscaler"},"authHeader":{"type":"string","description":"Header carrying the token in Zscaler deliveries (X-Cotool-Webhook-Token)"},"instructions":{"type":"string","description":"Instructions for pointing a Zscaler Cloud NSS feed or alert webhook at this trigger"}},"required":["type","authHeader","instructions"]},{"type":"object","properties":{"type":{"type":"string","const":"darktrace"},"basicUsername":{"type":"string","description":"HTTP Basic authentication username (the trigger ID)"},"instructions":{"type":"string","description":"Instructions for configuring the Darktrace HTTPS module"}},"required":["type","basicUsername","instructions"]}],"description":"Additional configuration fields specific to the trigger source type"}},"required":["secret","webhookUrl","additionalFields"],"description":"Webhook configuration data"}},"required":["success","data"],"description":"Response containing webhook configuration fields for external service setup"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/trigger/save":{"post":{"summary":"Save trigger definition","description":"Create and save a new trigger definition for Jira, Jira Automation, Slack, Linear, Cron, generic Webhook, or HackerOne sources.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agents/:agentId/trigger/save\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"triggerId\":\"string\",\"name\":\"string\",\"description\":\"string\",\"secret\":\"string\",\"webhookUrl\":\"string\",\"source\":\"jira\",\"eventMode\":\"direct\",\"createAlert\":true}'"}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"triggerId":{"type":"string","format":"uuid","description":"Unique identifier for the trigger"},"name":{"type":"string","description":"Display name for the trigger"},"description":{"type":"string","description":"Optional description of what this trigger does"},"secret":{"type":"string","description":"Secret for webhook authentication"},"webhookUrl":{"type":"string","description":"Webhook URL for Jira to call"},"source":{"type":"string","const":"jira"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"},"createAlert":{"type":"boolean","description":"Deprecated compatibility alias for eventMode"}},"required":["triggerId","name","secret","webhookUrl","source"]},{"type":"object","properties":{"triggerId":{"type":"string","format":"uuid","description":"Unique identifier for the trigger"},"name":{"type":"string","description":"Display name for the trigger"},"description":{"type":"string","description":"Optional description of what this trigger does"},"secret":{"type":"string","description":"Authentication token for Jira Automation"},"webhookUrl":{"type":"string","description":"Webhook URL for Jira Automation to call"},"source":{"type":"string","const":"jira-automation"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"},"createAlert":{"type":"boolean","description":"Deprecated compatibility alias for eventMode"}},"required":["triggerId","name","secret","webhookUrl","source"]},{"type":"object","properties":{"name":{"type":"string","description":"Display name for the trigger"},"description":{"type":"string","description":"Optional description of what this trigger does"},"source":{"type":"string","const":"slack"},"allowedUserIds":{"type":"array","items":{"type":"string"},"description":"Optional array of Slack user IDs allowed to trigger this agent"},"allowedUsergroupIds":{"type":"array","items":{"type":"string"},"description":"Optional array of Slack usergroup IDs allowed to trigger this agent"},"allowedChannelIds":{"type":"array","items":{"type":"string"},"description":"Optional array of Slack channel IDs where this trigger is allowed"},"replyScope":{"type":"string","enum":["anyone","cotool_users"],"description":"Who may reply in a Slack thread to continue this agent (anyone | cotool_users). Ignored when a user/usergroup allow list is set"},"reactionEmojis":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Slack emoji short names (no colons) that trigger this agent when added as a reaction to a message, e.g. [\"rotating_light\"]. Empty or absent means reactions do not trigger this agent","example":["rotating_light"]},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"},"createAlert":{"type":"boolean","description":"Deprecated compatibility alias for eventMode"}},"required":["name","source"]},{"type":"object","properties":{"triggerId":{"type":"string","format":"uuid","description":"Unique identifier for the trigger (required for legacy-webhook mode)"},"name":{"type":"string","description":"Display name for the trigger"},"description":{"type":"string","description":"Optional description of what this trigger does"},"secret":{"type":"string","description":"Secret for webhook authentication (required for legacy-webhook mode)"},"webhookUrl":{"type":"string","description":"Webhook URL for Linear to call (required for legacy-webhook mode)"},"source":{"type":"string","const":"linear"},"linearMode":{"type":"string","enum":["agent-session","legacy-webhook"],"description":"Agent Session mode (default) or legacy webhook mode"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"},"createAlert":{"type":"boolean","description":"Deprecated compatibility alias for eventMode"}},"required":["name","source"]},{"type":"object","properties":{"name":{"type":"string","description":"Display name for the trigger"},"description":{"type":"string","description":"Optional description of what this trigger does"},"source":{"type":"string","const":"cron"},"schedule":{"type":"string","description":"Cron schedule expression (e.g., \"0 9 * * 1-5\" for weekdays at 9 AM)"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"},"createAlert":{"type":"boolean","description":"Deprecated compatibility alias for eventMode"}},"required":["name","source","schedule"]},{"type":"object","properties":{"triggerId":{"type":"string","format":"uuid","description":"Unique identifier for the trigger"},"name":{"type":"string","description":"Display name for the trigger"},"description":{"type":"string","description":"Optional description of what this trigger does"},"secret":{"type":"string","description":"Authentication token for the webhook"},"webhookUrl":{"type":"string","description":"Webhook URL for external services to call"},"source":{"type":"string","const":"webhook"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"},"createAlert":{"type":"boolean","description":"Deprecated compatibility alias for eventMode"}},"required":["triggerId","name","secret","webhookUrl","source"]},{"type":"object","properties":{"triggerId":{"type":"string","format":"uuid","description":"Unique identifier for the trigger"},"name":{"type":"string","description":"Display name for the trigger"},"description":{"type":"string","description":"Optional description of what this trigger does"},"emailAddress":{"type":"string","description":"Email address for the trigger"},"source":{"type":"string","const":"email"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"},"createAlert":{"type":"boolean","description":"Deprecated compatibility alias for eventMode"}},"required":["triggerId","name","emailAddress","source"]},{"type":"object","properties":{"triggerId":{"type":"string","format":"uuid","description":"Unique identifier for the trigger"},"name":{"type":"string","description":"Display name for the trigger"},"description":{"type":"string","description":"Optional description of what this trigger does"},"secret":{"type":"string","description":"HackerOne signing secret used to verify the X-H1-Signature header"},"webhookUrl":{"type":"string","description":"Webhook URL for HackerOne to call"},"source":{"type":"string","const":"hackerone"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"},"createAlert":{"type":"boolean","description":"Deprecated compatibility alias for eventMode"}},"required":["triggerId","name","secret","webhookUrl","source"]},{"type":"object","properties":{"triggerId":{"type":"string","format":"uuid","description":"Unique identifier for the trigger"},"name":{"type":"string","description":"Display name for the trigger"},"description":{"type":"string","description":"Optional description of what this trigger does"},"secret":{"type":"string","description":"Bugcrowd-generated signing secret used to verify the X-Bugcrowd-Digest signature"},"webhookUrl":{"type":"string","description":"Webhook URL for Bugcrowd to call"},"source":{"type":"string","const":"bugcrowd"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"},"createAlert":{"type":"boolean","description":"Deprecated compatibility alias for eventMode"}},"required":["triggerId","name","secret","webhookUrl","source"]},{"type":"object","properties":{"triggerId":{"type":"string","format":"uuid","description":"Unique identifier for the trigger"},"name":{"type":"string","description":"Display name for the trigger"},"description":{"type":"string","description":"Optional description of what this trigger does"},"secret":{"type":"string","description":"Token Zscaler sends in the X-Cotool-Webhook-Token header (or as a bearer token)"},"webhookUrl":{"type":"string","description":"Webhook URL for Zscaler Cloud NSS feeds or alert webhooks to call"},"source":{"type":"string","const":"zscaler"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"},"createAlert":{"type":"boolean","description":"Deprecated compatibility alias for eventMode"}},"required":["triggerId","name","secret","webhookUrl","source"]},{"type":"object","properties":{"triggerId":{"type":"string","format":"uuid","description":"Unique identifier for the trigger"},"name":{"type":"string","description":"Display name for the trigger"},"description":{"type":"string","description":"Optional description of what this trigger does"},"secret":{"type":"string","description":"Generated HTTP Basic authentication password for Darktrace"},"webhookUrl":{"type":"string","description":"Webhook URL for Darktrace to call"},"source":{"type":"string","const":"darktrace"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"},"createAlert":{"type":"boolean","description":"Deprecated compatibility alias for eventMode"}},"required":["triggerId","name","secret","webhookUrl","source"]}],"description":"Request body for creating a new trigger, with different fields required based on the source type"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"]},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"First-class event behavior. Missing only on legacy serialized snapshots."},"name":{"type":"string"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secret":{"type":["string","null"]},"cronSchedule":{"type":["string","null"]},"emailAddress":{"type":["string","null"]},"config":{"type":"object","additionalProperties":{}},"lastRunAttemptedAt":{"type":["string","null"]},"lastRunSucceededAt":{"type":["string","null"]}},"required":["id","agentId","organizationId","source","name","enabled","createdAt","updatedAt","config"]}},"required":["success","data"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/trigger/{source}/{triggerId}":{"post":{"summary":"Webhook trigger","description":"Invoke an agent trigger via incoming webhook. External services post to this endpoint.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/trigger/:source/:triggerId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"example\":\"any_value\",\"note\":\"This field can contain any type of data\"}'"}],"parameters":[{"in":"path","name":"source","description":"Source system sending the webhook (jira, jira-automation, slack, linear, webhook, bugcrowd, hackerone, zscaler, darktrace)","schema":{"type":"string","enum":["jira","jira-automation","slack","linear","webhook","bugcrowd","hackerone","zscaler","darktrace"],"description":"Source system sending the webhook (jira, jira-automation, slack, linear, webhook, bugcrowd, hackerone, zscaler, darktrace)"},"required":true},{"in":"path","name":"triggerId","description":"Unique identifier of the trigger to invoke","schema":{"type":"string","format":"uuid","description":"Unique identifier of the trigger to invoke"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"description":"Body of the webhook request. This can be any value, and it will be passed as input to the agent."}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"executionId":{"type":"string","description":"Unique identifier for the agent execution"}},"required":["executionId"],"description":"Response from webhook trigger containing execution ID. Use this to retrieve the execution status of the agent."},{"type":"object","properties":{"executionId":{"type":"string","const":"skipped","description":"Indicates the webhook was skipped"},"message":{"type":"string","description":"Reason why the webhook was skipped"},"action":{"type":"string","description":"The action that caused the webhook to be skipped"}},"required":["executionId","message","action"],"description":"Response from webhook trigger containing execution ID, skip message, or error message"},{"type":"object","properties":{"error":{"type":"string","description":"Error message if webhook processing failed"}},"required":["error"],"description":"Response from webhook trigger containing error message"}],"description":"Response from webhook trigger containing execution ID, skip message, or error message"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/chat/history":{"get":{"summary":"Get chat history","description":"Retrieve all events and chat metadata for the specified chat conversation. If the chat has a structured output schema, the generated structured output is returned in `chat.result`.","tags":["Chat"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/chat/history\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"chatId","description":"Unique identifier of the chat to retrieve history for","schema":{"type":"string","format":"uuid","description":"Unique identifier of the chat to retrieve history for"},"required":true},{"in":"query","name":"limit","description":"Optional page size for paginated history fetch (1-100)","schema":{"type":"number","minimum":1,"maximum":100,"description":"Optional page size for paginated history fetch (1-100)"}},{"in":"query","name":"beforeCursor","description":"Cursor for loading older events","schema":{"type":"string","pattern":"^\\d+:[0-9a-fA-F-]{36}$","description":"Cursor for loading older events"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/ChatEvent"},"description":"Array of chat event objects"},"chat":{"oneOf":[{"$ref":"#/components/schemas/Chat"},{"type":"null"}],"description":"Chat details or null if not found"},"feedbackByEvent":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string","enum":["up","down"]},"createdAt":{"type":"string"}},"required":["label","createdAt"]},"description":"Latest human thumb feedback keyed by chat event id"},"nextCursor":{"type":["string","null"],"pattern":"^\\d+:[0-9a-fA-F-]{36}$","description":"Cursor for loading older events"},"hasMore":{"type":"boolean","description":"Whether more older events are available"}},"required":["events","chat"],"description":"Chat history response containing events and chat metadata"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/chat/meta":{"get":{"summary":"Get chat metadata","description":"Retrieve lightweight chat metadata (title and per-event feedback) without loading the full event history. Prefer this over /api/chat/history when only the chat header (title + feedback) is needed.","tags":["Chat"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/chat/meta\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"chatId","description":"Unique identifier of the chat to retrieve metadata for","schema":{"type":"string","format":"uuid","description":"Unique identifier of the chat to retrieve metadata for"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"chatId":{"type":"string","description":"Identifier of the chat the metadata belongs to"},"title":{"type":["string","null"],"description":"Chat title, or null if the chat has no title yet"},"agentId":{"type":["string","null"],"description":"Agent that owns this chat, or null for non-agent chats"},"detectionId":{"type":["string","null"],"description":"Detection that owns this chat, or null for non-detection chats"},"feedbackByEvent":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string","enum":["up","down"]},"createdAt":{"type":"string"}},"required":["label","createdAt"]},"description":"Latest human thumb feedback keyed by chat event id"}},"required":["chatId","title","feedbackByEvent"],"description":"Lightweight chat metadata (title, owner, and per-event feedback) without the full event history"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/run-async":{"post":{"summary":"Run agent asynchronously","description":"Start an asynchronous agent run and return a runId that can be polled for status updates. Once the run status is `done`, call `/api/agents/:agentId/run-async/:runId/result` to retrieve the same final payload shape returned by the synchronous run endpoint.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agents/:agentId/run-async\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"inputs\":null,\"attachments\":[{\"fileId\":\"string\",\"fileName\":\"string\",\"size\":0,\"fileType\":\"image\",\"previewText\":\"string\"}]}'"}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent to execute","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent to execute"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"$ref":"#/components/schemas/JsonObject","description":"Input values for agent execution based on the agent input configuration"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileId":{"type":"string","description":"Unique identifier of the uploaded file"},"fileName":{"type":"string","description":"Name of the file"},"size":{"type":"number","description":"Size of the file in bytes"},"fileType":{"type":"string","enum":["image","pdf","spreadsheet","document","presentation","file"],"description":"Semantic file type for iconography"},"previewText":{"type":"string","description":"Optional text preview for text-like files"}},"required":["fileId","fileName","size"],"additionalProperties":false},"description":"Optional array of file attachments to include with the agent execution"}},"required":["inputs"],"description":"Input values for agent execution based on agent input configuration"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","format":"uuid","description":"Unique identifier for this asynchronous agent run that can be polled for status"}},"required":["runId"],"description":"Response containing run ID for asynchronous agent execution"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/run-async/{runId}":{"get":{"summary":"Get async run status (deprecated)","description":"> ⚠️ **Deprecated**\n> Superseded by the run status endpoint, which returns the run status (queued, running, waiting, done, error, interrupted) and any status message instead of a bare isStreaming flag. Poll GET /api/agents/{agentId}/run-async/{runId}/status until status is done, error, or interrupted, then fetch GET /api/agents/{agentId}/run-async/{runId}/result. No sunset is scheduled.\n> **Use instead:** `/api/agents/:agentId/run-async/:runId/status`\n\nRetrieve streaming status or error information for an asynchronous agent run.","tags":["Agents"],"deprecated":true,"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents/:agentId/run-async/:runId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true},{"in":"path","name":"runId","description":"Unique identifier of the asynchronous run to check status for","schema":{"type":"string","format":"uuid","description":"Unique identifier of the asynchronous run to check status for"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"isStreaming":{"type":"boolean","description":"Whether the run is actively streaming (in-progress)"},"error":{"type":"string","description":"Error message if the run failed"}},"required":["isStreaming"],"description":"Status information for asynchronous agent run"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/run-async/{runId}/status":{"get":{"summary":"Get async run status","description":"Retrieve streaming status or error information for an asynchronous agent run. Once the returned status is `done`, call `/api/agents/:agentId/run-async/:runId/result` for the completed payload.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents/:agentId/run-async/:runId/status\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true},{"in":"path","name":"runId","description":"Unique identifier of the asynchronous run to check status for","schema":{"type":"string","format":"uuid","description":"Unique identifier of the asynchronous run to check status for"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["queued","running","waiting","done","error","interrupted"],"description":"Chat execution status"},"statusMessage":{"type":"string","description":"Additional status context, typically error messages"}},"required":["status"],"description":"Status information for asynchronous agent run"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/run-async/{runId}/result":{"get":{"summary":"Get async run result","description":"Retrieve the completed result of an asynchronous agent run. Use the status endpoint first and call this endpoint once the run status is `done`.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents/:agentId/run-async/:runId/result\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true},{"in":"path","name":"runId","description":"Unique identifier of the asynchronous run to check status for","schema":{"type":"string","format":"uuid","description":"Unique identifier of the asynchronous run to check status for"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"finalAssistantMessage":{"type":"string","description":"The final text response from the assistant"},"allToolCallsMade":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"tool-call"},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"args":{}},"required":["type","toolCallId","toolName"]},"description":"All tool calls made during the agent run"},"allToolResultsReceived":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"tool-result"},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"result":{},"isError":{"type":"boolean"}},"required":["type","toolCallId","toolName"]},"description":"All tool results received during the agent run"},"messages":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"role":{"type":"string","const":"system"},"content":{"type":"string"}},"required":["role","content"]},{"type":"object","properties":{"role":{"type":"string","const":"user"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"image"},"image":{},"mimeType":{"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"file"},"data":{},"mimeType":{"type":"string"}},"required":["type"]}]}}]}},"required":["role","content"]},{"type":"object","properties":{"role":{"type":"string","const":"assistant"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"tool-call"},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"args":{}},"required":["type","toolCallId","toolName"]},{"type":"object","properties":{"type":{"type":"string","const":"reasoning"},"text":{"type":"string"},"signature":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"tool-result"},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"result":{},"isError":{"type":"boolean"}},"required":["type","toolCallId","toolName"]},{"type":"object","properties":{"type":{"type":"string","const":"file"},"data":{},"mimeType":{"type":"string"}},"required":["type"]}]}}]}},"required":["role","content"]},{"type":"object","properties":{"role":{"type":"string","const":"tool"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"tool-result"},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"result":{},"isError":{"type":"boolean"}},"required":["type","toolCallId","toolName"]}}},"required":["role","content"]}]},"description":"Complete message history from the agent run"},"structuredOutputResult":{"oneOf":[{"$ref":"#/components/schemas/JsonValue"},{"type":"null"}],"description":"Structured output generated after the run, if available"}},"required":["finalAssistantMessage","allToolCallsMade","allToolResultsReceived","messages"],"description":"Completed result of an asynchronous agent execution"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/run-sync":{"post":{"summary":"Run agent synchronously","description":"Execute an agent run in a blocking manner and return the complete result once finished.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agents/:agentId/run-sync\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"inputs\":null,\"attachments\":[{\"fileId\":\"string\",\"fileName\":\"string\",\"size\":0,\"fileType\":\"image\",\"previewText\":\"string\"}]}'"}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent to execute","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent to execute"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"$ref":"#/components/schemas/JsonObject","description":"Input values for agent execution based on the agent input configuration"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileId":{"type":"string","description":"Unique identifier of the uploaded file"},"fileName":{"type":"string","description":"Name of the file"},"size":{"type":"number","description":"Size of the file in bytes"},"fileType":{"type":"string","enum":["image","pdf","spreadsheet","document","presentation","file"],"description":"Semantic file type for iconography"},"previewText":{"type":"string","description":"Optional text preview for text-like files"}},"required":["fileId","fileName","size"],"additionalProperties":false},"description":"Optional array of file attachments to include with the agent execution"}},"required":["inputs"],"description":"Input values for agent execution based on agent input configuration"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"finalAssistantMessage":{"type":"string","description":"The final text response from the assistant"},"allToolCallsMade":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"tool-call"},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"args":{}},"required":["type","toolCallId","toolName"]},"description":"All tool calls made during the agent run"},"allToolResultsReceived":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"tool-result"},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"result":{},"isError":{"type":"boolean"}},"required":["type","toolCallId","toolName"]},"description":"All tool results received during the agent run"},"messages":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"role":{"type":"string","const":"system"},"content":{"type":"string"}},"required":["role","content"]},{"type":"object","properties":{"role":{"type":"string","const":"user"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"image"},"image":{},"mimeType":{"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"file"},"data":{},"mimeType":{"type":"string"}},"required":["type"]}]}}]}},"required":["role","content"]},{"type":"object","properties":{"role":{"type":"string","const":"assistant"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"tool-call"},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"args":{}},"required":["type","toolCallId","toolName"]},{"type":"object","properties":{"type":{"type":"string","const":"reasoning"},"text":{"type":"string"},"signature":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"tool-result"},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"result":{},"isError":{"type":"boolean"}},"required":["type","toolCallId","toolName"]},{"type":"object","properties":{"type":{"type":"string","const":"file"},"data":{},"mimeType":{"type":"string"}},"required":["type"]}]}}]}},"required":["role","content"]},{"type":"object","properties":{"role":{"type":"string","const":"tool"},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"tool-result"},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"result":{},"isError":{"type":"boolean"}},"required":["type","toolCallId","toolName"]}}},"required":["role","content"]}]},"description":"Complete message history from the agent run"},"structuredOutputResult":{"oneOf":[{"$ref":"#/components/schemas/JsonValue"},{"type":"null"}],"description":"Structured output generated after the run, if available"}},"required":["finalAssistantMessage","allToolCallsMade","allToolResultsReceived","messages"],"description":"Complete result of synchronous agent execution"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents":{"get":{"summary":"List all agents","description":"Retrieve a list of all AI agents available in the organization","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":true,"description":"Whether this agent is built in to the system (true for built-in (system-managed) agents)"},"builtInAgentType":{"type":"string","enum":["threat-relevancy","threat-research","autonomous-hunt","code-detection-tuner","test-agent"],"description":"Type of built-in agent (e.g., threat-validation, threat-hunt)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn","builtInAgentType"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":false,"description":"Whether this agent is built in to the system (false for custom (user-created) agents)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn"]}],"description":"Agent configuration - can be either a built in (system-managed) or custom (user-created) agent"},"description":"Array of all agents in the organization"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a new agent","description":"Create a new AI agent with specified configuration including system prompt, tools, and model settings","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agents\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\",\"description\":\"string\",\"systemPrompt\":\"string\",\"toolNames\":[\"string\"],\"toolSelectionMode\":\"manual\",\"cliNames\":[\"string\"],\"toolActionConfigs\":null,\"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,\"persistentWorkspaceEnabled\":true,\"tags\":[null],\"skills\":[{\"skillId\":\"string\",\"skillVersionId\":\"string\"}],\"acceptanceCriteria\":[\"string\"]}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name of the agent"},"description":{"type":"string","description":"Description of what the agent does"},"systemPrompt":{"type":"string","description":"System prompt that defines the agent behavior and instructions"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Optional per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Input configuration defining what inputs the agent expects"},"modelAlias":{"description":"Model alias must be a valid model from the registry"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional context documents to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"format":"uuid","description":"Optional reference to the Tines story import template used to create this agent"},"planningMode":{"type":"string","enum":["never","always","auto"],"description":"Optional planning behavior; defaults to auto"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"Optional structured output schema definition for this agent"},"persistentWorkspaceEnabled":{"type":"boolean","description":"Optional persistent workspace setting; defaults to enabled for new agents"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of the skill to attach"},"skillVersionId":{"type":"string","format":"uuid","description":"Optional specific version to pin for this agent binding"}},"required":["skillId"]},"description":"Optional set of skills to attach to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"}},"required":["name","description","systemPrompt","toolNames","inputs","modelAlias"],"description":"Request body for creating a new AI agent with configuration"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":true,"description":"Whether this agent is built in to the system (true for built-in (system-managed) agents)"},"builtInAgentType":{"type":"string","enum":["threat-relevancy","threat-research","autonomous-hunt","code-detection-tuner","test-agent"],"description":"Type of built-in agent (e.g., threat-validation, threat-hunt)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn","builtInAgentType"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":false,"description":"Whether this agent is built in to the system (false for custom (user-created) agents)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn"]}],"description":"The newly created agent with generated ID and timestamps"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}":{"get":{"summary":"Get agent","description":"Retrieve detailed information about a specific agent by ID.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents/:agentId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent to retrieve","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent to retrieve"},"required":true},{"in":"query","name":"chatId","description":"Optional chat ID used to authorize loading historical run metadata","schema":{"type":"string","format":"uuid","description":"Optional chat ID used to authorize loading historical run metadata"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":true,"description":"Whether this agent is built in to the system (true for built-in (system-managed) agents)"},"builtInAgentType":{"type":"string","enum":["threat-relevancy","threat-research","autonomous-hunt","code-detection-tuner","test-agent"],"description":"Type of built-in agent (e.g., threat-validation, threat-hunt)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn","builtInAgentType"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":false,"description":"Whether this agent is built in to the system (false for custom (user-created) agents)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn"]}],"description":"Complete agent configuration and metadata"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update agent","description":"Modify an agent's configuration, such as tools, prompts, or model settings.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/agents/:agentId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\",\"description\":\"string\",\"versionDescription\":\"string\",\"systemPrompt\":\"string\",\"toolNames\":[\"string\"],\"toolSelectionMode\":\"manual\",\"cliNames\":[\"string\"],\"toolActionConfigs\":null,\"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,\"persistentWorkspaceEnabled\":true,\"slackReplyScope\":\"anyone\",\"tags\":[null],\"skills\":[{\"skillId\":\"string\",\"skillVersionId\":\"string\"}],\"acceptanceCriteria\":[\"string\"]}'"}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent to update","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent to update"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Optional new name for the agent"},"description":{"type":"string","description":"Optional new description for the agent"},"versionDescription":{"type":"string","description":"Optional description for the agent version created by this update"},"systemPrompt":{"type":"string","description":"Optional new system prompt for the agent"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Optional new array of tool names for the agent"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"Optional new tool selection mode for the agent"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional new array of CLI integration ids for the agent"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Optional updated per-tool-action configuration for the agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Optional new input configuration for the agent"},"modelAlias":{"description":"Model alias must be a valid model from the registry"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional new context documents for the agent"},"tinesStoryImportId":{"type":["string","null"],"format":"uuid","description":"Optional reference to the Tines story import template (can be set to null to clear)"},"planningMode":{"type":"string","enum":["never","always","auto"],"description":"Optional new planning behavior for this agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"Optional updated structured output schema definition for this agent"},"persistentWorkspaceEnabled":{"type":"boolean","description":"Optional persistent workspace setting for this agent"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Optional default Slack reply scope for chats not started by a Slack trigger (anyone | cotool_users)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of the skill to attach"},"skillVersionId":{"type":"string","format":"uuid","description":"Optional specific version to pin for this agent binding"}},"required":["skillId"]},"description":"Optional set of skills to attach to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"}},"description":"Request body for updating agent configuration (all fields optional)"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":true,"description":"Whether this agent is built in to the system (true for built-in (system-managed) agents)"},"builtInAgentType":{"type":"string","enum":["threat-relevancy","threat-research","autonomous-hunt","code-detection-tuner","test-agent"],"description":"Type of built-in agent (e.g., threat-validation, threat-hunt)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn","builtInAgentType"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":false,"description":"Whether this agent is built in to the system (false for custom (user-created) agents)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn"]}],"description":"The updated agent with modified configuration"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete agent","description":"Remove an agent from the system.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X DELETE \"https://app.cotool.ai/api/agents/:agentId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent to delete","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent to delete"},"required":true}],"responses":{"200":{"description":"Successful response - no content"},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/copy":{"post":{"summary":"Convert a disconnected managed agent into a manual agent","description":"Convert a sync-managed (GitOps) agent whose integration is disconnected into an editable manual agent: copies its config + prompt, transfers its trigger rows (preserving email/webhook/Slack bindings), and parks the managed original as a recoverable soft-delete.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agents/:agentId/copy\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the sync-managed agent to copy","schema":{"type":"string","format":"uuid","description":"Unique identifier of the sync-managed agent to copy"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":true,"description":"Whether this agent is built in to the system (true for built-in (system-managed) agents)"},"builtInAgentType":{"type":"string","enum":["threat-relevancy","threat-research","autonomous-hunt","code-detection-tuner","test-agent"],"description":"Type of built-in agent (e.g., threat-validation, threat-hunt)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn","builtInAgentType"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":false,"description":"Whether this agent is built in to the system (false for custom (user-created) agents)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn"]}],"description":"The newly created, non-managed copy"},"parkedAgentId":{"type":"string","format":"uuid","description":"The now-parked (soft-deleted, recoverable) managed agent that was converted"},"parkedAgentName":{"type":"string","description":"Name of the parked managed agent"},"transferredTriggerNames":{"type":"array","items":{"type":"string"},"description":"Names of the triggers transferred from the parked agent to the copy (rows re-pointed, bindings preserved)"}},"required":["agent","parkedAgentId","parkedAgentName","transferredTriggerNames"],"description":"The manual copy, the parked original, and which triggers were transferred"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/batch":{"put":{"summary":"Batch update agents","description":"Atomically update many agents in a single SERIALIZABLE transaction. The entire batch succeeds or rolls back together; this avoids partial-failure modes seen when issuing many concurrent single-agent updates that conflict on the same rows.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/agents/batch\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"items\":[{\"name\":\"string\",\"description\":\"string\",\"versionDescription\":\"string\",\"systemPrompt\":\"string\",\"toolNames\":[\"string\"],\"toolSelectionMode\":\"manual\",\"cliNames\":[\"string\"],\"toolActionConfigs\":null,\"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,\"persistentWorkspaceEnabled\":true,\"slackReplyScope\":\"anyone\",\"tags\":[null],\"skills\":[{\"skillId\":\"string\",\"skillVersionId\":\"string\"}],\"acceptanceCriteria\":[\"string\"],\"id\":\"string\"}]}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Optional new name for the agent"},"description":{"type":"string","description":"Optional new description for the agent"},"versionDescription":{"type":"string","description":"Optional description for the agent version created by this update"},"systemPrompt":{"type":"string","description":"Optional new system prompt for the agent"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Optional new array of tool names for the agent"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"Optional new tool selection mode for the agent"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional new array of CLI integration ids for the agent"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Optional updated per-tool-action configuration for the agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Optional new input configuration for the agent"},"modelAlias":{"description":"Model alias must be a valid model from the registry"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional new context documents for the agent"},"tinesStoryImportId":{"type":["string","null"],"format":"uuid","description":"Optional reference to the Tines story import template (can be set to null to clear)"},"planningMode":{"type":"string","enum":["never","always","auto"],"description":"Optional new planning behavior for this agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"Optional updated structured output schema definition for this agent"},"persistentWorkspaceEnabled":{"type":"boolean","description":"Optional persistent workspace setting for this agent"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Optional default Slack reply scope for chats not started by a Slack trigger (anyone | cotool_users)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of the skill to attach"},"skillVersionId":{"type":"string","format":"uuid","description":"Optional specific version to pin for this agent binding"}},"required":["skillId"]},"description":"Optional set of skills to attach to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"id":{"type":"string","format":"uuid","description":"Identifier of the agent to update"}},"required":["id"],"description":"Single agent update inside a batch — same shape as the single-agent update body, plus the agent id."},"minItems":1,"maxItems":200,"description":"Per-agent update payloads. The whole batch is applied in a single transaction."}},"required":["items"],"description":"Atomically update many agents in a single transaction. The entire batch succeeds or rolls back together."}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":true,"description":"Whether this agent is built in to the system (true for built-in (system-managed) agents)"},"builtInAgentType":{"type":"string","enum":["threat-relevancy","threat-research","autonomous-hunt","code-detection-tuner","test-agent"],"description":"Type of built-in agent (e.g., threat-validation, threat-hunt)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn","builtInAgentType"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":false,"description":"Whether this agent is built in to the system (false for custom (user-created) agents)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn"]}],"description":"Agent configuration - can be either a built in (system-managed) or custom (user-created) agent"},"description":"The updated agents, in the same order as the request items. Items whose agent could not be found or read after update are omitted."}},"required":["agents"],"description":"Updated agents from a batch update."}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/response-agent-notification-defaults":{"get":{"summary":"Get response-agent notification defaults","description":"Retrieve organization-wide default notification settings for response-agent acceptance criteria failures and critical issues.","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/response-agent-notification-defaults\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the organization default response-agent notification settings"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns these default settings"},"enabled":{"type":"boolean","description":"Whether default response-agent failure/critical notifications are enabled"},"destinationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Default notification destinations for response agents"},"createdAt":{"type":"string","description":"When the settings were created"},"updatedAt":{"type":"string","description":"When the settings were last updated"}},"required":["id","organizationId","enabled","destinationIds","createdAt","updatedAt"],"description":"Organization-wide default failure/critical notification settings for response agents"},"destinations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"webhook"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication: \"bearer\" for Authorization: Bearer <token>, \"header\" for custom header"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\" (e.g., \"X-API-Key\")"}},"required":["url","authType"]},"token":{"type":"string","description":"The authentication token (only returned to authorized users)"},"hasToken":{"type":"boolean","description":"Whether a token is configured"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"teams"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["url"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"slack"},"config":{"type":"object","properties":{"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"},"configurationRevision":{"type":"integer","minimum":0,"description":"Revision of user-managed Slack delivery configuration"},"blockedChannels":{"type":"object","additionalProperties":{"type":"object","properties":{"reason":{"type":"string","const":"archived","description":"Why delivery to this Slack channel is blocked"},"blockedAt":{"type":"string","description":"When Slack reported that the channel was archived"}},"required":["reason","blockedAt"]},"description":"Channels that delivery will skip until a user updates the destination"}},"required":["channelIds"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"pagerduty"},"config":{"type":"object","properties":{"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts"},"source":{"type":"string","description":"Optional source identifier (defaults to detection name)"}},"required":["severity"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"linear"},"config":{"type":"object","properties":{"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names for display purposes"},"workflowStateId":{"type":"string","minLength":1,"description":"Linear workflow state ID for created issues"},"workflowStateName":{"type":"string","description":"Cached Linear workflow state name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"tines"},"config":{"type":"object","properties":{"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]}]},"description":"Available output destinations for the organization"}},"required":["settings","destinations"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update response-agent notification defaults","description":"Update organization-wide default notification settings inherited by response agents.","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/response-agent-notification-defaults\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"enabled\":true,\"destinationIds\":[\"string\"]}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether default failure/critical notifications are enabled"},"destinationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The default notification destinations to use"}},"required":["enabled","destinationIds"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the organization default response-agent notification settings"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns these default settings"},"enabled":{"type":"boolean","description":"Whether default response-agent failure/critical notifications are enabled"},"destinationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Default notification destinations for response agents"},"createdAt":{"type":"string","description":"When the settings were created"},"updatedAt":{"type":"string","description":"When the settings were last updated"}},"required":["id","organizationId","enabled","destinationIds","createdAt","updatedAt"],"description":"Organization-wide default failure/critical notification settings for response agents"},"destinations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"webhook"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication: \"bearer\" for Authorization: Bearer <token>, \"header\" for custom header"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\" (e.g., \"X-API-Key\")"}},"required":["url","authType"]},"token":{"type":"string","description":"The authentication token (only returned to authorized users)"},"hasToken":{"type":"boolean","description":"Whether a token is configured"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"teams"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["url"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"slack"},"config":{"type":"object","properties":{"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"},"configurationRevision":{"type":"integer","minimum":0,"description":"Revision of user-managed Slack delivery configuration"},"blockedChannels":{"type":"object","additionalProperties":{"type":"object","properties":{"reason":{"type":"string","const":"archived","description":"Why delivery to this Slack channel is blocked"},"blockedAt":{"type":"string","description":"When Slack reported that the channel was archived"}},"required":["reason","blockedAt"]},"description":"Channels that delivery will skip until a user updates the destination"}},"required":["channelIds"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"pagerduty"},"config":{"type":"object","properties":{"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts"},"source":{"type":"string","description":"Optional source identifier (defaults to detection name)"}},"required":["severity"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"linear"},"config":{"type":"object","properties":{"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names for display purposes"},"workflowStateId":{"type":"string","minLength":1,"description":"Linear workflow state ID for created issues"},"workflowStateName":{"type":"string","description":"Cached Linear workflow state name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"tines"},"config":{"type":"object","properties":{"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]}]},"description":"Available output destinations for the organization"}},"required":["settings","destinations"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/chats":{"get":{"summary":"List agent runs/chats","description":"Retrieve a paginated list of runs/chats associated with a specific agent.","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents/:agentId/chats\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent to list chats for","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent to list chats for"},"required":true},{"in":"query","name":"limit","description":"Maximum number of chats to return (1-100, default: 10)","schema":{"type":"number","minimum":1,"maximum":100,"default":10,"description":"Maximum number of chats to return (1-100, default: 10)"}},{"in":"query","name":"offset","description":"Number of chats to skip for pagination (default: 0)","schema":{"type":"number","minimum":0,"default":0,"description":"Number of chats to skip for pagination (default: 0)"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"chats":{"type":"array","items":{"$ref":"#/components/schemas/Chat"},"description":"Array of chat objects for this agent"},"totalCount":{"type":"number","description":"Total number of chats available for pagination"}},"required":["chats","totalCount"],"description":"Paginated list of chats with total count for pagination"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent-runs":{"get":{"summary":"List agent runs","description":"Retrieve a paginated list of historical agent execution runs with optional filters.","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agent-runs\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"page","description":"Page number for pagination (0-based, default: 0)","schema":{"type":"number","minimum":0,"default":0,"description":"Page number for pagination (0-based, default: 0)"}},{"in":"query","name":"pageSize","description":"Number of runs per page (1-100, default: 50)","schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Number of runs per page (1-100, default: 50)"}},{"in":"query","name":"sortField","description":"Field to sort by (default: createdAt)","schema":{"type":"string","enum":["createdAt","updatedAt","agentName","modelAlias","evalScore"],"default":"createdAt","description":"Field to sort by (default: createdAt)"}},{"in":"query","name":"sortDirection","description":"Sort direction (default: desc)","schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction (default: desc)"}},{"in":"query","name":"agentIdFilter","description":"Optional filter by exact agent id","schema":{"type":"string","format":"uuid","description":"Optional filter by exact agent id"}},{"in":"query","name":"agentNameFilter","description":"Optional filter by agent name (partial match)","schema":{"type":"string","description":"Optional filter by agent name (partial match)"}},{"in":"query","name":"searchQuery","description":"Optional search across execution ID, run/alert title, and agent name (partial match)","schema":{"type":"string","description":"Optional search across execution ID, run/alert title, and agent name (partial match)"}},{"in":"query","name":"toolFilter","description":"Optional comma-separated list of tool names to filter by","schema":{"type":"string","description":"Optional comma-separated list of tool names to filter by"}},{"in":"query","name":"dateFrom","description":"Optional start date filter (ISO string)","schema":{"type":"string","description":"Optional start date filter (ISO string)"}},{"in":"query","name":"dateTo","description":"Optional end date filter (ISO string)","schema":{"type":"string","description":"Optional end date filter (ISO string)"}},{"in":"query","name":"triggerSourceFilter","description":"Optional comma-separated list of trigger source values (manual, jira, slack, etc.)","schema":{"type":"string","description":"Optional comma-separated list of trigger source values (manual, jira, slack, etc.)"}},{"in":"query","name":"scoreFilters","description":"Optional JSON array of { op: gt|lt|eq|ge|le, value: number } for eval score filtering (applied as OR)","schema":{"type":"string","description":"Optional JSON array of { op: gt|lt|eq|ge|le, value: number } for eval score filtering (applied as OR)"}},{"in":"query","name":"noteworthyFilter","description":"When true, only return noteworthy runs: those with critical issues, failed acceptance criteria, or high/critical severity detection hits","schema":{"type":"string","description":"When true, only return noteworthy runs: those with critical issues, failed acceptance criteria, or high/critical severity detection hits"}},{"in":"query","name":"needsAttentionFilter","description":"When true, only return runs with critical issues or failed acceptance criteria","schema":{"type":"string","description":"When true, only return runs with critical issues or failed acceptance criteria"}},{"in":"query","name":"includeTotalCount","description":"When false, skip the exact pagination count and return zero for totalCount","schema":{"type":"string","description":"When false, skip the exact pagination count and return zero for totalCount"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the agent run"},"agentId":{"type":"string","format":"uuid","description":"ID of the agent that performed this run"},"agentName":{"type":"string","description":"Name of the agent that performed this run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard agent) or detection (security detection agent)"},"runTitle":{"type":"string","description":"Title/description of the run"},"createdAt":{"type":"string","description":"ISO timestamp when the run was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the run was last updated"},"modelAlias":{"type":"string","description":"Alias of the model used for this run"},"modelName":{"type":"string","description":"Full name of the model used for this run"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Names of tools used in this run (limited to first 5 tools for display)"},"totalToolCount":{"type":"integer","description":"Total number of tools invoked during this run"},"triggerSource":{"type":["string","null"],"description":"Source that triggered the run (e.g., manual, api, jira, slack, linear, cron, webhook, email)"},"triggerName":{"type":["string","null"],"description":"Name of the specific trigger that initiated the run"},"hasError":{"type":"boolean","description":"Whether the run encountered any errors"},"isStreaming":{"type":"boolean","description":"Whether the run is currently streaming (in-progress)"},"status":{"type":"string","enum":["queued","running","waiting","done","error","interrupted"],"description":"Chat execution status: queued (created but not yet claimed), running (actively executing), waiting (awaiting user response), done (completed), error (failed), interrupted (stopped by user)"},"evalScore":{"type":["number","null"],"description":"LLM evaluation score for this run (0-10 scale, null if not evaluated)"},"evalExplanation":{"type":["string","null"],"description":"Explanation of the evaluation score"},"evalBulletSummary":{"type":["array","null"],"items":{"type":"string"},"description":"Bullet-point summary of evaluation findings"},"criticalIssue":{"type":["object","null"],"properties":{"category":{"type":"string","enum":["authentication","connectivity","missing_data","permission","configuration","service_unavailable","content_filter"],"description":"Category of the critical issue (see: authentication, connectivity, missing_data, permission, configuration, service_unavailable)"},"explanation":{"type":"string","description":"One sentence explaining what went wrong"}},"required":["category","explanation"],"description":"Critical external blocker detected by LLM judge evaluation"},"acceptanceCriteriaResults":{"type":["array","null"],"items":{"type":"object","properties":{"criterion":{"type":"string","description":"The acceptance criterion being evaluated"},"met":{"type":"boolean","description":"Whether the agent run satisfied this acceptance criterion"},"explanation":{"type":"string","description":"Brief explanation of why the criterion was or was not met"}},"required":["criterion","met","explanation"]},"description":"Acceptance criteria evaluation results for this run"},"linkedAlert":{"type":["object","null"],"properties":{"displayId":{"type":"string","description":"Human-readable alert identifier"},"title":{"type":"string","description":"Linked alert title"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Current linked alert status"}},"required":["displayId","title","status"],"description":"Alert this run created or triaged, when available to the caller"},"parentRun":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"ID of the parent agent run that delegated this execution"},"agentId":{"type":"string","format":"uuid","description":"ID of the agent that delegated this execution"},"agentName":{"type":"string","description":"Name of the agent that delegated this execution"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of the agent that delegated this execution"},"runTitle":{"type":"string","description":"Title of the parent agent run"}},"required":["id","agentId","agentName","agentType","runTitle"],"description":"Parent agent run that delegated this execution, when readable by the caller"}},"required":["id","agentId","agentName","agentType","runTitle","createdAt","updatedAt","modelAlias","toolNames","totalToolCount","hasError","isStreaming"]},"description":"Array of agent run summaries matching the query"},"totalCount":{"type":"integer","description":"Total number of runs matching the filters (for pagination)"}},"required":["runs","totalCount"],"description":"Paginated list of agent execution runs with filtering and sorting"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/critical-issues":{"get":{"summary":"List critical issues","description":"Retrieve normalized critical issues from agent evaluations and code-detection circuit breakers.","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/critical-issues\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"limit","description":"Number of critical issues to return","schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Number of critical issues to return"}},{"in":"query","name":"offset","description":"Number of critical issues to skip","schema":{"type":"number","minimum":0,"default":0,"description":"Number of critical issues to skip"}},{"in":"query","name":"status","description":"Critical issue status filter","schema":{"type":"string","enum":["open","dismissed","resolved"],"default":"open","description":"Critical issue status filter"}},{"in":"query","name":"issueId","description":"Specific critical issue ID to return","schema":{"type":"string","format":"uuid","description":"Specific critical issue ID to return"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"alerts":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["authentication","connectivity","missing_data","permission","configuration","service_unavailable","content_filter"],"description":"Critical Issue Categories that prevented task completion (external blockers, not agent faults):\nauthentication: OAuth tokens, API keys, credentials failures\nconnectivity: Service/network connectivity issues\nmissing_data: Required data/logs not available\npermission: User lacks required permissions\nconfiguration: Misconfiguration (wrong settings, missing config)\nservice_unavailable: External service down or unresponsive\ncontent_filter: The LLM provider's content safety filter declined a request"},"explanation":{"type":"string"},"status":{"type":"string","enum":["open","dismissed","resolved"]},"dismissedAt":{"type":["string","null"]},"dismissedByUserId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"sourceType":{"type":"string","const":"agent_run"},"agentId":{"type":"string","format":"uuid"},"agentName":{"type":"string"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard agent) or detection (security detection agent)"},"runId":{"type":"string","format":"uuid"},"runTitle":{"type":"string"},"runCreatedAt":{"type":"string"},"agentRunEvalId":{"type":["string","null"],"format":"uuid"},"evaluatorType":{"type":"string"},"evaluatorVersion":{"type":"string"}},"required":["id","organizationId","category","explanation","status","dismissedAt","dismissedByUserId","createdAt","updatedAt","sourceType","agentId","agentName","agentType","runId","runTitle","runCreatedAt","agentRunEvalId","evaluatorType","evaluatorVersion"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["authentication","connectivity","missing_data","permission","configuration","service_unavailable","content_filter"],"description":"Critical Issue Categories that prevented task completion (external blockers, not agent faults):\nauthentication: OAuth tokens, API keys, credentials failures\nconnectivity: Service/network connectivity issues\nmissing_data: Required data/logs not available\npermission: User lacks required permissions\nconfiguration: Misconfiguration (wrong settings, missing config)\nservice_unavailable: External service down or unresponsive\ncontent_filter: The LLM provider's content safety filter declined a request"},"explanation":{"type":"string"},"status":{"type":"string","enum":["open","dismissed","resolved"]},"dismissedAt":{"type":["string","null"]},"dismissedByUserId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"sourceType":{"type":"string","const":"code_detection"},"codeDetectionId":{"type":"string","format":"uuid"},"codeDetectionName":{"type":"string"},"codeDetectionExecutionId":{"type":"string","format":"uuid"},"executionKind":{"type":"string","enum":["editor","manual","scheduled"]},"executionStartedAt":{"type":"string"}},"required":["id","organizationId","category","explanation","status","dismissedAt","dismissedByUserId","createdAt","updatedAt","sourceType","codeDetectionId","codeDetectionName","codeDetectionExecutionId","executionKind","executionStartedAt"]}]}},"totalCount":{"type":"integer"}},"required":["alerts","totalCount"],"description":"Paginated list of normalized critical issues"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/critical-issues/{issueId}/dismiss":{"post":{"summary":"Dismiss critical issue","description":"Dismiss an open critical issue so it no longer appears in the active issues feed.","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/critical-issues/:issueId/dismiss\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"issueId","description":"Critical issue ID","schema":{"type":"string","format":"uuid","description":"Critical issue ID"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"],"description":"Result of dismissing a critical issue"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent-runs/{runId}/feedback":{"post":{"summary":"Submit feedback for an agent run","description":"Submits user feedback (thumbs up/down) for a specific agent run, optionally including a comment and chat event reference","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agent-runs/:runId/feedback\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"label\":\"up\",\"agentId\":\"string\",\"chatEventId\":\"string\",\"comment\":\"string\"}'"}],"parameters":[{"in":"path","name":"runId","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","enum":["up","down"]},"agentId":{"type":"string","format":"uuid"},"chatEventId":{"type":"string","format":"uuid"},"comment":{"type":"string","maxLength":1000}},"required":["label"]}}}},"responses":{"200":{"description":"Successful response - no content"},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent-runs/feedback-batch":{"post":{"summary":"Submit feedback for multiple agent runs","description":"Submits user feedback (thumbs up/down) for multiple agent runs in a single batch operation","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agent-runs/feedback-batch\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"items\":[{\"agentId\":\"string\",\"runId\":\"string\",\"label\":\"up\",\"comment\":\"string\"}]}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"label":{"type":"string","enum":["up","down"]},"comment":{"type":"string","maxLength":1000}},"required":["agentId","runId","label"]},"minItems":1}},"required":["items"]}}}},"responses":{"200":{"description":"Successful response - no content"},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/feedback-metrics":{"get":{"summary":"Get detailed feedback metrics for an agent","description":"Retrieves comprehensive feedback metrics for a single agent including time-series data, per-prompt breakdown (optional), and all-time statistics","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents/:agentId/feedback-metrics\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"groupByPrompt","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"avgScore7d":{"type":["number","null"]},"avgScore30d":{"type":["number","null"]},"upRate7d":{"type":["number","null"]},"upRate30d":{"type":["number","null"]},"total7d":{"type":"integer"},"total30d":{"type":"integer"},"series30d":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"avgScore":{"type":"number"},"upRate":{"type":["number","null"]},"count":{"type":"integer"}},"required":["date","avgScore","upRate","count"]}},"byPrompt":{"type":"array","items":{"type":"object","properties":{"agentVersionId":{"type":["string","null"],"format":"uuid"},"description":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["active","previous",null]},"avgScoreAllTime":{"type":["number","null"]},"upRateAllTime":{"type":["number","null"]},"totalAllTime":{"type":"integer"},"avgScore7d":{"type":["number","null"]},"upRate7d":{"type":["number","null"]},"total7d":{"type":"integer"},"avgScore30d":{"type":["number","null"]},"upRate30d":{"type":["number","null"]},"total30d":{"type":"integer"}},"required":["agentVersionId","description","status","avgScoreAllTime","upRateAllTime","totalAllTime","avgScore7d","upRate7d","total7d","avgScore30d","upRate30d","total30d"]}},"avgScoreAllTime":{"type":["number","null"]},"upRateAllTime":{"type":["number","null"]},"totalAllTime":{"type":"integer"}},"required":["agentId","avgScore7d","avgScore30d","upRate7d","upRate30d","total7d","total30d","series30d","avgScoreAllTime","upRateAllTime","totalAllTime"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/llm-eval-metrics":{"get":{"summary":"Get LLM evaluation metrics","description":"Retrieve system LLM evaluation metrics for an agent (default evaluator: llm-judge).","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents/:agentId/llm-eval-metrics\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","description":"Agent ID","schema":{"type":"string","format":"uuid","description":"Agent ID"},"required":true},{"in":"query","name":"evaluatorType","description":"Evaluator type (default: llm-judge)","schema":{"type":"string","description":"Evaluator type (default: llm-judge)"}},{"in":"query","name":"groupByPrompt","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"evaluatorType":{"type":"string"},"avgScore7d":{"type":["number","null"]},"avgScore30d":{"type":["number","null"]},"avgScoreAllTime":{"type":["number","null"]},"total7d":{"type":"integer"},"total30d":{"type":"integer"},"totalAllTime":{"type":"integer"},"series30d":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"avgScore":{"type":"number"},"count":{"type":"integer"}},"required":["date","avgScore","count"]}},"byPrompt":{"type":"array","items":{"type":"object","properties":{"agentVersionId":{"type":["string","null"],"format":"uuid"},"description":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["active","previous",null]},"avgScoreAllTime":{"type":["number","null"]},"totalAllTime":{"type":["integer","null"]},"avgScore7d":{"type":["number","null"]},"total7d":{"type":"integer"},"avgScore30d":{"type":["number","null"]},"total30d":{"type":"integer"}},"required":["agentVersionId","description","status","avgScoreAllTime","totalAllTime","avgScore7d","total7d","avgScore30d","total30d"]}}},"required":["agentId","evaluatorType","avgScore7d","avgScore30d","avgScoreAllTime","total7d","total30d","totalAllTime","series30d"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/llm-eval-metrics/batch":{"post":{"summary":"Get LLM evaluation metrics for multiple agents","description":"Retrieve system LLM evaluation metrics (llm-judge) for multiple agents in batch.","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agents/llm-eval-metrics/batch\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"agentIds\":[\"string\"]}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of agent IDs"}},"required":["agentIds"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"avgScore7d":{"type":["number","null"]},"avgScore30d":{"type":["number","null"]},"totalEvals7d":{"type":"integer"},"totalEvals30d":{"type":"integer"}},"required":["agentId","avgScore7d","avgScore30d","totalEvals7d","totalEvals30d"]}}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent-runs/trigger-sources":{"get":{"summary":"List trigger sources","description":"Retrieve all distinct trigger sources used across agent runs in this organization.","tags":["Agent Runs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agent-runs/trigger-sources\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"},"description":"Distinct trigger sources present in this organization (includes manual)"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent-tags":{"get":{"summary":"List agent tags","description":"Retrieve all tags available in the organization with their usage counts.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agent-tags\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the tag"},"name":{"type":"string","description":"Tag name"},"agentCount":{"type":"number","description":"Total number of agents and detections using this tag"},"responseAgentCount":{"type":"number","description":"Number of response agents using this tag"},"detectionCount":{"type":"number","description":"Number of detections using this tag"}},"required":["id","name","agentCount"]},"description":"List of all tags in the organization with usage counts"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create agent tag","description":"Create a new tag in the organization.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agent-tags\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":null}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Name of the tag to create"}},"required":["name"],"description":"Request body for creating a tag"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the created tag"},"name":{"type":"string","description":"Name of the created tag"}},"required":["id","name"],"description":"Result of tag creation"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent-tags/{tagId}":{"delete":{"summary":"Delete agent tag","description":"Delete a tag from the organization. Requires setting.tags.manage permission. Will fail if the tag is still assigned to any agents.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X DELETE \"https://app.cotool.ai/api/agent-tags/:tagId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"tagId","description":"Unique identifier of the tag to delete","schema":{"type":"string","format":"uuid","description":"Unique identifier of the tag to delete"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the deletion was successful"},"error":{"type":"string","description":"Error message if deletion failed"}},"required":["success"],"description":"Result of tag deletion"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Rename agent tag","description":"Rename a tag in the organization. Requires setting.tags.manage permission.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/agent-tags/:tagId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":null}'"}],"parameters":[{"in":"path","name":"tagId","description":"Unique identifier of the tag to rename","schema":{"type":"string","format":"uuid","description":"Unique identifier of the tag to rename"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"New name for the tag"}},"required":["name"],"description":"Request body for renaming a tag"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the rename was successful"},"error":{"type":"string","description":"Error message if rename failed"}},"required":["success"],"description":"Result of tag rename"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent-templates":{"get":{"summary":"List agent templates","description":"Retrieve all available agent templates for the current organization.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agent-templates\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"systemPrompt":{"type":"string"},"selectedTools":{"type":"array","items":{"type":"string"}},"modelAlias":{},"enabled":{"type":"boolean"},"missingRequiredCapabilities":{"type":"array","items":{"type":"string","enum":["logQuerying","detectionAuthoring","detectionRuleReading","detectionResultReading","endpoint","threatIntel","ticketing","messaging","identityManagement","email","readingCode","writingCode","knowledgeBase","workflowAutomation","securityPosture","peopleManagement","visualization","utility"]}}},"required":["name","description","systemPrompt","selectedTools","modelAlias","enabled"]}}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/versions":{"get":{"summary":"List agent versions","description":"List the whole-definition version timeline for an agent (newest first)","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/agents/:agentId/versions\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"definition":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"modelAlias":{},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode: auto (plan when needed), never (skip planning), or always (always create a plan first)"},"agentFilesystem":{"type":"boolean"},"toolNames":{"type":"array","items":{"type":"string"}},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"Tool selection behavior: manual uses the stored tool list, all_read_only resolves all non-mutating tools at runtime"},"slackReplyScope":{"type":"string","enum":["anyone","cotool_users"],"description":"Who may reply in a Slack thread to continue this agent: anyone (any Slack user) or cotool_users (only mapped Cotool users with execute permission)"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Optional per-tool-action configuration entries for the agent"},"agentTools":{"type":"array","items":{"type":"object","properties":{"sync_key":{"type":"string"}},"required":["sync_key"]}},"cliNames":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"string"}},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]}},"acceptanceCriteria":{"type":"array","items":{"type":"string"}},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]}},"triggers":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["cron","webhook","jira-automation","jira","slack","linear","email","bugcrowd","hackerone","zscaler","darktrace"]},"sync_key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"schedule":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"jqlFilter":{"type":"string"},"issuePropertyKeysFilter":{"type":"array","items":{"type":"string"}},"fieldIdsFilter":{"type":"array","items":{"type":"string"}},"allowedChannelIds":{"type":"array","items":{"type":"string"}},"allowedUserIds":{"type":"array","items":{"type":"string"}},"allowedUsergroupIds":{"type":"array","items":{"type":"string"}},"replyScope":{"type":"string","enum":["anyone","cotool_users"],"description":"Who may reply in a Slack thread to continue this agent: anyone (any Slack user) or cotool_users (only mapped Cotool users with execute permission)"},"reactionEmojis":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["agent-session","legacy-webhook"]},"resourceTypes":{"type":"array","items":{"type":"string"}},"emailAddress":{"type":"string"}},"required":["source","name"]}},"structuredOutputSchema":{"$ref":"#/components/schemas/CotoolJsonSchema"},"systemPrompt":{"type":"string"},"syncKey":{"type":"string"}},"required":["name","modelAlias","systemPrompt"],"additionalProperties":true},"origin":{"type":"string","enum":["user","sync"]},"sourceCommitSha":{"type":["string","null"]},"changedByUserId":{"type":["string","null"],"format":"uuid"},"changedByEmail":{"type":["string","null"]},"description":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","agentId","definition","origin","sourceCommitSha","changedByUserId","changedByEmail","description","createdAt"]}}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/versions/{versionId}/revert":{"post":{"summary":"Revert an agent to a previous version","description":"Re-applies a previously-recorded version's whole-definition snapshot (prompt + spec + tags + skills) onto the live agent, recording a new head version equal to the chosen one. Requires agent.edit.","tags":["Agents"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agents/:agentId/versions/:versionId/revert\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"agentId","schema":{"type":"string","format":"uuid"},"required":true},{"in":"path","name":"versionId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"definition":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"modelAlias":{},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode: auto (plan when needed), never (skip planning), or always (always create a plan first)"},"agentFilesystem":{"type":"boolean"},"toolNames":{"type":"array","items":{"type":"string"}},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"Tool selection behavior: manual uses the stored tool list, all_read_only resolves all non-mutating tools at runtime"},"slackReplyScope":{"type":"string","enum":["anyone","cotool_users"],"description":"Who may reply in a Slack thread to continue this agent: anyone (any Slack user) or cotool_users (only mapped Cotool users with execute permission)"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Optional per-tool-action configuration entries for the agent"},"agentTools":{"type":"array","items":{"type":"object","properties":{"sync_key":{"type":"string"}},"required":["sync_key"]}},"cliNames":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"string"}},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]}},"acceptanceCriteria":{"type":"array","items":{"type":"string"}},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]}},"triggers":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["cron","webhook","jira-automation","jira","slack","linear","email","bugcrowd","hackerone","zscaler","darktrace"]},"sync_key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether an inbound event runs the configured agent directly or creates a Cotool alert before routing to the agent."},"schedule":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"jqlFilter":{"type":"string"},"issuePropertyKeysFilter":{"type":"array","items":{"type":"string"}},"fieldIdsFilter":{"type":"array","items":{"type":"string"}},"allowedChannelIds":{"type":"array","items":{"type":"string"}},"allowedUserIds":{"type":"array","items":{"type":"string"}},"allowedUsergroupIds":{"type":"array","items":{"type":"string"}},"replyScope":{"type":"string","enum":["anyone","cotool_users"],"description":"Who may reply in a Slack thread to continue this agent: anyone (any Slack user) or cotool_users (only mapped Cotool users with execute permission)"},"reactionEmojis":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["agent-session","legacy-webhook"]},"resourceTypes":{"type":"array","items":{"type":"string"}},"emailAddress":{"type":"string"}},"required":["source","name"]}},"structuredOutputSchema":{"$ref":"#/components/schemas/CotoolJsonSchema"},"systemPrompt":{"type":"string"},"syncKey":{"type":"string"}},"required":["name","modelAlias","systemPrompt"],"additionalProperties":true},"origin":{"type":"string","enum":["user","sync"]},"sourceCommitSha":{"type":["string","null"]},"changedByUserId":{"type":["string","null"],"format":"uuid"},"changedByEmail":{"type":["string","null"]},"description":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","agentId","definition","origin","sourceCommitSha","changedByUserId","changedByEmail","description","createdAt"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts":{"get":{"summary":"List alerts","description":"Retrieve first-class alert work items for the current organization. Archived dismissed, duplicate, and expired alerts are excluded unless a status filter is provided.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/alerts\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"limit","description":"Maximum number of alerts to return per page","schema":{"type":"integer","minimum":1,"maximum":200,"default":100,"description":"Maximum number of alerts to return per page"}},{"in":"query","name":"offset","description":"Number of alerts to skip for pagination","schema":{"type":"integer","minimum":0,"default":0,"description":"Number of alerts to skip for pagination"}},{"in":"query","name":"status","description":"Comma-separated alert statuses to include","schema":{"type":"string","description":"Comma-separated alert statuses to include"}},{"in":"query","name":"source","description":"Comma-separated alert source names to include","schema":{"type":"string","description":"Comma-separated alert source names to include"}},{"in":"query","name":"severity","description":"Comma-separated severities to include","schema":{"type":"string","description":"Comma-separated severities to include"}},{"in":"query","name":"assignedAgentId","description":"Only include alerts assigned to this response agent","schema":{"type":"string","format":"uuid","description":"Only include alerts assigned to this response agent"}},{"in":"query","name":"detection","description":"Alert detection filter key returned by /api/alerts/filter-options","schema":{"type":"string","description":"Alert detection filter key returned by /api/alerts/filter-options"}},{"in":"query","name":"detectionId","description":"Only include alerts tied to this Cotool detection","schema":{"type":"string","format":"uuid","description":"Only include alerts tied to this Cotool detection"}},{"in":"query","name":"originAgentId","description":"Only include alerts created by this origin agent","schema":{"type":"string","format":"uuid","description":"Only include alerts created by this origin agent"}},{"in":"query","name":"originDetectionHitId","description":"Only include the alert created from this detection hit","schema":{"type":"string","format":"uuid","description":"Only include the alert created from this detection hit"}},{"in":"query","name":"createdAfter","description":"Only include alerts created at or after this ISO timestamp","schema":{"type":"string","format":"date-time","description":"Only include alerts created at or after this ISO timestamp"}},{"in":"query","name":"q","description":"Free-text search over alert title, description, detection name, and origin references","schema":{"type":"string","minLength":1,"maxLength":500,"description":"Free-text search over alert title, description, detection name, and origin references"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]}},"totalCount":{"type":"integer","minimum":0,"description":"Total number of matching alerts for pagination"}},"required":["alerts","totalCount"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts/filter-options":{"get":{"summary":"Get alert filter options","description":"Return alert filter options derived from readable alerts, including Cotool and externally extracted detections.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/alerts/filter-options\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"detections":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"Opaque detection filter key accepted by the list alerts endpoint"},"label":{"type":"string","minLength":1,"description":"Human-readable detection name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this is a Cotool detection or an extracted external detection"},"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection id, when applicable"},"name":{"type":"string","minLength":1,"description":"Detection name stored on alert rows"},"count":{"type":"integer","minimum":0,"description":"Number of readable alerts for this detection filter"}},"required":["key","label","kind","id","name","count"]},"description":"Detection filter options derived from readable alerts"},"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Source filter key accepted by the list alerts endpoint"},"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Source category for the option (agent, detection, trigger, or hunt)"},"count":{"type":"integer","minimum":0,"description":"Number of readable alerts for this source"}},"required":["name","category","count"]},"description":"Source filter options actually present on readable alerts"}},"required":["detections","sources"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alert-routing":{"get":{"summary":"Get alert routing overview","description":"Return detection alert routing defaults, per-detection effective routing, alert producers, and response-agent handling summary.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/alert-routing\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"defaultSettings":{"type":"object","properties":{"organizationId":{"type":"string","format":"uuid","description":"Organization that owns these alert routing defaults"},"defaultResponseAgentId":{"type":["string","null"],"format":"uuid","description":"Default agent for alerts without an explicit route"},"defaultResponseAgentName":{"type":["string","null"],"description":"Display name for the configured default alert agent"},"createdAt":{"type":"string","description":"ISO timestamp when the organization row was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the routing default was last updated"}},"required":["organizationId","defaultResponseAgentId","defaultResponseAgentName","createdAt","updatedAt"]},"responseAgents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Response agent identifier"},"name":{"type":"string","minLength":1,"description":"Response agent display name"}},"required":["id","name"]}},"detections":{"type":"array","items":{"type":"object","properties":{"detectionAgentId":{"type":"string","format":"uuid","description":"Detection agent identifier"},"detectionAgentName":{"type":"string","minLength":1,"description":"Detection agent name"},"isAutonomousHunt":{"type":"boolean","description":"True for the built-in Autonomous Hunt orchestrator, which has no navigable detection detail page for non-admins"},"override":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Detection alert routing override id"},"detectionAgentId":{"type":"string","format":"uuid","description":"Detection agent this override applies to"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this override"},"responseAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent override, or null to leave alerts unassigned"},"responseAgentName":{"type":["string","null"],"description":"Display name for the override response agent"},"createdAt":{"type":"string","description":"ISO timestamp when the override was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the override was last updated"}},"required":["id","detectionAgentId","organizationId","responseAgentId","responseAgentName","createdAt","updatedAt"],"description":"Per-detection override, if configured"},"effective":{"type":"object","properties":{"detectionAgentId":{"type":"string","format":"uuid","description":"Detection agent this effective routing applies to"},"responseAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent that will handle new alerts, if configured"},"responseAgentName":{"type":["string","null"],"description":"Display name for the effective response agent"},"source":{"type":"string","enum":["detection_override","organization_default"],"description":"Whether the effective setting comes from an override or organization default"},"inheritedDefaultResponseAgentId":{"type":["string","null"],"format":"uuid","description":"Organization default response agent id used for inheritance"},"inheritedDefaultResponseAgentName":{"type":["string","null"],"description":"Organization default response agent name used for inheritance"}},"required":["detectionAgentId","responseAgentId","responseAgentName","source","inheritedDefaultResponseAgentId","inheritedDefaultResponseAgentName"],"description":"Effective alert routing for this detection"},"alertCount30d":{"type":"integer","minimum":0,"description":"Detection-created alert count over the last 30 days"},"openUnassignedCount":{"type":"integer","minimum":0,"description":"Open unassigned alerts for this detection"}},"required":["detectionAgentId","detectionAgentName","isAutonomousHunt","override","effective","alertCount30d","openUnassignedCount"]}},"agentSources":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid","description":"Alert-producing agent identifier"},"agentName":{"type":"string","minLength":1,"description":"Alert-producing agent name"},"targetAgentId":{"type":["string","null"],"format":"uuid","description":"Default agent that will handle new alerts, or null when unassigned"},"alertCount30d":{"type":"integer","minimum":0,"description":"Agent-created alert count over the last 30 days"},"openUnassignedCount":{"type":"integer","minimum":0,"description":"Open unassigned alerts created by this agent"}},"required":["agentId","agentName","targetAgentId","alertCount30d","openUnassignedCount"]}},"triggers":{"type":"array","items":{"type":"object","properties":{"triggerId":{"type":"string","format":"uuid","description":"Trigger identifier"},"triggerName":{"type":"string","minLength":1,"description":"Trigger name"},"triggerSource":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Trigger source"},"sourceLogoToolType":{"type":["string","null"],"minLength":1,"description":"Tool logo key used to brand this alert source, or null when unset"},"responseAgentId":{"type":"string","format":"uuid","description":"Owning response agent id"},"responseAgentName":{"type":"string","minLength":1,"description":"Owning response agent name"},"createAlert":{"type":"boolean","description":"Deprecated compatibility field; true when eventMode is alert_source"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Direct agent trigger or explicit alert source"},"alertCount30d":{"type":"integer","minimum":0,"description":"Trigger-created alert count over the last 30 days"},"runCount30d":{"type":"integer","minimum":0,"description":"Runs started by this trigger or alert source over the last 30 days"},"enabled":{"type":"boolean","description":"False when the trigger is turned off; omitted on older payloads, treated as enabled"}},"required":["triggerId","triggerName","triggerSource","sourceLogoToolType","responseAgentId","responseAgentName","createAlert","alertCount30d"]}},"responseAgentSummaries":{"type":"array","items":{"type":"object","properties":{"responseAgentId":{"type":"string","format":"uuid","description":"Response agent identifier"},"responseAgentName":{"type":"string","minLength":1,"description":"Response agent name"},"activeAssignedAlertCount":{"type":"integer","minimum":0,"description":"Active alerts currently assigned to this response agent"},"alertCount30d":{"type":"integer","minimum":0,"description":"Alerts assigned to this response agent over the last 30 days"},"lastTriageRunAt":{"type":["string","null"],"description":"ISO timestamp of the most recent triage run for this agent"},"sourceNames":{"type":"array","items":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"description":"Alert source names recently handled by this response agent"},"isLegacyDetection":{"type":"boolean","description":"Migrated legacy customer detection (stored agentType detection); its triggers always run direct during the compatibility window"},"subAgents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid","description":"Sub-agent identifier"},"agentName":{"type":"string","minLength":1,"description":"Sub-agent display name"},"runCount30d":{"type":"integer","minimum":0,"description":"Runs delegated to this sub-agent by the parent agent over the last 30 days"}},"required":["agentId","agentName","runCount30d"]},"description":"Agents this agent can invoke as sub-agents via its agent tools"}},"required":["responseAgentId","responseAgentName","activeAssignedAlertCount","alertCount30d","lastTriageRunAt","sourceNames"]}}},"required":["defaultSettings","responseAgents","detections","triggers","responseAgentSummaries"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alert-routing/defaults":{"put":{"summary":"Update default alert routing","description":"Update the organization-wide default agent for alerts without an explicit route.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/alert-routing/defaults\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"defaultResponseAgentId\":\"string\"}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"defaultResponseAgentId":{"type":["string","null"],"format":"uuid","description":"Default agent for alerts without an explicit route"}},"required":["defaultResponseAgentId"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"defaultSettings":{"type":"object","properties":{"organizationId":{"type":"string","format":"uuid","description":"Organization that owns these alert routing defaults"},"defaultResponseAgentId":{"type":["string","null"],"format":"uuid","description":"Default agent for alerts without an explicit route"},"defaultResponseAgentName":{"type":["string","null"],"description":"Display name for the configured default alert agent"},"createdAt":{"type":"string","description":"ISO timestamp when the organization row was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the routing default was last updated"}},"required":["organizationId","defaultResponseAgentId","defaultResponseAgentName","createdAt","updatedAt"]},"responseAgents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Response agent identifier"},"name":{"type":"string","minLength":1,"description":"Response agent display name"}},"required":["id","name"]}}},"required":["defaultSettings","responseAgents"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/detections/{id}/alert-routing":{"get":{"summary":"Get detection alert routing","description":"Return a detection agent alert routing override and effective routing setting.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/detections/:id/alert-routing\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","description":"Detection agent id","schema":{"type":"string","format":"uuid","description":"Detection agent id"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"override":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Detection alert routing override id"},"detectionAgentId":{"type":"string","format":"uuid","description":"Detection agent this override applies to"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this override"},"responseAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent override, or null to leave alerts unassigned"},"responseAgentName":{"type":["string","null"],"description":"Display name for the override response agent"},"createdAt":{"type":"string","description":"ISO timestamp when the override was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the override was last updated"}},"required":["id","detectionAgentId","organizationId","responseAgentId","responseAgentName","createdAt","updatedAt"]},"effective":{"type":"object","properties":{"detectionAgentId":{"type":"string","format":"uuid","description":"Detection agent this effective routing applies to"},"responseAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent that will handle new alerts, if configured"},"responseAgentName":{"type":["string","null"],"description":"Display name for the effective response agent"},"source":{"type":"string","enum":["detection_override","organization_default"],"description":"Whether the effective setting comes from an override or organization default"},"inheritedDefaultResponseAgentId":{"type":["string","null"],"format":"uuid","description":"Organization default response agent id used for inheritance"},"inheritedDefaultResponseAgentName":{"type":["string","null"],"description":"Organization default response agent name used for inheritance"}},"required":["detectionAgentId","responseAgentId","responseAgentName","source","inheritedDefaultResponseAgentId","inheritedDefaultResponseAgentName"]},"defaultSettings":{"type":"object","properties":{"organizationId":{"type":"string","format":"uuid","description":"Organization that owns these alert routing defaults"},"defaultResponseAgentId":{"type":["string","null"],"format":"uuid","description":"Default agent for alerts without an explicit route"},"defaultResponseAgentName":{"type":["string","null"],"description":"Display name for the configured default alert agent"},"createdAt":{"type":"string","description":"ISO timestamp when the organization row was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the routing default was last updated"}},"required":["organizationId","defaultResponseAgentId","defaultResponseAgentName","createdAt","updatedAt"]},"responseAgents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Response agent identifier"},"name":{"type":"string","minLength":1,"description":"Response agent display name"}},"required":["id","name"]}}},"required":["override","effective","defaultSettings","responseAgents"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update detection alert routing","description":"Set or clear a per-detection alert routing override.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/detections/:id/alert-routing\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"inheritOrgDefault\":true,\"responseAgentId\":\"string\"}'"}],"parameters":[{"in":"path","name":"id","description":"Detection agent id","schema":{"type":"string","format":"uuid","description":"Detection agent id"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"inheritOrgDefault":{"type":"boolean","description":"When true, remove the detection override"},"responseAgentId":{"type":["string","null"],"format":"uuid","description":"Override response agent, or null to leave alerts unassigned"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"override":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Detection alert routing override id"},"detectionAgentId":{"type":"string","format":"uuid","description":"Detection agent this override applies to"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this override"},"responseAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent override, or null to leave alerts unassigned"},"responseAgentName":{"type":["string","null"],"description":"Display name for the override response agent"},"createdAt":{"type":"string","description":"ISO timestamp when the override was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the override was last updated"}},"required":["id","detectionAgentId","organizationId","responseAgentId","responseAgentName","createdAt","updatedAt"]},"effective":{"type":"object","properties":{"detectionAgentId":{"type":"string","format":"uuid","description":"Detection agent this effective routing applies to"},"responseAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent that will handle new alerts, if configured"},"responseAgentName":{"type":["string","null"],"description":"Display name for the effective response agent"},"source":{"type":"string","enum":["detection_override","organization_default"],"description":"Whether the effective setting comes from an override or organization default"},"inheritedDefaultResponseAgentId":{"type":["string","null"],"format":"uuid","description":"Organization default response agent id used for inheritance"},"inheritedDefaultResponseAgentName":{"type":["string","null"],"description":"Organization default response agent name used for inheritance"}},"required":["detectionAgentId","responseAgentId","responseAgentName","source","inheritedDefaultResponseAgentId","inheritedDefaultResponseAgentName"]},"defaultSettings":{"type":"object","properties":{"organizationId":{"type":"string","format":"uuid","description":"Organization that owns these alert routing defaults"},"defaultResponseAgentId":{"type":["string","null"],"format":"uuid","description":"Default agent for alerts without an explicit route"},"defaultResponseAgentName":{"type":["string","null"],"description":"Display name for the configured default alert agent"},"createdAt":{"type":"string","description":"ISO timestamp when the organization row was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the routing default was last updated"}},"required":["organizationId","defaultResponseAgentId","defaultResponseAgentName","createdAt","updatedAt"]},"responseAgents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Response agent identifier"},"name":{"type":"string","minLength":1,"description":"Response agent display name"}},"required":["id","name"]}}},"required":["override","effective","defaultSettings","responseAgents"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts/for-run/{runId}":{"get":{"summary":"Get alert for run","description":"Resolve the alert a run triaged or created, used to link an agent run back to its alert.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/alerts/for-run/:runId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"runId","description":"Run UUID (chats.id) to resolve a linked alert for","schema":{"type":"string","format":"uuid","description":"Run UUID (chats.id) to resolve a linked alert for"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"alert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"],"description":"Alert this run triaged or created, or null when the run is not linked to an alert"}},"required":["alert"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts/{alertId}":{"get":{"summary":"Get alert","description":"Retrieve one alert and its initial timeline page.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/alerts/:alertId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"alertId","description":"Alert UUID or human-readable display ID","schema":{"type":"string","description":"Alert UUID or human-readable display ID"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"alert":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."},"timeline":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"created"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"originDetectionHitId":{"type":["string","null"],"format":"uuid"},"originTriggerId":{"type":["string","null"],"format":"uuid"},"sourcePayloadId":{"type":"string","format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert creation timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"comment"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"slackSource":{}},"additionalProperties":true,"description":"Metadata for alert comment timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"status_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."},"duplicateOfAlertId":{"type":"string","format":"uuid"},"duplicateOfDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateOfTitle":{"type":"string","minLength":1}},"additionalProperties":true,"description":"Metadata for alert status-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"title_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeTitle":{"type":["string","null"]},"afterTitle":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert title-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"description_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeDescription":{"type":["string","null"]},"afterDescription":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert description-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"severity_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"afterSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"reason":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert severity-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"assignment_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"assignedAgentId":{"type":["string","null"],"format":"uuid"},"runId":{"type":["string","null"],"format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert assignment-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"triage_run"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."}},"additionalProperties":true,"description":"Metadata for alert triage-run timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"duplicate_linked"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"duplicateAlertId":{"type":"string","format":"uuid"},"duplicateAlertDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateAlertTitle":{"type":"string","minLength":1}},"required":["duplicateAlertId","duplicateAlertDisplayId","duplicateAlertTitle"],"description":"Metadata for an alert marked as a duplicate of this alert."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"external_event"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","additionalProperties":true,"description":"Metadata for externally mirrored alert timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"detection_tuned"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"detectionId":{"type":"string","format":"uuid"},"detectionName":{"type":["string","null"]},"versionId":{"type":"string","format":"uuid"},"version":{"type":["integer","null"],"exclusiveMinimum":0},"proposalId":{"type":"string","format":"uuid"},"chatId":{"type":["string","null"],"format":"uuid"},"role":{"type":"string","enum":["fp_eliminated","benign_eliminated","tp_retained"],"description":"How this alert's label figured in the approved tuning proposal: its false-positive or benign label was eliminated by the change, or it was a true positive the backtest verified the new version still catches."},"windowStart":{"type":"string","format":"date-time"},"windowEnd":{"type":"string","format":"date-time"}},"required":["detectionId","detectionName","versionId","version","proposalId","chatId","role","windowStart","windowEnd"],"additionalProperties":true,"description":"Metadata recorded on cited alerts when a tuning proposal built on this alert's feedback is approved and published."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]}]},"description":"Initial page of timeline entries"}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource","timeline"]}},"required":["alert"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update alert details","description":"Update an alert title and/or description and append matching timeline entries.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PATCH \"https://app.cotool.ai/api/alerts/:alertId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d 'null'"}],"parameters":[{"in":"path","name":"alertId","description":"Alert UUID or human-readable display ID","schema":{"type":"string","description":"Alert UUID or human-readable display ID"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":500,"description":"Updated human-readable alert title"},"description":{"type":["string","null"],"maxLength":50000,"description":"Updated markdown description, or null to clear it"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"alert":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt"]},"entries":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"created"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"originDetectionHitId":{"type":["string","null"],"format":"uuid"},"originTriggerId":{"type":["string","null"],"format":"uuid"},"sourcePayloadId":{"type":"string","format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert creation timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"comment"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"slackSource":{}},"additionalProperties":true,"description":"Metadata for alert comment timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"status_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."},"duplicateOfAlertId":{"type":"string","format":"uuid"},"duplicateOfDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateOfTitle":{"type":"string","minLength":1}},"additionalProperties":true,"description":"Metadata for alert status-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"title_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeTitle":{"type":["string","null"]},"afterTitle":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert title-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"description_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeDescription":{"type":["string","null"]},"afterDescription":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert description-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"severity_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"afterSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"reason":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert severity-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"assignment_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"assignedAgentId":{"type":["string","null"],"format":"uuid"},"runId":{"type":["string","null"],"format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert assignment-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"triage_run"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."}},"additionalProperties":true,"description":"Metadata for alert triage-run timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"duplicate_linked"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"duplicateAlertId":{"type":"string","format":"uuid"},"duplicateAlertDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateAlertTitle":{"type":"string","minLength":1}},"required":["duplicateAlertId","duplicateAlertDisplayId","duplicateAlertTitle"],"description":"Metadata for an alert marked as a duplicate of this alert."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"external_event"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","additionalProperties":true,"description":"Metadata for externally mirrored alert timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"detection_tuned"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"detectionId":{"type":"string","format":"uuid"},"detectionName":{"type":["string","null"]},"versionId":{"type":"string","format":"uuid"},"version":{"type":["integer","null"],"exclusiveMinimum":0},"proposalId":{"type":"string","format":"uuid"},"chatId":{"type":["string","null"],"format":"uuid"},"role":{"type":"string","enum":["fp_eliminated","benign_eliminated","tp_retained"],"description":"How this alert's label figured in the approved tuning proposal: its false-positive or benign label was eliminated by the change, or it was a true positive the backtest verified the new version still catches."},"windowStart":{"type":"string","format":"date-time"},"windowEnd":{"type":"string","format":"date-time"}},"required":["detectionId","detectionName","versionId","version","proposalId","chatId","role","windowStart","windowEnd"],"additionalProperties":true,"description":"Metadata recorded on cited alerts when a tuning proposal built on this alert's feedback is approved and published."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]}]},"description":"Timeline entries recorded for changed title/description fields"}},"required":["alert","entries"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts/{alertId}/timeline":{"get":{"summary":"Get alert timeline","description":"Retrieve paginated timeline entries for an alert.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/alerts/:alertId/timeline\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"alertId","description":"Alert UUID or human-readable display ID","schema":{"type":"string","description":"Alert UUID or human-readable display ID"},"required":true},{"in":"query","name":"limit","description":"Maximum number of timeline entries to return","schema":{"type":"integer","minimum":1,"maximum":200,"default":100,"description":"Maximum number of timeline entries to return"}},{"in":"query","name":"offset","description":"Number of timeline entries to skip","schema":{"type":"integer","minimum":0,"default":0,"description":"Number of timeline entries to skip"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"created"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"originDetectionHitId":{"type":["string","null"],"format":"uuid"},"originTriggerId":{"type":["string","null"],"format":"uuid"},"sourcePayloadId":{"type":"string","format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert creation timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"comment"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"slackSource":{}},"additionalProperties":true,"description":"Metadata for alert comment timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"status_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."},"duplicateOfAlertId":{"type":"string","format":"uuid"},"duplicateOfDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateOfTitle":{"type":"string","minLength":1}},"additionalProperties":true,"description":"Metadata for alert status-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"title_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeTitle":{"type":["string","null"]},"afterTitle":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert title-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"description_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeDescription":{"type":["string","null"]},"afterDescription":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert description-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"severity_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"afterSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"reason":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert severity-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"assignment_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"assignedAgentId":{"type":["string","null"],"format":"uuid"},"runId":{"type":["string","null"],"format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert assignment-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"triage_run"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."}},"additionalProperties":true,"description":"Metadata for alert triage-run timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"duplicate_linked"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"duplicateAlertId":{"type":"string","format":"uuid"},"duplicateAlertDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateAlertTitle":{"type":"string","minLength":1}},"required":["duplicateAlertId","duplicateAlertDisplayId","duplicateAlertTitle"],"description":"Metadata for an alert marked as a duplicate of this alert."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"external_event"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","additionalProperties":true,"description":"Metadata for externally mirrored alert timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"detection_tuned"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"detectionId":{"type":"string","format":"uuid"},"detectionName":{"type":["string","null"]},"versionId":{"type":"string","format":"uuid"},"version":{"type":["integer","null"],"exclusiveMinimum":0},"proposalId":{"type":"string","format":"uuid"},"chatId":{"type":["string","null"],"format":"uuid"},"role":{"type":"string","enum":["fp_eliminated","benign_eliminated","tp_retained"],"description":"How this alert's label figured in the approved tuning proposal: its false-positive or benign label was eliminated by the change, or it was a true positive the backtest verified the new version still catches."},"windowStart":{"type":"string","format":"date-time"},"windowEnd":{"type":"string","format":"date-time"}},"required":["detectionId","detectionName","versionId","version","proposalId","chatId","role","windowStart","windowEnd"],"additionalProperties":true,"description":"Metadata recorded on cited alerts when a tuning proposal built on this alert's feedback is approved and published."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]}]}},"totalCount":{"type":"integer","minimum":0,"description":"Total number of timeline entries for this alert"}},"required":["entries","totalCount"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts/{alertId}/source-payloads/{sourcePayloadId}":{"get":{"summary":"Get alert source payload","description":"Retrieve the stored raw source payload for an alert.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/alerts/:alertId/source-payloads/:sourcePayloadId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"alertId","description":"Alert UUID or human-readable display ID","schema":{"type":"string","description":"Alert UUID or human-readable display ID"},"required":true},{"in":"path","name":"sourcePayloadId","description":"Alert source payload UUID","schema":{"type":"string","format":"uuid","description":"Alert source payload UUID"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sourcePayload":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Source payload identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the payload"},"alertId":{"type":"string","format":"uuid","description":"Alert this payload belongs to"},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider when the source is an external trigger"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that produced the payload, when applicable"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that produced the payload, when applicable"},"contentType":{"type":"string","const":"application/json"},"storageKind":{"type":"string","enum":["inline_json","kv"]},"sha256":{"type":"string","description":"SHA-256 digest of the JSON payload"},"sizeBytes":{"type":"integer","minimum":0},"payload":{"$ref":"#/components/schemas/JsonValue","description":"Raw source payload for alert triage"},"detectionDefinition":{"type":["string","null"],"description":"Originating agent definition: run version when available, otherwise current definition. Context separate from the stored source payload."},"createdAt":{"type":"string","description":"ISO timestamp when the payload was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the payload was last updated"}},"required":["id","organizationId","alertId","source","externalProvider","originTriggerId","originRunId","contentType","storageKind","sha256","sizeBytes","payload","createdAt","updatedAt"]}},"required":["sourcePayload"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts/{alertId}/comments":{"post":{"summary":"Add alert comment","description":"Append a timeline comment to an alert.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/alerts/:alertId/comments\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"bodyMarkdown\":\"string\"}'"}],"parameters":[{"in":"path","name":"alertId","description":"Alert UUID or human-readable display ID","schema":{"type":"string","description":"Alert UUID or human-readable display ID"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"bodyMarkdown":{"type":"string","minLength":1,"maxLength":20000,"description":"Markdown comment body"}},"required":["bodyMarkdown"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"entry":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"created"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"originDetectionHitId":{"type":["string","null"],"format":"uuid"},"originTriggerId":{"type":["string","null"],"format":"uuid"},"sourcePayloadId":{"type":"string","format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert creation timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"comment"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"slackSource":{}},"additionalProperties":true,"description":"Metadata for alert comment timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"status_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."},"duplicateOfAlertId":{"type":"string","format":"uuid"},"duplicateOfDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateOfTitle":{"type":"string","minLength":1}},"additionalProperties":true,"description":"Metadata for alert status-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"title_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeTitle":{"type":["string","null"]},"afterTitle":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert title-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"description_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeDescription":{"type":["string","null"]},"afterDescription":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert description-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"severity_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"afterSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"reason":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert severity-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"assignment_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"assignedAgentId":{"type":["string","null"],"format":"uuid"},"runId":{"type":["string","null"],"format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert assignment-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"triage_run"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."}},"additionalProperties":true,"description":"Metadata for alert triage-run timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"duplicate_linked"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"duplicateAlertId":{"type":"string","format":"uuid"},"duplicateAlertDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateAlertTitle":{"type":"string","minLength":1}},"required":["duplicateAlertId","duplicateAlertDisplayId","duplicateAlertTitle"],"description":"Metadata for an alert marked as a duplicate of this alert."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"external_event"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","additionalProperties":true,"description":"Metadata for externally mirrored alert timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"detection_tuned"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"detectionId":{"type":"string","format":"uuid"},"detectionName":{"type":["string","null"]},"versionId":{"type":"string","format":"uuid"},"version":{"type":["integer","null"],"exclusiveMinimum":0},"proposalId":{"type":"string","format":"uuid"},"chatId":{"type":["string","null"],"format":"uuid"},"role":{"type":"string","enum":["fp_eliminated","benign_eliminated","tp_retained"],"description":"How this alert's label figured in the approved tuning proposal: its false-positive or benign label was eliminated by the change, or it was a true positive the backtest verified the new version still catches."},"windowStart":{"type":"string","format":"date-time"},"windowEnd":{"type":"string","format":"date-time"}},"required":["detectionId","detectionName","versionId","version","proposalId","chatId","role","windowStart","windowEnd"],"additionalProperties":true,"description":"Metadata recorded on cited alerts when a tuning proposal built on this alert's feedback is approved and published."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]}]}},"required":["entry"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts/{alertId}/status":{"post":{"summary":"Update alert status","description":"Update an alert lifecycle status and append a status-change timeline entry when the status changes. Optional feedback is appended as a comment in the same transaction. Duplicate status requires a canonical alert target.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/alerts/:alertId/status\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d 'null'"}],"parameters":[{"in":"path","name":"alertId","description":"Alert UUID or human-readable display ID","schema":{"type":"string","description":"Alert UUID or human-readable display ID"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate"],"description":"New alert lifecycle status. `expired` is set only by the alert inactivity job and is rejected here."},"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional reason for the status change"},"commentBodyMarkdown":{"type":"string","minLength":1,"maxLength":20000,"description":"Optional human feedback appended to the alert timeline as a comment"},"duplicateOfAlertId":{"type":"string","description":"Required canonical alert identifier when marking an alert as duplicate"}},"required":["status"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"alert":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt"]},"entry":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"created"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"originDetectionHitId":{"type":["string","null"],"format":"uuid"},"originTriggerId":{"type":["string","null"],"format":"uuid"},"sourcePayloadId":{"type":"string","format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert creation timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"comment"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"slackSource":{}},"additionalProperties":true,"description":"Metadata for alert comment timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"status_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."},"duplicateOfAlertId":{"type":"string","format":"uuid"},"duplicateOfDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateOfTitle":{"type":"string","minLength":1}},"additionalProperties":true,"description":"Metadata for alert status-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"title_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeTitle":{"type":["string","null"]},"afterTitle":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert title-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"description_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeDescription":{"type":["string","null"]},"afterDescription":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert description-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"severity_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"afterSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"reason":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert severity-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"assignment_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"assignedAgentId":{"type":["string","null"],"format":"uuid"},"runId":{"type":["string","null"],"format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert assignment-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"triage_run"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."}},"additionalProperties":true,"description":"Metadata for alert triage-run timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"duplicate_linked"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"duplicateAlertId":{"type":"string","format":"uuid"},"duplicateAlertDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateAlertTitle":{"type":"string","minLength":1}},"required":["duplicateAlertId","duplicateAlertDisplayId","duplicateAlertTitle"],"description":"Metadata for an alert marked as a duplicate of this alert."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"external_event"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","additionalProperties":true,"description":"Metadata for externally mirrored alert timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"detection_tuned"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"detectionId":{"type":"string","format":"uuid"},"detectionName":{"type":["string","null"]},"versionId":{"type":"string","format":"uuid"},"version":{"type":["integer","null"],"exclusiveMinimum":0},"proposalId":{"type":"string","format":"uuid"},"chatId":{"type":["string","null"],"format":"uuid"},"role":{"type":"string","enum":["fp_eliminated","benign_eliminated","tp_retained"],"description":"How this alert's label figured in the approved tuning proposal: its false-positive or benign label was eliminated by the change, or it was a true positive the backtest verified the new version still catches."},"windowStart":{"type":"string","format":"date-time"},"windowEnd":{"type":"string","format":"date-time"}},"required":["detectionId","detectionName","versionId","version","proposalId","chatId","role","windowStart","windowEnd"],"additionalProperties":true,"description":"Metadata recorded on cited alerts when a tuning proposal built on this alert's feedback is approved and published."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"null"}],"description":"Timeline entry created for a status transition, or null when the requested status was already set"},"commentEntry":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"created"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"originDetectionHitId":{"type":["string","null"],"format":"uuid"},"originTriggerId":{"type":["string","null"],"format":"uuid"},"sourcePayloadId":{"type":"string","format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert creation timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"comment"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"slackSource":{}},"additionalProperties":true,"description":"Metadata for alert comment timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"status_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."},"duplicateOfAlertId":{"type":"string","format":"uuid"},"duplicateOfDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateOfTitle":{"type":"string","minLength":1}},"additionalProperties":true,"description":"Metadata for alert status-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"title_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeTitle":{"type":["string","null"]},"afterTitle":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert title-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"description_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeDescription":{"type":["string","null"]},"afterDescription":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert description-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"severity_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"afterSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"reason":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert severity-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"assignment_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"assignedAgentId":{"type":["string","null"],"format":"uuid"},"runId":{"type":["string","null"],"format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert assignment-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"triage_run"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."}},"additionalProperties":true,"description":"Metadata for alert triage-run timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"duplicate_linked"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"duplicateAlertId":{"type":"string","format":"uuid"},"duplicateAlertDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateAlertTitle":{"type":"string","minLength":1}},"required":["duplicateAlertId","duplicateAlertDisplayId","duplicateAlertTitle"],"description":"Metadata for an alert marked as a duplicate of this alert."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"external_event"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","additionalProperties":true,"description":"Metadata for externally mirrored alert timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"detection_tuned"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"detectionId":{"type":"string","format":"uuid"},"detectionName":{"type":["string","null"]},"versionId":{"type":"string","format":"uuid"},"version":{"type":["integer","null"],"exclusiveMinimum":0},"proposalId":{"type":"string","format":"uuid"},"chatId":{"type":["string","null"],"format":"uuid"},"role":{"type":"string","enum":["fp_eliminated","benign_eliminated","tp_retained"],"description":"How this alert's label figured in the approved tuning proposal: its false-positive or benign label was eliminated by the change, or it was a true positive the backtest verified the new version still catches."},"windowStart":{"type":"string","format":"date-time"},"windowEnd":{"type":"string","format":"date-time"}},"required":["detectionId","detectionName","versionId","version","proposalId","chatId","role","windowStart","windowEnd"],"additionalProperties":true,"description":"Metadata recorded on cited alerts when a tuning proposal built on this alert's feedback is approved and published."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]}],"description":"Optional feedback comment appended with the status transition"},"commentAdded":{"type":"boolean","description":"Whether optional feedback was appended as a comment with the status transition"},"statusChanged":{"type":"boolean","description":"Whether the alert status changed and a timeline entry was recorded"}},"required":["alert","entry","statusChanged"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"409":{"description":"The alert cannot be reopened because a newer open hit exists for the same entity.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"CODE_DETECTION_HIT_OPEN_CONFLICT"}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alert-escalation-notification-defaults":{"get":{"summary":"Get escalated alert notification defaults","description":"Get the organization-wide destinations notified when an alert moves into escalated status.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/alert-escalation-notification-defaults\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the organization alert escalation notification settings"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns these settings"},"enabled":{"type":"boolean","description":"Whether notifications are sent when an alert moves into escalated status"},"destinationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Destinations notified when an alert is escalated"},"minSeverity":{"type":"string","enum":["low","medium","high","critical"],"description":"Minimum alert severity eligible for escalated alert notifications; low means all severities notify"},"createdAt":{"type":"string","description":"When the settings were created"},"updatedAt":{"type":"string","description":"When the settings were last updated"}},"required":["id","organizationId","enabled","destinationIds","minSeverity","createdAt","updatedAt"],"description":"Organization-wide notification settings for escalated alerts"},"destinations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"webhook"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication: \"bearer\" for Authorization: Bearer <token>, \"header\" for custom header"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\" (e.g., \"X-API-Key\")"}},"required":["url","authType"]},"token":{"type":"string","description":"The authentication token (only returned to authorized users)"},"hasToken":{"type":"boolean","description":"Whether a token is configured"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"teams"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["url"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"slack"},"config":{"type":"object","properties":{"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"},"configurationRevision":{"type":"integer","minimum":0,"description":"Revision of user-managed Slack delivery configuration"},"blockedChannels":{"type":"object","additionalProperties":{"type":"object","properties":{"reason":{"type":"string","const":"archived","description":"Why delivery to this Slack channel is blocked"},"blockedAt":{"type":"string","description":"When Slack reported that the channel was archived"}},"required":["reason","blockedAt"]},"description":"Channels that delivery will skip until a user updates the destination"}},"required":["channelIds"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"pagerduty"},"config":{"type":"object","properties":{"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts"},"source":{"type":"string","description":"Optional source identifier (defaults to detection name)"}},"required":["severity"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"linear"},"config":{"type":"object","properties":{"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names for display purposes"},"workflowStateId":{"type":"string","minLength":1,"description":"Linear workflow state ID for created issues"},"workflowStateName":{"type":"string","description":"Cached Linear workflow state name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"tines"},"config":{"type":"object","properties":{"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]}]},"description":"Available output destinations for the organization"}},"required":["settings","destinations"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update escalated alert notification defaults","description":"Update the organization-wide destinations notified when an alert moves into escalated status.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/alert-escalation-notification-defaults\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"enabled\":true,\"destinationIds\":[\"string\"],\"minSeverity\":\"low\"}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether notifications are sent when an alert moves into escalated status"},"destinationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Destinations notified when an alert is escalated"},"minSeverity":{"type":"string","enum":["low","medium","high","critical"],"description":"Minimum alert severity eligible for escalated alert notifications; preserves the stored value when omitted"}},"required":["enabled","destinationIds"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the organization alert escalation notification settings"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns these settings"},"enabled":{"type":"boolean","description":"Whether notifications are sent when an alert moves into escalated status"},"destinationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Destinations notified when an alert is escalated"},"minSeverity":{"type":"string","enum":["low","medium","high","critical"],"description":"Minimum alert severity eligible for escalated alert notifications; low means all severities notify"},"createdAt":{"type":"string","description":"When the settings were created"},"updatedAt":{"type":"string","description":"When the settings were last updated"}},"required":["id","organizationId","enabled","destinationIds","minSeverity","createdAt","updatedAt"],"description":"Organization-wide notification settings for escalated alerts"},"destinations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"webhook"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication: \"bearer\" for Authorization: Bearer <token>, \"header\" for custom header"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\" (e.g., \"X-API-Key\")"}},"required":["url","authType"]},"token":{"type":"string","description":"The authentication token (only returned to authorized users)"},"hasToken":{"type":"boolean","description":"Whether a token is configured"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"teams"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["url"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"slack"},"config":{"type":"object","properties":{"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"},"configurationRevision":{"type":"integer","minimum":0,"description":"Revision of user-managed Slack delivery configuration"},"blockedChannels":{"type":"object","additionalProperties":{"type":"object","properties":{"reason":{"type":"string","const":"archived","description":"Why delivery to this Slack channel is blocked"},"blockedAt":{"type":"string","description":"When Slack reported that the channel was archived"}},"required":["reason","blockedAt"]},"description":"Channels that delivery will skip until a user updates the destination"}},"required":["channelIds"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"pagerduty"},"config":{"type":"object","properties":{"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts"},"source":{"type":"string","description":"Optional source identifier (defaults to detection name)"}},"required":["severity"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"linear"},"config":{"type":"object","properties":{"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names for display purposes"},"workflowStateId":{"type":"string","minLength":1,"description":"Linear workflow state ID for created issues"},"workflowStateName":{"type":"string","description":"Cached Linear workflow state name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"tines"},"config":{"type":"object","properties":{"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]}]},"description":"Available output destinations for the organization"}},"required":["settings","destinations"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts/{alertId}/severity":{"post":{"summary":"Update alert severity","description":"Update an alert severity and append a severity-change timeline entry.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/alerts/:alertId/severity\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"severity\":\"low\",\"reason\":\"string\"}'"}],"parameters":[{"in":"path","name":"alertId","description":"Alert UUID or human-readable display ID","schema":{"type":"string","description":"Alert UUID or human-readable display ID"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"severity":{"type":"string","enum":["low","medium","high","critical"],"description":"New alert severity"},"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional reason for the severity change"}},"required":["severity"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"alert":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt"]},"entry":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"created"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"originDetectionHitId":{"type":["string","null"],"format":"uuid"},"originTriggerId":{"type":["string","null"],"format":"uuid"},"sourcePayloadId":{"type":"string","format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert creation timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"comment"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"slackSource":{}},"additionalProperties":true,"description":"Metadata for alert comment timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"status_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."},"duplicateOfAlertId":{"type":"string","format":"uuid"},"duplicateOfDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateOfTitle":{"type":"string","minLength":1}},"additionalProperties":true,"description":"Metadata for alert status-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"title_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeTitle":{"type":["string","null"]},"afterTitle":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert title-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"description_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeDescription":{"type":["string","null"]},"afterDescription":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert description-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"severity_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"afterSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"reason":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert severity-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"assignment_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"assignedAgentId":{"type":["string","null"],"format":"uuid"},"runId":{"type":["string","null"],"format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert assignment-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"triage_run"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."}},"additionalProperties":true,"description":"Metadata for alert triage-run timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"duplicate_linked"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"duplicateAlertId":{"type":"string","format":"uuid"},"duplicateAlertDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateAlertTitle":{"type":"string","minLength":1}},"required":["duplicateAlertId","duplicateAlertDisplayId","duplicateAlertTitle"],"description":"Metadata for an alert marked as a duplicate of this alert."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"external_event"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","additionalProperties":true,"description":"Metadata for externally mirrored alert timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"detection_tuned"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"detectionId":{"type":"string","format":"uuid"},"detectionName":{"type":["string","null"]},"versionId":{"type":"string","format":"uuid"},"version":{"type":["integer","null"],"exclusiveMinimum":0},"proposalId":{"type":"string","format":"uuid"},"chatId":{"type":["string","null"],"format":"uuid"},"role":{"type":"string","enum":["fp_eliminated","benign_eliminated","tp_retained"],"description":"How this alert's label figured in the approved tuning proposal: its false-positive or benign label was eliminated by the change, or it was a true positive the backtest verified the new version still catches."},"windowStart":{"type":"string","format":"date-time"},"windowEnd":{"type":"string","format":"date-time"}},"required":["detectionId","detectionName","versionId","version","proposalId","chatId","role","windowStart","windowEnd"],"additionalProperties":true,"description":"Metadata recorded on cited alerts when a tuning proposal built on this alert's feedback is approved and published."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]}]}},"required":["alert","entry"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/alerts/{alertId}/triage-runs":{"post":{"summary":"Start alert triage run","description":"Assign an alert to a response agent and enqueue an alert-triage run.","tags":["Alerts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/alerts/:alertId/triage-runs\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"agentId\":\"string\",\"reason\":\"string\"}'"}],"parameters":[{"in":"path","name":"alertId","description":"Alert UUID or human-readable display ID","schema":{"type":"string","description":"Alert UUID or human-readable display ID"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid","description":"Response agent to assign and start immediately"},"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional reason for starting triage with this agent"}},"required":["agentId"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"alert":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt"]},"runId":{"type":"string","format":"uuid","description":"Created response-agent triage run, stored as chats.id"},"entry":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"created"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"originDetectionHitId":{"type":["string","null"],"format":"uuid"},"originTriggerId":{"type":["string","null"],"format":"uuid"},"sourcePayloadId":{"type":"string","format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert creation timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"comment"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"slackSource":{}},"additionalProperties":true,"description":"Metadata for alert comment timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"status_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."},"duplicateOfAlertId":{"type":"string","format":"uuid"},"duplicateOfDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateOfTitle":{"type":"string","minLength":1}},"additionalProperties":true,"description":"Metadata for alert status-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"title_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeTitle":{"type":["string","null"]},"afterTitle":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert title-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"description_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeDescription":{"type":["string","null"]},"afterDescription":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert description-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"severity_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"beforeSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"afterSeverity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"reason":{"type":["string","null"]}},"additionalProperties":true,"description":"Metadata for alert severity-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"assignment_change"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"assignedAgentId":{"type":["string","null"],"format":"uuid"},"runId":{"type":["string","null"],"format":"uuid"}},"additionalProperties":true,"description":"Metadata for alert assignment-change timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"triage_run"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"reason":{"type":["string","null"]},"agentId":{"type":"string","format":"uuid"},"runId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["completed","failed","canceled"],"description":"How an alert triage run ended. `completed` means the run finished without setting a final disposition; `failed` means the agent run errored; `canceled` means the run was interrupted."}},"additionalProperties":true,"description":"Metadata for alert triage-run timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"duplicate_linked"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"duplicateAlertId":{"type":"string","format":"uuid"},"duplicateAlertDisplayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"duplicateAlertTitle":{"type":"string","minLength":1}},"required":["duplicateAlertId","duplicateAlertDisplayId","duplicateAlertTitle"],"description":"Metadata for an alert marked as a duplicate of this alert."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"external_event"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","additionalProperties":true,"description":"Metadata for externally mirrored alert timeline entries."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Timeline entry identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the timeline entry"},"alertId":{"type":"string","format":"uuid","description":"Alert this entry belongs to"},"createdAt":{"type":"string","description":"ISO timestamp when the entry was created"},"actorType":{"type":"string","enum":["human","agent","system"],"description":"Actor class responsible for a timeline entry."},"actorUserId":{"type":["string","null"],"format":"uuid","description":"Human actor user id, when actorType is human"},"actorAgentId":{"type":["string","null"],"format":"uuid","description":"Agent actor id, when actorType is agent"},"actorRunId":{"type":["string","null"],"format":"uuid","description":"Run responsible for this entry, stored as chats.id"},"actorUserName":{"type":["string","null"],"description":"Resolved display name for a human actor, hydrated for rendering"},"actorUserImageUrl":{"type":["string","null"],"description":"Resolved avatar image URL for a human actor, when one is available"},"actorAgentName":{"type":["string","null"],"description":"Resolved display name for an agent actor or referenced assigned agent"},"kind":{"type":"string","const":"detection_tuned"},"bodyMarkdown":{"type":["string","null"],"description":"Timeline body, when this entry has prose content"},"beforeStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status before a status transition"},"afterStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Status after a status transition"},"metadata":{"type":"object","properties":{"detectionId":{"type":"string","format":"uuid"},"detectionName":{"type":["string","null"]},"versionId":{"type":"string","format":"uuid"},"version":{"type":["integer","null"],"exclusiveMinimum":0},"proposalId":{"type":"string","format":"uuid"},"chatId":{"type":["string","null"],"format":"uuid"},"role":{"type":"string","enum":["fp_eliminated","benign_eliminated","tp_retained"],"description":"How this alert's label figured in the approved tuning proposal: its false-positive or benign label was eliminated by the change, or it was a true positive the backtest verified the new version still catches."},"windowStart":{"type":"string","format":"date-time"},"windowEnd":{"type":"string","format":"date-time"}},"required":["detectionId","detectionName","versionId","version","proposalId","chatId","role","windowStart","windowEnd"],"additionalProperties":true,"description":"Metadata recorded on cited alerts when a tuning proposal built on this alert's feedback is approved and published."}},"required":["id","organizationId","alertId","createdAt","actorType","actorUserId","actorAgentId","actorRunId","actorUserName","actorUserImageUrl","kind","bodyMarkdown","beforeStatus","afterStatus","metadata"]}]}},"required":["alert","runId","entry"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent-sync/validate":{"post":{"summary":"Validate Response-Agent-as-Code YAML","description":"Validate Response-Agents-as-Code YAML without syncing it. Runs the same parse, schema, and cross-file checks as the GitOps sync engine, so a CI check stays in step with real sync behavior. Typically used to validate agent files in a pull request before they merge.\n\n**Request.** Post each file as a `{ path, content }` pair. The validator has no access to your repo, so you send the raw file text. Post one file to check it on its own, or a whole directory to also catch cross-file issues like duplicate `sync_key` values and dependency cycles. Include any prompt `.md` files referenced by `systemPrompt.file` so those references resolve.\n\n**Response.** An overall `valid` flag, plus per file an `errors` list (these would block a sync) and a `warnings` list (non-blocking). Warnings are checks that need live workspace state the request cannot see, such as an unprovided `systemPrompt.file` or a reference to an agent that is not in the request.\n\n**Authentication.** Send a bearer token. **GitHub OIDC is the recommended method:** in GitHub Actions, use the [`cotool/validate-agents` Action](/agents/response-agents-as-code#validate-in-ci), which mints a short-lived, repo-scoped token (no stored secret; the repository must be connected for GitOps sync) that grants validate-only access. A Cotool API key with the `tool.manage` permission also works for non-GitHub or self-hosted CI, but it is long-lived and inherits the full permissions of the user who created it, so prefer OIDC and treat any API key as a sensitive, least-privilege secret.","tags":["Agents as Code"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agent-sync/validate\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"files\":[{\"path\":\"agents/triage-suspicious-login.yaml\",\"content\":\"apiVersion: cotool.ai/v1\\nkind: ResponseAgent\\nmetadata:\\n  sync_key: triage-suspicious-login\\n  name: Triage Suspicious Login\\nspec:\\n  modelAlias: anthropic:chat:sonnet-4.6\\n  toolNames: [slack]\\n\"}],\"skillsPath\":\"string\"}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"description":"Repo-relative file path, e.g. \"agents/triage.yaml\". A .yaml/.yml file is validated as an agent; any other file (such as a .md) is treated as a referenced systemPrompt.file. Also used to identify files in cross-file checks.","example":"agents/triage-suspicious-login.yaml"},"content":{"type":"string","description":"The full raw text of the file. The validator has no repo access, so you send the file contents yourself.","example":"apiVersion: cotool.ai/v1\nkind: ResponseAgent\nmetadata:\n  sync_key: triage-suspicious-login\n  name: Triage Suspicious Login\nspec:\n  modelAlias: anthropic:chat:sonnet-4.6\n  toolNames: [slack]\n"}},"required":["path","content"]},"minItems":1,"description":"The files to validate. Post one to check it on its own, or a whole directory to also catch cross-file issues. Include any SKILL.md files (under skillsPath) that agents reference, and any prompt .md files referenced by systemPrompt.file; a skill reference whose SKILL.md is not in the request is a warning, not a failure."},"skillsPath":{"type":"string","minLength":1,"description":"Directory holding standalone SKILL.md skill definitions (default \"cotool/skills\"). Must match your sync config's skills path so skill files in the request are discovered."}},"required":["files"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","description":"True when every returned result validated with no errors."},"fileCount":{"type":"number","description":"Number of validation result rows returned."},"agentCount":{"type":"number","description":"Number of schema-valid, graph-clean agents found."},"results":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"valid":{"type":"boolean","description":"True when this file has no error-severity diagnostics."},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["yaml_error","schema_error","fetch_error"],"description":"Kind of issue."},"message":{"type":"string","description":"Human-readable explanation (includes the field path for schema errors)."}},"required":["code","message"]},"description":"Issues that would make this file fail to sync."},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["yaml_error","schema_error","fetch_error"],"description":"Kind of issue."},"message":{"type":"string","description":"Human-readable explanation (includes the field path for schema errors)."}},"required":["code","message"]},"description":"Non-blocking issues that depend on live workspace state the validator cannot see, such as an unresolved systemPrompt.file or a reference to an agent not in the request."}},"required":["path","valid","errors","warnings"]}}},"required":["valid","fileCount","agentCount","results"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/artifacts/{artifactId}":{"get":{"summary":"Get artifact","description":"Fetch the content and metadata of a stored artifact by its ID for a given chat.","tags":["Artifacts"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/artifacts/:artifactId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"artifactId","description":"Unique identifier of the artifact to retrieve","schema":{"type":"string","description":"Unique identifier of the artifact to retrieve"},"required":true},{"in":"query","name":"chatId","description":"Unique identifier of the chat that owns this artifact","schema":{"type":"string","format":"uuid","description":"Unique identifier of the chat that owns this artifact"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"The full content of the artifact"},"metadata":{"type":"object","additionalProperties":{},"description":"Optional metadata associated with the artifact"}},"required":["content"],"description":"Artifact content and metadata"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/audit-logs/count":{"get":{"summary":"Count audit logs","description":"Return the total number of audit-log records that match a set of optional filters.","tags":["Audit Logs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/audit-logs/count\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"userId","description":"Count audit logs for specific user ID","schema":{"type":"string","minLength":1,"description":"Count audit logs for specific user ID"}},{"in":"query","name":"event","description":"Count audit logs for specific event type (e.g., user.login, agent.runStarted)","schema":{"type":"string","description":"Count audit logs for specific event type (e.g., user.login, agent.runStarted)"}},{"in":"query","name":"actor","description":"Count audit logs for specific actor type (user, agent, chat)","schema":{"type":"string","description":"Count audit logs for specific actor type (user, agent, chat)"}},{"in":"query","name":"chatId","description":"Count audit logs for specific chat ID","schema":{"type":"string","minLength":1,"description":"Count audit logs for specific chat ID"}},{"in":"query","name":"agentId","description":"Count audit logs for specific agent ID","schema":{"type":"string","minLength":1,"description":"Count audit logs for specific agent ID"}},{"in":"query","name":"triggerId","description":"Count audit logs for specific trigger ID","schema":{"type":"string","minLength":1,"description":"Count audit logs for specific trigger ID"}},{"in":"query","name":"toolGroup","description":"Count audit logs for a specific tool family (matches data.toolId equal to the value or starting with \"<value>_\")","schema":{"type":"string","description":"Count audit logs for a specific tool family (matches data.toolId equal to the value or starting with \"<value>_\")"}},{"in":"query","name":"startDate","description":"Count audit logs from this date onwards (ISO string format)","schema":{"type":"string","description":"Count audit logs from this date onwards (ISO string format)"}},{"in":"query","name":"endDate","description":"Count audit logs up to this date (ISO string format)","schema":{"type":"string","description":"Count audit logs up to this date (ISO string format)"}},{"in":"query","name":"search","description":"Text search across event type, actor, user email, agent name, and data fields","schema":{"type":"string","description":"Text search across event type, actor, user email, agent name, and data fields"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","description":"Total number of audit log entries matching the specified filters"}},"required":["count"],"description":"Count of audit log entries"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/audit-logs/filter-options":{"get":{"summary":"Get audit-log filter options","description":"Retrieve the distinct event types, actors, user IDs, and tool family slugs that appear in this org's audit logs. Used by the audit-logs UI to populate filter dropdowns with only values that actually yield results.","tags":["Audit Logs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/audit-logs/filter-options\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"eventTypes":{"type":"array","items":{"type":"string"},"description":"Distinct event types present in audit logs for the organization"},"actors":{"type":"array","items":{"type":"string"},"description":"Distinct actor values (user, agent, chat) present in audit logs for the organization"},"userIds":{"type":"array","items":{"type":"string"},"description":"Distinct user IDs present in audit logs for the organization"},"toolGroups":{"type":"array","items":{"type":"string"},"description":"Distinct tool family slugs (data.toolId first segment, split on \"_\") present in audit logs for the organization"}},"required":["eventTypes","actors","userIds","toolGroups"],"description":"Pre-computed value lists used to populate the audit-log filter dropdowns. Each list is already scoped to values that appear in the org's audit logs after the native-tool exclusion."}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/audit-logs/event-catalog":{"get":{"summary":"Get audit-log event catalog","description":"Retrieve the canonical catalog of every audit-log event type the platform can emit, including events that have never been recorded for this organization. Use /api/audit-logs/filter-options to get only the values present in this org's audit logs.","tags":["Audit Logs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/audit-logs/event-catalog\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","description":"Audit-log event type identifier (e.g., user.login, agent.runStarted)"},"actor":{"type":"string","description":"Actor type that emits this event (user, agent, or chat)"},"description":{"type":"string","description":"Human-readable description of when this event is recorded"}},"required":["event","actor","description"]},"description":"Every audit-log event type the platform can emit"}},"required":["events"],"description":"Canonical catalog of all possible audit-log event types, independent of whether they have ever been recorded for the organization."}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/audit-logs":{"get":{"summary":"List audit logs","description":"Return a paginated list of audit logs filtered by query parameters such as userId, event type, date range, etc. Supports two pagination modes: limit/offset (default), and keyset cursors for continuous export — when a page is full, the X-Next-Cursor response header carries an opaque cursor for the next page; pass it back as the cursor query parameter. An absent header (or a short page) means there is no more data. Cursor pages stay equally fast at any depth, unlike large offsets.","tags":["Audit Logs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/audit-logs\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"userId","description":"Filter audit logs by specific user ID","schema":{"type":"string","minLength":1,"description":"Filter audit logs by specific user ID"}},{"in":"query","name":"event","description":"Filter audit logs by event type (e.g., user.login, agent.runStarted)","schema":{"type":"string","description":"Filter audit logs by event type (e.g., user.login, agent.runStarted)"}},{"in":"query","name":"actor","description":"Filter audit logs by actor type (user, agent, chat)","schema":{"type":"string","description":"Filter audit logs by actor type (user, agent, chat)"}},{"in":"query","name":"chatId","description":"Filter audit logs by specific chat ID","schema":{"type":"string","minLength":1,"description":"Filter audit logs by specific chat ID"}},{"in":"query","name":"agentId","description":"Filter audit logs by specific agent ID","schema":{"type":"string","minLength":1,"description":"Filter audit logs by specific agent ID"}},{"in":"query","name":"triggerId","description":"Filter audit logs by specific trigger ID","schema":{"type":"string","minLength":1,"description":"Filter audit logs by specific trigger ID"}},{"in":"query","name":"toolGroup","description":"Filter audit logs by tool family (e.g. \"slack\" matches data.toolId = \"slack\" and any \"slack_*\" tool)","schema":{"type":"string","description":"Filter audit logs by tool family (e.g. \"slack\" matches data.toolId = \"slack\" and any \"slack_*\" tool)"}},{"in":"query","name":"startDate","description":"Filter audit logs from this date onwards (ISO string format)","schema":{"type":"string","description":"Filter audit logs from this date onwards (ISO string format)"}},{"in":"query","name":"endDate","description":"Filter audit logs up to this date (ISO string format)","schema":{"type":"string","description":"Filter audit logs up to this date (ISO string format)"}},{"in":"query","name":"search","description":"Text search across event type, actor, user email, agent name, and data fields","schema":{"type":"string","description":"Text search across event type, actor, user email, agent name, and data fields"}},{"in":"query","name":"limit","description":"Maximum number of audit logs to return (1-100, default: 50)","schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of audit logs to return (1-100, default: 50)"}},{"in":"query","name":"offset","description":"Number of audit logs to skip for pagination (default: 0, max: 10000). For continuous export or deep pagination, use cursor pagination instead.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0,"description":"Number of audit logs to skip for pagination (default: 0, max: 10000). For continuous export or deep pagination, use cursor pagination instead."}},{"in":"query","name":"cursor","description":"Opaque keyset-pagination cursor from the X-Next-Cursor response header of the previous page. Preferred over offset for continuous export: pages stay equally fast at any depth and an empty page means there is no more data. Mutually exclusive with offset; only supported with sortBy=timestamp.","schema":{"type":"string","minLength":1,"description":"Opaque keyset-pagination cursor from the X-Next-Cursor response header of the previous page. Preferred over offset for continuous export: pages stay equally fast at any depth and an empty page means there is no more data. Mutually exclusive with offset; only supported with sortBy=timestamp."}},{"in":"query","name":"sortBy","description":"Field to sort audit logs by (default: timestamp)","schema":{"type":"string","enum":["timestamp","createdAt"],"default":"timestamp","description":"Field to sort audit logs by (default: timestamp)"}},{"in":"query","name":"sortDirection","description":"Sort direction for audit logs (default: desc)","schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction for audit logs (default: desc)"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Unique identifier for this audit log entry"},"timestamp":{"type":"string","description":"When the audited event occurred"},"organizationId":{"type":"string","format":"uuid","description":"Organization where the event took place"},"event":{"type":"string","description":"Type of event that was audited (e.g., user.login, agent.runStarted)"},"actor":{"type":"string","description":"Who or what performed the action (user, agent, chat)"},"userId":{"type":["string","null"],"format":"uuid","description":"ID of the user involved in the event (null if not applicable)"},"ipAddress":{"type":["string","null"],"description":"IP address where the event originated (null if not applicable)"},"chatId":{"type":["string","null"],"format":"uuid","description":"ID of the chat involved in the event (null if not applicable)"},"agentId":{"type":["string","null"],"format":"uuid","description":"ID of the agent involved in the event (null if not applicable)"},"runId":{"type":["string","null"],"format":"uuid","description":"ID of the agent run involved in the event (null if not applicable)"},"triggerId":{"type":["string","null"],"format":"uuid","description":"ID of the trigger involved in the event (null if not applicable)"},"data":{"type":["object","null"],"additionalProperties":{},"description":"Additional event-specific data (null if no extra data)"},"createdAt":{"type":"string","description":"When this audit log entry was created in the database"},"user":{"type":"object","properties":{"email":{"type":"string","description":"Email address of the user associated with this audit log"}},"required":["email"],"description":"Hydrated user information (included when available)"},"agent":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the agent associated with this audit log"}},"required":["name"],"description":"Hydrated agent information (included when available)"},"trigger":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the trigger associated with this audit log"},"type":{"type":"string","description":"Type of trigger (e.g., jira, slack, linear, cron)"}},"required":["name","type"],"description":"Hydrated trigger information (included when available)"}},"required":["id","timestamp","organizationId","event","actor","userId","ipAddress","chatId","agentId","runId","triggerId","data","createdAt"],"description":"Complete audit log entry with optional hydrated relationship data"},"description":"Array of audit log entries matching the specified filters"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/audit-logs/{id}":{"get":{"summary":"Get audit log entry","description":"Retrieve a single audit-log record by its unique identifier.","tags":["Audit Logs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/audit-logs/:id\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","description":"Unique identifier of the audit log entry to retrieve","schema":{"type":"string","minLength":1,"description":"Unique identifier of the audit log entry to retrieve"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Unique identifier for this audit log entry"},"timestamp":{"type":"string","description":"When the audited event occurred"},"organizationId":{"type":"string","format":"uuid","description":"Organization where the event took place"},"event":{"type":"string","description":"Type of event that was audited (e.g., user.login, agent.runStarted)"},"actor":{"type":"string","description":"Who or what performed the action (user, agent, chat)"},"userId":{"type":["string","null"],"format":"uuid","description":"ID of the user involved in the event (null if not applicable)"},"ipAddress":{"type":["string","null"],"description":"IP address where the event originated (null if not applicable)"},"chatId":{"type":["string","null"],"format":"uuid","description":"ID of the chat involved in the event (null if not applicable)"},"agentId":{"type":["string","null"],"format":"uuid","description":"ID of the agent involved in the event (null if not applicable)"},"runId":{"type":["string","null"],"format":"uuid","description":"ID of the agent run involved in the event (null if not applicable)"},"triggerId":{"type":["string","null"],"format":"uuid","description":"ID of the trigger involved in the event (null if not applicable)"},"data":{"type":["object","null"],"additionalProperties":{},"description":"Additional event-specific data (null if no extra data)"},"createdAt":{"type":"string","description":"When this audit log entry was created in the database"},"user":{"type":"object","properties":{"email":{"type":"string","description":"Email address of the user associated with this audit log"}},"required":["email"],"description":"Hydrated user information (included when available)"},"agent":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the agent associated with this audit log"}},"required":["name"],"description":"Hydrated agent information (included when available)"},"trigger":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the trigger associated with this audit log"},"type":{"type":"string","description":"Type of trigger (e.g., jira, slack, linear, cron)"}},"required":["name","type"],"description":"Hydrated trigger information (included when available)"}},"required":["id","timestamp","organizationId","event","actor","userId","ipAddress","chatId","agentId","runId","triggerId","data","createdAt"],"description":"Single audit log entry response"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/me":{"get":{"summary":"Get current user","description":"Return the authenticated user's profile information.","tags":["Users"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/auth/me\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the user"},"email":{"type":"string","format":"email","description":"Email address of the user (normalized and validated)"},"isVerified":{"type":"boolean","description":"Whether the user has verified their email address"},"roleId":{"type":"string","description":"The role the user belongs to"},"createdAt":{"type":"string","description":"When the user account was created"},"updatedAt":{"type":"string","description":"When the user account was last updated"},"lastLoginAt":{"type":["string","null"],"description":"When the user last logged in (null if never logged in)"},"googleId":{"type":["string","null"],"description":"Google OAuth ID if user signed up with Google (null if not linked)"},"microsoftId":{"type":["string","null"],"description":"Microsoft OAuth ID if user signed up with Microsoft (null if not linked)"},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Additional user metadata as key-value pairs (null if no metadata)"},"organizationId":{"type":"string","format":"uuid","description":"ID of the organization this user belongs to"},"organizationName":{"type":"string","description":"URL-safe name of the organization this user belongs to"},"authType":{"type":"string","enum":["oauth","local","mixed"],"description":"Type of authentication used for the user"},"isAdmin":{"type":"boolean","description":"Whether the user is an admin"}},"required":["id","email","isVerified","roleId","createdAt","updatedAt","lastLoginAt","googleId","microsoftId","metadata","organizationId","authType","isAdmin"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/perms":{"get":{"summary":"Get current user permissions and all available permissions","description":"Returns the current user's effective permissions and the list of all permission definitions available in the system.","tags":["Users"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/perms\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"userPerms":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"agent.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"detection.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"tool.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"cli.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"chat.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.triage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.perms.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.update"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.invite"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.delete"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.apiKey.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auditLog.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.customModel.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auth.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.tags.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.suggestions.manage"}},"required":["resource","action"]}]}},"allPerms":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"agent.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"detection.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"tool.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"cli.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"chat.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.triage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.perms.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.update"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.invite"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.delete"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.apiKey.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auditLog.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.customModel.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auth.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.tags.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.suggestions.manage"}},"required":["resource","action"]}]}}},"required":["userPerms","allPerms"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/chats":{"get":{"summary":"List chats","description":"Retrieve a paginated list of chats for the current user or agent.","tags":["Chat"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/chats\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100},"required":true},{"in":"query","name":"offset","schema":{"type":"integer","minimum":0},"required":true},{"in":"query","name":"search","schema":{"type":"string","minLength":1,"maxLength":200}},{"in":"query","name":"titleOnly","schema":{"type":"string"}},{"in":"query","name":"pinnedOnly","schema":{"type":"string"}},{"in":"query","name":"excludePinned","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"chats":{"type":"array","items":{"$ref":"#/components/schemas/Chat"}},"totalCount":{"type":"integer"},"feedbackByEvent":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string","enum":["up","down"]},"createdAt":{"type":"string"}},"required":["label","createdAt"]}}},"required":["chats","totalCount"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/chats/{chatId}/feedback":{"post":{"summary":"Submit thumbs feedback for a chat","description":"Records a thumbs up/down for a chat if the user has access to it.","tags":["Chat"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/chats/:chatId/feedback\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"agentId\":\"string\",\"label\":\"up\",\"chatEventId\":\"string\",\"comment\":\"string\"}'"}],"parameters":[{"in":"path","name":"chatId","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","format":"uuid"},"label":{"type":"string","enum":["up","down"]},"chatEventId":{"type":"string","format":"uuid"},"comment":{"type":"string","maxLength":1000}},"required":["label"]}}}},"responses":{"200":{"description":"Successful response - no content"},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/chats/{chatId}":{"delete":{"summary":"Delete chat","description":"Delete a chat conversation by its unique identifier.","tags":["Chat"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X DELETE \"https://app.cotool.ai/api/chats/:chatId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"chatId","schema":{"type":"string","format":"uuid"},"required":true}],"responses":{"200":{"description":"Successful response - no content"},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/hunt/overview":{"get":{"summary":"Hunt overview","description":"Landing dashboard: environment metric tiles, the intel -> exposure funnel, detection coverage distribution, and recent Threats / rule proposals / blocking gaps.","tags":["Hunt"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/hunt/overview\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"primaryCta":{"type":"object","properties":{"label":{"type":"string"},"href":{"type":"string"},"activeHuntAlertCount":{"type":"number"}},"required":["label","href","activeHuntAlertCount"]},"summary":{"type":"object","properties":{"windowDays":{"anyOf":[{"type":"number","const":7},{"type":"number","const":30}]},"intelIngestedCount":{"type":"number"},"threatsTrackedCount":{"type":"number"},"threatsAssessedCount":{"type":"number"},"exposureAlertsGeneratedCount":{"type":"number"},"foundIocAlertsGeneratedCount":{"type":"number"},"activeHuntAlertCount":{"type":"number"},"ruleProposalsCreatedCount":{"type":"number"},"detectionPrsOpenedCount":{"type":"number"},"ruleProposalsShippedCount":{"type":"number"},"blockingGapsOpenCount":{"type":"number"},"blockingGapsResolvedCount":{"type":"number"},"coverageStateDistribution":{"type":"object","properties":{"none":{"type":"number"},"partial":{"type":"number"},"covered":{"type":"number"},"unknown":{"type":"number"}},"required":["none","partial","covered","unknown"]}},"required":["windowDays","intelIngestedCount","threatsTrackedCount","threatsAssessedCount","exposureAlertsGeneratedCount","foundIocAlertsGeneratedCount","activeHuntAlertCount","ruleProposalsCreatedCount","detectionPrsOpenedCount","ruleProposalsShippedCount","blockingGapsOpenCount","blockingGapsResolvedCount","coverageStateDistribution"]},"funnel":{"type":"object","properties":{"intelIngestedCount":{"type":"number"},"huntableIntelCount":{"type":"number"},"threatsTrackedCount":{"type":"number"},"threatsAssessedCount":{"type":"number"},"exposureAlertsGeneratedCount":{"type":"number"}},"required":["intelIngestedCount","huntableIntelCount","threatsTrackedCount","threatsAssessedCount","exposureAlertsGeneratedCount"]},"recentThreats":{"type":"array","items":{"type":"object","properties":{"threatId":{"type":"string"},"title":{"type":"string"},"canonicalType":{"type":"string","enum":["vulnerability","campaign"]},"canonicalKeyType":{"type":"string","enum":["cve","advisory","vendor_advisory","campaign_name","malware_family"]},"canonicalKey":{"type":"string"},"firstSeenAt":{"type":"string"},"latestIntelAt":{"type":"string"},"huntResultBadge":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","covered_by_existing_detection","no_exposure_found","inconclusive",null]},"exposureScore":{"type":["number","null"]},"exposureBand":{"type":["string","null"],"enum":["critical","high","medium","low","minimal",null]},"exposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"coverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"affectedAssetCount":{"type":"number"},"activeHuntAlertId":{"type":["string","null"]},"activeHuntAlertStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"latestAlertId":{"type":["string","null"]},"latestAlertStatus":{"type":["string","null"],"enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired",null],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"deliverableCount":{"type":"number"}},"required":["threatId","title","canonicalType","canonicalKeyType","canonicalKey","firstSeenAt","latestIntelAt","huntResultBadge","exposureScore","exposureBand","exposureState","coverageState","affectedAssetCount","activeHuntAlertId","activeHuntAlertStatus","latestAlertId","latestAlertStatus","deliverableCount"]},"maxItems":10},"recentRuleProposals":{"type":"array","items":{"type":"object","properties":{"deliverableId":{"type":"string"},"proposalId":{"type":["string","null"]},"pullRequestUrl":{"type":["string","null"]},"threatId":{"type":"string"},"threatTitle":{"type":"string"},"intent":{"type":"string"},"pinning":{"type":"string","enum":["ioc_pinned","behavioral","mixed"]},"targetProduct":{"type":["string","null"]},"targetLogSource":{"type":["string","null"]},"lifecycleStatus":{"type":"string","enum":["authoring","drafted","in_review","shipped","dismissed","failed"]},"createdAt":{"type":"string"}},"required":["deliverableId","proposalId","pullRequestUrl","threatId","threatTitle","intent","pinning","targetProduct","targetLogSource","lifecycleStatus","createdAt"]},"maxItems":10},"recentBlockingGaps":{"type":"array","items":{"type":"object","properties":{"gapId":{"type":"string"},"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"blocking":{"type":"boolean"},"gapStatus":{"type":"string","enum":["open","resolved","dismissed"]},"establishedAt":{"type":"string"},"linkedThreats":{"type":"array","items":{"type":"object","properties":{"threatId":{"type":"string"},"threatTitle":{"type":"string"},"canonicalKey":{"type":"string"},"blocking":{"type":"boolean"}},"required":["threatId","threatTitle","canonicalKey","blocking"]}},"createdAt":{"type":"string"}},"required":["gapId","product","logSource","scopeType","scopeId","blocking","gapStatus","establishedAt","linkedThreats","createdAt"]},"maxItems":10},"capabilities":{"type":"object","properties":{"canReadEvidence":{"type":"boolean"},"canReassess":{"type":"boolean"},"canTriage":{"type":"boolean"}},"required":["canReadEvidence","canReassess","canTriage"]}},"required":["primaryCta","summary","funnel","recentThreats","recentRuleProposals","recentBlockingGaps"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/hunt/actors":{"get":{"summary":"List threat actors","description":"Actor grouping nodes for the current organization, used as Threat catalog filter options.","tags":["Hunt"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/hunt/actors\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"actors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}}},"required":["id","organizationId","name","aliases"]}}},"required":["actors"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/threats":{"get":{"summary":"List Threats","description":"The durable Threat catalog. Filterable by derived status, canonical type, coverage state, exposure state, hunt result badge, actor, linked Alert state, and free-text query.","tags":["Hunt"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/threats\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","enum":["active","assessing","assessment_failed","blocked","monitoring","covered","clear","not_relevant","resolved","dismissed"]}},{"in":"query","name":"canonicalType","schema":{"type":"string","enum":["vulnerability","campaign"]}},{"in":"query","name":"coverageState","schema":{"type":"string","enum":["none","partial","covered","unknown"]}},{"in":"query","name":"exposureState","schema":{"type":"string","enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive"]}},{"in":"query","name":"huntResultBadge","schema":{"type":"string","enum":["compromise_signal_found","exposure_found","covered_by_existing_detection","no_exposure_found","inconclusive"]}},{"in":"query","name":"actorId","schema":{"type":"string"}},{"in":"query","name":"linkedAlertState","schema":{"type":"string","enum":["active","terminal","none"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"threats":{"type":"array","items":{"type":"object","properties":{"threat":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"canonicalType":{"type":"string","enum":["vulnerability","campaign"]},"canonicalKeyType":{"type":"string","enum":["cve","advisory","vendor_advisory","campaign_name","malware_family"]},"canonicalKey":{"type":"string"},"title":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"actorId":{"type":["string","null"]},"intelItemIds":{"type":"array","items":{"type":"string"}},"relevancyScore":{"type":["number","null"]},"exposureScore":{"type":["number","null"]},"exposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"coverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"detectionEngineeringNote":{"type":["string","null"]},"latestRunId":{"type":["string","null"]},"assessmentRunningExecutionId":{"type":["string","null"]},"assessmentFailedAt":{"type":["string","null"]},"latestAlertId":{"type":["string","null"]},"activeHuntAlertId":{"type":["string","null"]},"dismissedAt":{"type":["string","null"]},"dismissedByUserId":{"type":["string","null"]},"dismissedReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","canonicalType","canonicalKeyType","canonicalKey","title","aliases","actorId","intelItemIds","relevancyScore","exposureScore","exposureState","coverageState","detectionEngineeringNote","latestRunId","assessmentRunningExecutionId","assessmentFailedAt","latestAlertId","activeHuntAlertId","dismissedAt","dismissedByUserId","dismissedReason","createdAt","updatedAt"]},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"threatId":{"type":"string"},"kind":{"type":"string","enum":["create","update"]},"trigger":{"type":"string","enum":["new_threat","intel_attached","manual","backfill","reclassification"]},"runAt":{"type":"string"},"relevancyExecutionId":{"type":"string"},"relevancyScore":{"type":"number"},"relevancyHeadline":{"type":["string","null"]},"relevancyExplanation":{"type":"array","items":{"type":"string"}},"exposureExecutionId":{"type":["string","null"]},"exposureScore":{"type":["number","null"]},"exposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"exposureStory":{"type":["object","null"],"properties":{"exposureState":{"type":"string","enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive"]},"headline":{"type":"string"},"summary":{"type":"array","items":{"type":"string"}},"exposureChecks":{"type":"array","items":{"type":"object","properties":{"purpose":{"type":"string","enum":["exposure","ioc","telemetry","detection_coverage"]},"indicatorId":{"type":"string"},"authoritative":{"type":"boolean"},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"]},"indicatorRole":{"type":"string","enum":["compromise","relevance"]},"checked":{"type":"string"},"source":{"type":"string"},"scope":{"type":"string"},"timeWindow":{"type":["object","null"],"properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"outcome":{"type":"string","enum":["found","not_found","inconclusive"]},"evidence":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["purpose","checked","source","scope","timeWindow","outcome","evidence","limitations"]}},"assets":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"kind":{"type":"string","enum":["repository","host","service","cloud_resource","identity","package","domain","saas_account","container_image","other"],"default":"other"},"platform":{"type":["string","null"],"default":null},"source":{"type":"string"},"internetFacing":{"type":["boolean","null"]},"evidence":{"type":"string"}},"required":["identifier","kind","platform","source","internetFacing","evidence"]}},"iocFindings":{"type":"array","items":{"type":"object","properties":{"indicatorId":{"type":"string"},"authoritative":{"type":"boolean"},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"]},"role":{"type":"string","enum":["compromise","relevance"],"default":"compromise"},"platform":{"type":["string","null"],"default":null},"iocValue":{"type":"string"},"evidence":{"type":"string"},"affectedSystems":{"type":"array","items":{"type":"string"}}},"required":["iocType","role","platform","iocValue","evidence","affectedSystems"]}},"discoveredIndicators":{"type":"array","items":{"type":"object","properties":{"indicatorId":{"type":"string","minLength":1,"description":"Unique run-local id such as discovered-1."},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"],"description":"Canonical indicator type."},"role":{"type":"string","enum":["compromise","relevance"],"description":"Required role with no default."},"platform":{"type":"string","description":"Optional registry/ecosystem for package or image indicators."},"iocValue":{"type":"string","minLength":1,"maxLength":2048,"description":"One exact atomic indicator value, never a prose/composite description."},"roleRationale":{"type":"string","minLength":1,"description":"Why a match alone does or does not justify a compromise claim."},"evidence":{"type":"string","minLength":1,"description":"Cited evidence establishing this as a threat indicator."}},"required":["indicatorId","iocType","role","iocValue","roleRationale","evidence"]}},"observations":{"type":"array","items":{"type":"object","properties":{"observationId":{"type":"string","minLength":1,"description":"Unique run-local observation id."},"kind":{"type":"string","enum":["software_presence","vulnerable_asset","configuration_exposure","exploit_attempt","suspicious_behavior","confirmed_malicious_behavior"],"description":"Semantic kind of customer-environment observation."},"summary":{"type":"string","minLength":1,"description":"Concise statement of what was observed."},"evidence":{"type":"string","minLength":1,"description":"Cited customer-environment evidence."},"affectedSystems":{"type":"array","items":{"type":"string","description":"Affected system identifier."},"description":"Affected customer assets; empty when none."},"timeWindow":{"type":"object","properties":{"start":{"type":"string","description":"Observation window start."},"end":{"type":"string","description":"Observation window end."}},"required":["start","end"]}},"required":["observationId","kind","summary","evidence","affectedSystems"]}},"researchContext":{"type":"array","items":{"type":"object","properties":{"contextId":{"type":"string","minLength":1,"description":"Unique run-local context id."},"summary":{"type":"string","minLength":1,"description":"Concise public/intel fact."},"evidence":{"type":"string","minLength":1,"description":"Cited evidence for the context fact."}},"required":["contextId","summary","evidence"]}},"conclusion":{"type":"object","properties":{"headline":{"type":"string","minLength":1,"description":"One self-contained sentence stating the environment verdict and the evidence-based interpretation that determines the score. Never merely report that an indicator matched: if activity is attributable to security inspection, scanning, testing, or another evidenced benign cause, state both the match and that interpretation so the reader immediately understands why it is not concerning. When the exposure score is in the residual band (35-59), state the residual condition — what concretely remains exposed, unpatched, or unverified — never a bare \"no exposure found\"."},"summary":{"type":"array","items":{"type":"string","description":"One concise cited verdict bullet."},"minItems":3,"maxItems":8,"description":"3-8 concise bullets explaining the environment verdict."},"supportingFindingIds":{"type":"array","items":{"type":"string","description":"An input-catalog indicatorId that appears in indicatorChecks, or an observationId defined in observations, copied verbatim."},"description":"Authoritative input-check or environment-observation ids supporting the verdict, copied verbatim from ids defined in this output; never discovered-indicator ids, context ids, or invented shorthand ids."},"contextIds":{"type":"array","items":{"type":"string","description":"Research context id used for interpretation."},"description":"Referenced public/intel context ids."}},"required":["headline","summary","supportingFindingIds","contextIds"]},"detectionCoverage":{"type":"object","properties":{"state":{"type":"string","enum":["none","partial","covered","unknown"]},"searches":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"criteria":{"type":"string"},"resultCount":{"type":"number"},"evidence":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["source","criteria","resultCount","evidence","limitations"]}},"matches":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["rule_proposal","deployed_rule","detection_agent"]},"platform":{"type":["string","null"]},"url":{"type":["string","null"]}},"required":["id","name","kind"]},"coverage":{"type":"string","enum":["partial","covered","unknown"]},"rationale":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["ref","coverage","rationale","limitations"]}}},"required":["state","searches","matches"]},"gaps":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"scopeKey":{"type":"string"},"blocking":{"type":"boolean"},"description":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["product","logSource","scopeType","scopeId","scopeKey","blocking","description","limitations"]}},"nextSteps":{"type":"array","items":{"type":"string"}},"timeline":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"description":{"type":"string"}},"required":["timestamp","description"]}},"executionId":{"type":"string"},"runAt":{"type":"string"}},"required":["exposureState","summary","exposureChecks","assets","iocFindings","detectionCoverage","gaps","nextSteps","executionId","runAt"]},"coverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"hasFoundIoc":{"type":"boolean"},"hasBlockingGap":{"type":"boolean"},"diff":{"type":["object","null"],"properties":{"prevRunId":{"type":"string"},"beforeExposureScore":{"type":["number","null"]},"afterExposureScore":{"type":["number","null"]},"beforeExposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"afterExposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"beforeCoverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"afterCoverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["prevRunId","beforeExposureScore","afterExposureScore","beforeExposureState","afterExposureState","beforeCoverageState","afterCoverageState","reasons"]}},"required":["id","threatId","kind","trigger","runAt","relevancyExecutionId","relevancyScore","relevancyExplanation","exposureExecutionId","exposureScore","exposureState","exposureStory","coverageState","hasFoundIoc","hasBlockingGap","diff"]}},"deliverables":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"threatId":{"type":"string"},"executionId":{"type":"string"},"createdAt":{"type":"string"},"supersededById":{"type":["string","null"]},"kind":{"type":"string","const":"rule_proposal"},"proposalId":{"type":["string","null"]},"pullRequestUrl":{"type":["string","null"]},"intent":{"type":"string"},"pinning":{"type":"string","enum":["ioc_pinned","behavioral","mixed"]},"pinnedIocs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}},"required":["type","value"]}},"targetProduct":{"type":["string","null"]},"targetLogSource":{"type":["string","null"]},"lifecycleStatus":{"type":"string","enum":["authoring","drafted","in_review","shipped","dismissed","failed"]}},"required":["id","organizationId","threatId","executionId","createdAt","supersededById","kind","proposalId","pullRequestUrl","intent","pinning","pinnedIocs","targetProduct","targetLogSource","lifecycleStatus"]},{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"threatId":{"type":"string"},"executionId":{"type":"string"},"createdAt":{"type":"string"},"supersededById":{"type":["string","null"]},"kind":{"type":"string","const":"gap"},"gapId":{"type":["string","null"]},"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"scopeKey":{"type":"string"},"blocking":{"type":"boolean"},"description":{"type":"string"},"gapStatus":{"type":"string","enum":["open","resolved","dismissed"]},"establishedAt":{"type":"string"},"statusAt":{"type":["string","null"]},"statusActor":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"agent"},"runId":{"type":"string"}},"required":["type","runId"]},{"type":"object","properties":{"type":{"type":"string","const":"human"},"userId":{"type":"string"}},"required":["type","userId"]},{"type":"null"}]},"statusReason":{"type":["string","null"]},"otherLinkedThreats":{"type":"array","items":{"type":"object","properties":{"threatId":{"type":"string"},"threatTitle":{"type":"string"},"canonicalKey":{"type":"string"},"blocking":{"type":"boolean"}},"required":["threatId","threatTitle","canonicalKey","blocking"]}}},"required":["id","organizationId","threatId","executionId","createdAt","supersededById","kind","product","logSource","scopeType","scopeId","scopeKey","blocking","description","gapStatus","establishedAt","statusAt","statusActor","statusReason"]}]}},"intelItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"publisher":{"type":"string"},"sourceName":{"type":["string","null"]},"url":{"type":["string","null"]},"publishedAt":{"type":"string"},"tldr":{"type":["string","null"]},"attackPath":{"type":"array","items":{"type":"string"}},"summary":{"type":["string","null"]},"attackTechniques":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]}},"malware":{"type":"array","items":{"type":"string"}},"actors":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"type":"string"}},"affectedProducts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"versions":{"type":"array","items":{"type":"string"}}},"required":["name","versions"]}},"eventFirstSeen":{"type":["string","null"]},"eventLastSeen":{"type":["string","null"]}},"required":["id","title","publisher","url","publishedAt","tldr","attackPath"]}},"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]}},"activeHuntAlert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]},"latestAlert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]},"activityEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"threatId":{"type":"string"},"kind":{"type":"string","enum":["threat_created","intel_attached","reassessment_requested","assessment_started","relevancy_completed","exposure_started","assessment_failed"]},"actorType":{"type":"string","enum":["system","agent","human"]},"runId":{"type":["string","null"]},"metadata":{"type":["object","null"],"properties":{"score":{"type":"number"},"hunting":{"type":"boolean"},"executionId":{"type":"string"},"canonicalKey":{"type":"string"},"label":{"type":"string"},"userId":{"type":"string"}}},"createdAt":{"type":"string"}},"required":["id","threatId","kind","actorType","runId","metadata","createdAt"]}},"capabilities":{"type":"object","properties":{"canReadEvidence":{"type":"boolean"},"canReassess":{"type":"boolean"},"canTriage":{"type":"boolean"}},"required":["canReadEvidence","canReassess","canTriage"]}},"required":["threat","runs","deliverables","intelItems","alerts","activeHuntAlert","latestAlert","activityEvents"]}}},"required":["threats"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/threats/{id}":{"get":{"summary":"Get Threat detail","description":"A Threat with its assessment runs (newest first), deliverables, and all linked Hunt Alert episodes.","tags":["Hunt"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/threats/:id\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"threat":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"canonicalType":{"type":"string","enum":["vulnerability","campaign"]},"canonicalKeyType":{"type":"string","enum":["cve","advisory","vendor_advisory","campaign_name","malware_family"]},"canonicalKey":{"type":"string"},"title":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"actorId":{"type":["string","null"]},"intelItemIds":{"type":"array","items":{"type":"string"}},"relevancyScore":{"type":["number","null"]},"exposureScore":{"type":["number","null"]},"exposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"coverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"detectionEngineeringNote":{"type":["string","null"]},"latestRunId":{"type":["string","null"]},"assessmentRunningExecutionId":{"type":["string","null"]},"assessmentFailedAt":{"type":["string","null"]},"latestAlertId":{"type":["string","null"]},"activeHuntAlertId":{"type":["string","null"]},"dismissedAt":{"type":["string","null"]},"dismissedByUserId":{"type":["string","null"]},"dismissedReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","canonicalType","canonicalKeyType","canonicalKey","title","aliases","actorId","intelItemIds","relevancyScore","exposureScore","exposureState","coverageState","detectionEngineeringNote","latestRunId","assessmentRunningExecutionId","assessmentFailedAt","latestAlertId","activeHuntAlertId","dismissedAt","dismissedByUserId","dismissedReason","createdAt","updatedAt"]},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"threatId":{"type":"string"},"kind":{"type":"string","enum":["create","update"]},"trigger":{"type":"string","enum":["new_threat","intel_attached","manual","backfill","reclassification"]},"runAt":{"type":"string"},"relevancyExecutionId":{"type":"string"},"relevancyScore":{"type":"number"},"relevancyHeadline":{"type":["string","null"]},"relevancyExplanation":{"type":"array","items":{"type":"string"}},"exposureExecutionId":{"type":["string","null"]},"exposureScore":{"type":["number","null"]},"exposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"exposureStory":{"type":["object","null"],"properties":{"exposureState":{"type":"string","enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive"]},"headline":{"type":"string"},"summary":{"type":"array","items":{"type":"string"}},"exposureChecks":{"type":"array","items":{"type":"object","properties":{"purpose":{"type":"string","enum":["exposure","ioc","telemetry","detection_coverage"]},"indicatorId":{"type":"string"},"authoritative":{"type":"boolean"},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"]},"indicatorRole":{"type":"string","enum":["compromise","relevance"]},"checked":{"type":"string"},"source":{"type":"string"},"scope":{"type":"string"},"timeWindow":{"type":["object","null"],"properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"outcome":{"type":"string","enum":["found","not_found","inconclusive"]},"evidence":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["purpose","checked","source","scope","timeWindow","outcome","evidence","limitations"]}},"assets":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"kind":{"type":"string","enum":["repository","host","service","cloud_resource","identity","package","domain","saas_account","container_image","other"],"default":"other"},"platform":{"type":["string","null"],"default":null},"source":{"type":"string"},"internetFacing":{"type":["boolean","null"]},"evidence":{"type":"string"}},"required":["identifier","kind","platform","source","internetFacing","evidence"]}},"iocFindings":{"type":"array","items":{"type":"object","properties":{"indicatorId":{"type":"string"},"authoritative":{"type":"boolean"},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"]},"role":{"type":"string","enum":["compromise","relevance"],"default":"compromise"},"platform":{"type":["string","null"],"default":null},"iocValue":{"type":"string"},"evidence":{"type":"string"},"affectedSystems":{"type":"array","items":{"type":"string"}}},"required":["iocType","role","platform","iocValue","evidence","affectedSystems"]}},"discoveredIndicators":{"type":"array","items":{"type":"object","properties":{"indicatorId":{"type":"string","minLength":1,"description":"Unique run-local id such as discovered-1."},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"],"description":"Canonical indicator type."},"role":{"type":"string","enum":["compromise","relevance"],"description":"Required role with no default."},"platform":{"type":"string","description":"Optional registry/ecosystem for package or image indicators."},"iocValue":{"type":"string","minLength":1,"maxLength":2048,"description":"One exact atomic indicator value, never a prose/composite description."},"roleRationale":{"type":"string","minLength":1,"description":"Why a match alone does or does not justify a compromise claim."},"evidence":{"type":"string","minLength":1,"description":"Cited evidence establishing this as a threat indicator."}},"required":["indicatorId","iocType","role","iocValue","roleRationale","evidence"]}},"observations":{"type":"array","items":{"type":"object","properties":{"observationId":{"type":"string","minLength":1,"description":"Unique run-local observation id."},"kind":{"type":"string","enum":["software_presence","vulnerable_asset","configuration_exposure","exploit_attempt","suspicious_behavior","confirmed_malicious_behavior"],"description":"Semantic kind of customer-environment observation."},"summary":{"type":"string","minLength":1,"description":"Concise statement of what was observed."},"evidence":{"type":"string","minLength":1,"description":"Cited customer-environment evidence."},"affectedSystems":{"type":"array","items":{"type":"string","description":"Affected system identifier."},"description":"Affected customer assets; empty when none."},"timeWindow":{"type":"object","properties":{"start":{"type":"string","description":"Observation window start."},"end":{"type":"string","description":"Observation window end."}},"required":["start","end"]}},"required":["observationId","kind","summary","evidence","affectedSystems"]}},"researchContext":{"type":"array","items":{"type":"object","properties":{"contextId":{"type":"string","minLength":1,"description":"Unique run-local context id."},"summary":{"type":"string","minLength":1,"description":"Concise public/intel fact."},"evidence":{"type":"string","minLength":1,"description":"Cited evidence for the context fact."}},"required":["contextId","summary","evidence"]}},"conclusion":{"type":"object","properties":{"headline":{"type":"string","minLength":1,"description":"One self-contained sentence stating the environment verdict and the evidence-based interpretation that determines the score. Never merely report that an indicator matched: if activity is attributable to security inspection, scanning, testing, or another evidenced benign cause, state both the match and that interpretation so the reader immediately understands why it is not concerning. When the exposure score is in the residual band (35-59), state the residual condition — what concretely remains exposed, unpatched, or unverified — never a bare \"no exposure found\"."},"summary":{"type":"array","items":{"type":"string","description":"One concise cited verdict bullet."},"minItems":3,"maxItems":8,"description":"3-8 concise bullets explaining the environment verdict."},"supportingFindingIds":{"type":"array","items":{"type":"string","description":"An input-catalog indicatorId that appears in indicatorChecks, or an observationId defined in observations, copied verbatim."},"description":"Authoritative input-check or environment-observation ids supporting the verdict, copied verbatim from ids defined in this output; never discovered-indicator ids, context ids, or invented shorthand ids."},"contextIds":{"type":"array","items":{"type":"string","description":"Research context id used for interpretation."},"description":"Referenced public/intel context ids."}},"required":["headline","summary","supportingFindingIds","contextIds"]},"detectionCoverage":{"type":"object","properties":{"state":{"type":"string","enum":["none","partial","covered","unknown"]},"searches":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"criteria":{"type":"string"},"resultCount":{"type":"number"},"evidence":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["source","criteria","resultCount","evidence","limitations"]}},"matches":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["rule_proposal","deployed_rule","detection_agent"]},"platform":{"type":["string","null"]},"url":{"type":["string","null"]}},"required":["id","name","kind"]},"coverage":{"type":"string","enum":["partial","covered","unknown"]},"rationale":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["ref","coverage","rationale","limitations"]}}},"required":["state","searches","matches"]},"gaps":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"scopeKey":{"type":"string"},"blocking":{"type":"boolean"},"description":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["product","logSource","scopeType","scopeId","scopeKey","blocking","description","limitations"]}},"nextSteps":{"type":"array","items":{"type":"string"}},"timeline":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"description":{"type":"string"}},"required":["timestamp","description"]}},"executionId":{"type":"string"},"runAt":{"type":"string"}},"required":["exposureState","summary","exposureChecks","assets","iocFindings","detectionCoverage","gaps","nextSteps","executionId","runAt"]},"coverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"hasFoundIoc":{"type":"boolean"},"hasBlockingGap":{"type":"boolean"},"diff":{"type":["object","null"],"properties":{"prevRunId":{"type":"string"},"beforeExposureScore":{"type":["number","null"]},"afterExposureScore":{"type":["number","null"]},"beforeExposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"afterExposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"beforeCoverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"afterCoverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["prevRunId","beforeExposureScore","afterExposureScore","beforeExposureState","afterExposureState","beforeCoverageState","afterCoverageState","reasons"]}},"required":["id","threatId","kind","trigger","runAt","relevancyExecutionId","relevancyScore","relevancyExplanation","exposureExecutionId","exposureScore","exposureState","exposureStory","coverageState","hasFoundIoc","hasBlockingGap","diff"]}},"deliverables":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"threatId":{"type":"string"},"executionId":{"type":"string"},"createdAt":{"type":"string"},"supersededById":{"type":["string","null"]},"kind":{"type":"string","const":"rule_proposal"},"proposalId":{"type":["string","null"]},"pullRequestUrl":{"type":["string","null"]},"intent":{"type":"string"},"pinning":{"type":"string","enum":["ioc_pinned","behavioral","mixed"]},"pinnedIocs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}},"required":["type","value"]}},"targetProduct":{"type":["string","null"]},"targetLogSource":{"type":["string","null"]},"lifecycleStatus":{"type":"string","enum":["authoring","drafted","in_review","shipped","dismissed","failed"]}},"required":["id","organizationId","threatId","executionId","createdAt","supersededById","kind","proposalId","pullRequestUrl","intent","pinning","pinnedIocs","targetProduct","targetLogSource","lifecycleStatus"]},{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"threatId":{"type":"string"},"executionId":{"type":"string"},"createdAt":{"type":"string"},"supersededById":{"type":["string","null"]},"kind":{"type":"string","const":"gap"},"gapId":{"type":["string","null"]},"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"scopeKey":{"type":"string"},"blocking":{"type":"boolean"},"description":{"type":"string"},"gapStatus":{"type":"string","enum":["open","resolved","dismissed"]},"establishedAt":{"type":"string"},"statusAt":{"type":["string","null"]},"statusActor":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"agent"},"runId":{"type":"string"}},"required":["type","runId"]},{"type":"object","properties":{"type":{"type":"string","const":"human"},"userId":{"type":"string"}},"required":["type","userId"]},{"type":"null"}]},"statusReason":{"type":["string","null"]},"otherLinkedThreats":{"type":"array","items":{"type":"object","properties":{"threatId":{"type":"string"},"threatTitle":{"type":"string"},"canonicalKey":{"type":"string"},"blocking":{"type":"boolean"}},"required":["threatId","threatTitle","canonicalKey","blocking"]}}},"required":["id","organizationId","threatId","executionId","createdAt","supersededById","kind","product","logSource","scopeType","scopeId","scopeKey","blocking","description","gapStatus","establishedAt","statusAt","statusActor","statusReason"]}]}},"intelItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"publisher":{"type":"string"},"sourceName":{"type":["string","null"]},"url":{"type":["string","null"]},"publishedAt":{"type":"string"},"tldr":{"type":["string","null"]},"attackPath":{"type":"array","items":{"type":"string"}},"summary":{"type":["string","null"]},"attackTechniques":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]}},"malware":{"type":"array","items":{"type":"string"}},"actors":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"type":"string"}},"affectedProducts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"versions":{"type":"array","items":{"type":"string"}}},"required":["name","versions"]}},"eventFirstSeen":{"type":["string","null"]},"eventLastSeen":{"type":["string","null"]}},"required":["id","title","publisher","url","publishedAt","tldr","attackPath"]}},"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]}},"activeHuntAlert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]},"latestAlert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]},"activityEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"threatId":{"type":"string"},"kind":{"type":"string","enum":["threat_created","intel_attached","reassessment_requested","assessment_started","relevancy_completed","exposure_started","assessment_failed"]},"actorType":{"type":"string","enum":["system","agent","human"]},"runId":{"type":["string","null"]},"metadata":{"type":["object","null"],"properties":{"score":{"type":"number"},"hunting":{"type":"boolean"},"executionId":{"type":"string"},"canonicalKey":{"type":"string"},"label":{"type":"string"},"userId":{"type":"string"}}},"createdAt":{"type":"string"}},"required":["id","threatId","kind","actorType","runId","metadata","createdAt"]}},"capabilities":{"type":"object","properties":{"canReadEvidence":{"type":"boolean"},"canReassess":{"type":"boolean"},"canTriage":{"type":"boolean"}},"required":["canReadEvidence","canReassess","canTriage"]}},"required":["threat","runs","deliverables","intelItems","alerts","activeHuntAlert","latestAlert","activityEvents"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Threat not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/threats/{id}/dismiss":{"post":{"summary":"Dismiss a Threat","description":"Explicitly dismiss a non-alert Threat (monitoring / covered / clear / blocked / not relevant) with an optional reason. Records who and when. New material positive evidence later auto-restores it.","tags":["Hunt"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/threats/:id/dismiss\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"reason\":\"string\"}'"}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"threat":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"canonicalType":{"type":"string","enum":["vulnerability","campaign"]},"canonicalKeyType":{"type":"string","enum":["cve","advisory","vendor_advisory","campaign_name","malware_family"]},"canonicalKey":{"type":"string"},"title":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"actorId":{"type":["string","null"]},"intelItemIds":{"type":"array","items":{"type":"string"}},"relevancyScore":{"type":["number","null"]},"exposureScore":{"type":["number","null"]},"exposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"coverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"detectionEngineeringNote":{"type":["string","null"]},"latestRunId":{"type":["string","null"]},"assessmentRunningExecutionId":{"type":["string","null"]},"assessmentFailedAt":{"type":["string","null"]},"latestAlertId":{"type":["string","null"]},"activeHuntAlertId":{"type":["string","null"]},"dismissedAt":{"type":["string","null"]},"dismissedByUserId":{"type":["string","null"]},"dismissedReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","canonicalType","canonicalKeyType","canonicalKey","title","aliases","actorId","intelItemIds","relevancyScore","exposureScore","exposureState","coverageState","detectionEngineeringNote","latestRunId","assessmentRunningExecutionId","assessmentFailedAt","latestAlertId","activeHuntAlertId","dismissedAt","dismissedByUserId","dismissedReason","createdAt","updatedAt"]},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"threatId":{"type":"string"},"kind":{"type":"string","enum":["create","update"]},"trigger":{"type":"string","enum":["new_threat","intel_attached","manual","backfill","reclassification"]},"runAt":{"type":"string"},"relevancyExecutionId":{"type":"string"},"relevancyScore":{"type":"number"},"relevancyHeadline":{"type":["string","null"]},"relevancyExplanation":{"type":"array","items":{"type":"string"}},"exposureExecutionId":{"type":["string","null"]},"exposureScore":{"type":["number","null"]},"exposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"exposureStory":{"type":["object","null"],"properties":{"exposureState":{"type":"string","enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive"]},"headline":{"type":"string"},"summary":{"type":"array","items":{"type":"string"}},"exposureChecks":{"type":"array","items":{"type":"object","properties":{"purpose":{"type":"string","enum":["exposure","ioc","telemetry","detection_coverage"]},"indicatorId":{"type":"string"},"authoritative":{"type":"boolean"},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"]},"indicatorRole":{"type":"string","enum":["compromise","relevance"]},"checked":{"type":"string"},"source":{"type":"string"},"scope":{"type":"string"},"timeWindow":{"type":["object","null"],"properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"outcome":{"type":"string","enum":["found","not_found","inconclusive"]},"evidence":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["purpose","checked","source","scope","timeWindow","outcome","evidence","limitations"]}},"assets":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"kind":{"type":"string","enum":["repository","host","service","cloud_resource","identity","package","domain","saas_account","container_image","other"],"default":"other"},"platform":{"type":["string","null"],"default":null},"source":{"type":"string"},"internetFacing":{"type":["boolean","null"]},"evidence":{"type":"string"}},"required":["identifier","kind","platform","source","internetFacing","evidence"]}},"iocFindings":{"type":"array","items":{"type":"object","properties":{"indicatorId":{"type":"string"},"authoritative":{"type":"boolean"},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"]},"role":{"type":"string","enum":["compromise","relevance"],"default":"compromise"},"platform":{"type":["string","null"],"default":null},"iocValue":{"type":"string"},"evidence":{"type":"string"},"affectedSystems":{"type":"array","items":{"type":"string"}}},"required":["iocType","role","platform","iocValue","evidence","affectedSystems"]}},"discoveredIndicators":{"type":"array","items":{"type":"object","properties":{"indicatorId":{"type":"string","minLength":1,"description":"Unique run-local id such as discovered-1."},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"],"description":"Canonical indicator type."},"role":{"type":"string","enum":["compromise","relevance"],"description":"Required role with no default."},"platform":{"type":"string","description":"Optional registry/ecosystem for package or image indicators."},"iocValue":{"type":"string","minLength":1,"maxLength":2048,"description":"One exact atomic indicator value, never a prose/composite description."},"roleRationale":{"type":"string","minLength":1,"description":"Why a match alone does or does not justify a compromise claim."},"evidence":{"type":"string","minLength":1,"description":"Cited evidence establishing this as a threat indicator."}},"required":["indicatorId","iocType","role","iocValue","roleRationale","evidence"]}},"observations":{"type":"array","items":{"type":"object","properties":{"observationId":{"type":"string","minLength":1,"description":"Unique run-local observation id."},"kind":{"type":"string","enum":["software_presence","vulnerable_asset","configuration_exposure","exploit_attempt","suspicious_behavior","confirmed_malicious_behavior"],"description":"Semantic kind of customer-environment observation."},"summary":{"type":"string","minLength":1,"description":"Concise statement of what was observed."},"evidence":{"type":"string","minLength":1,"description":"Cited customer-environment evidence."},"affectedSystems":{"type":"array","items":{"type":"string","description":"Affected system identifier."},"description":"Affected customer assets; empty when none."},"timeWindow":{"type":"object","properties":{"start":{"type":"string","description":"Observation window start."},"end":{"type":"string","description":"Observation window end."}},"required":["start","end"]}},"required":["observationId","kind","summary","evidence","affectedSystems"]}},"researchContext":{"type":"array","items":{"type":"object","properties":{"contextId":{"type":"string","minLength":1,"description":"Unique run-local context id."},"summary":{"type":"string","minLength":1,"description":"Concise public/intel fact."},"evidence":{"type":"string","minLength":1,"description":"Cited evidence for the context fact."}},"required":["contextId","summary","evidence"]}},"conclusion":{"type":"object","properties":{"headline":{"type":"string","minLength":1,"description":"One self-contained sentence stating the environment verdict and the evidence-based interpretation that determines the score. Never merely report that an indicator matched: if activity is attributable to security inspection, scanning, testing, or another evidenced benign cause, state both the match and that interpretation so the reader immediately understands why it is not concerning. When the exposure score is in the residual band (35-59), state the residual condition — what concretely remains exposed, unpatched, or unverified — never a bare \"no exposure found\"."},"summary":{"type":"array","items":{"type":"string","description":"One concise cited verdict bullet."},"minItems":3,"maxItems":8,"description":"3-8 concise bullets explaining the environment verdict."},"supportingFindingIds":{"type":"array","items":{"type":"string","description":"An input-catalog indicatorId that appears in indicatorChecks, or an observationId defined in observations, copied verbatim."},"description":"Authoritative input-check or environment-observation ids supporting the verdict, copied verbatim from ids defined in this output; never discovered-indicator ids, context ids, or invented shorthand ids."},"contextIds":{"type":"array","items":{"type":"string","description":"Research context id used for interpretation."},"description":"Referenced public/intel context ids."}},"required":["headline","summary","supportingFindingIds","contextIds"]},"detectionCoverage":{"type":"object","properties":{"state":{"type":"string","enum":["none","partial","covered","unknown"]},"searches":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"criteria":{"type":"string"},"resultCount":{"type":"number"},"evidence":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["source","criteria","resultCount","evidence","limitations"]}},"matches":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["rule_proposal","deployed_rule","detection_agent"]},"platform":{"type":["string","null"]},"url":{"type":["string","null"]}},"required":["id","name","kind"]},"coverage":{"type":"string","enum":["partial","covered","unknown"]},"rationale":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["ref","coverage","rationale","limitations"]}}},"required":["state","searches","matches"]},"gaps":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"scopeKey":{"type":"string"},"blocking":{"type":"boolean"},"description":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["product","logSource","scopeType","scopeId","scopeKey","blocking","description","limitations"]}},"nextSteps":{"type":"array","items":{"type":"string"}},"timeline":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"description":{"type":"string"}},"required":["timestamp","description"]}},"executionId":{"type":"string"},"runAt":{"type":"string"}},"required":["exposureState","summary","exposureChecks","assets","iocFindings","detectionCoverage","gaps","nextSteps","executionId","runAt"]},"coverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"hasFoundIoc":{"type":"boolean"},"hasBlockingGap":{"type":"boolean"},"diff":{"type":["object","null"],"properties":{"prevRunId":{"type":"string"},"beforeExposureScore":{"type":["number","null"]},"afterExposureScore":{"type":["number","null"]},"beforeExposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"afterExposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"beforeCoverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"afterCoverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["prevRunId","beforeExposureScore","afterExposureScore","beforeExposureState","afterExposureState","beforeCoverageState","afterCoverageState","reasons"]}},"required":["id","threatId","kind","trigger","runAt","relevancyExecutionId","relevancyScore","relevancyExplanation","exposureExecutionId","exposureScore","exposureState","exposureStory","coverageState","hasFoundIoc","hasBlockingGap","diff"]}},"deliverables":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"threatId":{"type":"string"},"executionId":{"type":"string"},"createdAt":{"type":"string"},"supersededById":{"type":["string","null"]},"kind":{"type":"string","const":"rule_proposal"},"proposalId":{"type":["string","null"]},"pullRequestUrl":{"type":["string","null"]},"intent":{"type":"string"},"pinning":{"type":"string","enum":["ioc_pinned","behavioral","mixed"]},"pinnedIocs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}},"required":["type","value"]}},"targetProduct":{"type":["string","null"]},"targetLogSource":{"type":["string","null"]},"lifecycleStatus":{"type":"string","enum":["authoring","drafted","in_review","shipped","dismissed","failed"]}},"required":["id","organizationId","threatId","executionId","createdAt","supersededById","kind","proposalId","pullRequestUrl","intent","pinning","pinnedIocs","targetProduct","targetLogSource","lifecycleStatus"]},{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"threatId":{"type":"string"},"executionId":{"type":"string"},"createdAt":{"type":"string"},"supersededById":{"type":["string","null"]},"kind":{"type":"string","const":"gap"},"gapId":{"type":["string","null"]},"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"scopeKey":{"type":"string"},"blocking":{"type":"boolean"},"description":{"type":"string"},"gapStatus":{"type":"string","enum":["open","resolved","dismissed"]},"establishedAt":{"type":"string"},"statusAt":{"type":["string","null"]},"statusActor":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"agent"},"runId":{"type":"string"}},"required":["type","runId"]},{"type":"object","properties":{"type":{"type":"string","const":"human"},"userId":{"type":"string"}},"required":["type","userId"]},{"type":"null"}]},"statusReason":{"type":["string","null"]},"otherLinkedThreats":{"type":"array","items":{"type":"object","properties":{"threatId":{"type":"string"},"threatTitle":{"type":"string"},"canonicalKey":{"type":"string"},"blocking":{"type":"boolean"}},"required":["threatId","threatTitle","canonicalKey","blocking"]}}},"required":["id","organizationId","threatId","executionId","createdAt","supersededById","kind","product","logSource","scopeType","scopeId","scopeKey","blocking","description","gapStatus","establishedAt","statusAt","statusActor","statusReason"]}]}},"intelItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"publisher":{"type":"string"},"sourceName":{"type":["string","null"]},"url":{"type":["string","null"]},"publishedAt":{"type":"string"},"tldr":{"type":["string","null"]},"attackPath":{"type":"array","items":{"type":"string"}},"summary":{"type":["string","null"]},"attackTechniques":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]}},"malware":{"type":"array","items":{"type":"string"}},"actors":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"type":"string"}},"affectedProducts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"versions":{"type":"array","items":{"type":"string"}}},"required":["name","versions"]}},"eventFirstSeen":{"type":["string","null"]},"eventLastSeen":{"type":["string","null"]}},"required":["id","title","publisher","url","publishedAt","tldr","attackPath"]}},"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]}},"activeHuntAlert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]},"latestAlert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]},"activityEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"threatId":{"type":"string"},"kind":{"type":"string","enum":["threat_created","intel_attached","reassessment_requested","assessment_started","relevancy_completed","exposure_started","assessment_failed"]},"actorType":{"type":"string","enum":["system","agent","human"]},"runId":{"type":["string","null"]},"metadata":{"type":["object","null"],"properties":{"score":{"type":"number"},"hunting":{"type":"boolean"},"executionId":{"type":"string"},"canonicalKey":{"type":"string"},"label":{"type":"string"},"userId":{"type":"string"}}},"createdAt":{"type":"string"}},"required":["id","threatId","kind","actorType","runId","metadata","createdAt"]}},"capabilities":{"type":"object","properties":{"canReadEvidence":{"type":"boolean"},"canReassess":{"type":"boolean"},"canTriage":{"type":"boolean"}},"required":["canReadEvidence","canReassess","canTriage"]}},"required":["threat","runs","deliverables","intelItems","alerts","activeHuntAlert","latestAlert","activityEvents"]}}}},"400":{"description":"Threat is alert-driven (active / resolved) and cannot be dismissed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Caller lacks the alert.triage permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/threats/{id}/restore":{"post":{"summary":"Restore a dismissed Threat","description":"Clear an explicit dismissal, returning the Threat to its derived status.","tags":["Hunt"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/threats/:id/restore\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"threat":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"canonicalType":{"type":"string","enum":["vulnerability","campaign"]},"canonicalKeyType":{"type":"string","enum":["cve","advisory","vendor_advisory","campaign_name","malware_family"]},"canonicalKey":{"type":"string"},"title":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"actorId":{"type":["string","null"]},"intelItemIds":{"type":"array","items":{"type":"string"}},"relevancyScore":{"type":["number","null"]},"exposureScore":{"type":["number","null"]},"exposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"coverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"detectionEngineeringNote":{"type":["string","null"]},"latestRunId":{"type":["string","null"]},"assessmentRunningExecutionId":{"type":["string","null"]},"assessmentFailedAt":{"type":["string","null"]},"latestAlertId":{"type":["string","null"]},"activeHuntAlertId":{"type":["string","null"]},"dismissedAt":{"type":["string","null"]},"dismissedByUserId":{"type":["string","null"]},"dismissedReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","canonicalType","canonicalKeyType","canonicalKey","title","aliases","actorId","intelItemIds","relevancyScore","exposureScore","exposureState","coverageState","detectionEngineeringNote","latestRunId","assessmentRunningExecutionId","assessmentFailedAt","latestAlertId","activeHuntAlertId","dismissedAt","dismissedByUserId","dismissedReason","createdAt","updatedAt"]},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"threatId":{"type":"string"},"kind":{"type":"string","enum":["create","update"]},"trigger":{"type":"string","enum":["new_threat","intel_attached","manual","backfill","reclassification"]},"runAt":{"type":"string"},"relevancyExecutionId":{"type":"string"},"relevancyScore":{"type":"number"},"relevancyHeadline":{"type":["string","null"]},"relevancyExplanation":{"type":"array","items":{"type":"string"}},"exposureExecutionId":{"type":["string","null"]},"exposureScore":{"type":["number","null"]},"exposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"exposureStory":{"type":["object","null"],"properties":{"exposureState":{"type":"string","enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive"]},"headline":{"type":"string"},"summary":{"type":"array","items":{"type":"string"}},"exposureChecks":{"type":"array","items":{"type":"object","properties":{"purpose":{"type":"string","enum":["exposure","ioc","telemetry","detection_coverage"]},"indicatorId":{"type":"string"},"authoritative":{"type":"boolean"},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"]},"indicatorRole":{"type":"string","enum":["compromise","relevance"]},"checked":{"type":"string"},"source":{"type":"string"},"scope":{"type":"string"},"timeWindow":{"type":["object","null"],"properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"outcome":{"type":"string","enum":["found","not_found","inconclusive"]},"evidence":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["purpose","checked","source","scope","timeWindow","outcome","evidence","limitations"]}},"assets":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"kind":{"type":"string","enum":["repository","host","service","cloud_resource","identity","package","domain","saas_account","container_image","other"],"default":"other"},"platform":{"type":["string","null"],"default":null},"source":{"type":"string"},"internetFacing":{"type":["boolean","null"]},"evidence":{"type":"string"}},"required":["identifier","kind","platform","source","internetFacing","evidence"]}},"iocFindings":{"type":"array","items":{"type":"object","properties":{"indicatorId":{"type":"string"},"authoritative":{"type":"boolean"},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"]},"role":{"type":"string","enum":["compromise","relevance"],"default":"compromise"},"platform":{"type":["string","null"],"default":null},"iocValue":{"type":"string"},"evidence":{"type":"string"},"affectedSystems":{"type":"array","items":{"type":"string"}}},"required":["iocType","role","platform","iocValue","evidence","affectedSystems"]}},"discoveredIndicators":{"type":"array","items":{"type":"object","properties":{"indicatorId":{"type":"string","minLength":1,"description":"Unique run-local id such as discovered-1."},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"],"description":"Canonical indicator type."},"role":{"type":"string","enum":["compromise","relevance"],"description":"Required role with no default."},"platform":{"type":"string","description":"Optional registry/ecosystem for package or image indicators."},"iocValue":{"type":"string","minLength":1,"maxLength":2048,"description":"One exact atomic indicator value, never a prose/composite description."},"roleRationale":{"type":"string","minLength":1,"description":"Why a match alone does or does not justify a compromise claim."},"evidence":{"type":"string","minLength":1,"description":"Cited evidence establishing this as a threat indicator."}},"required":["indicatorId","iocType","role","iocValue","roleRationale","evidence"]}},"observations":{"type":"array","items":{"type":"object","properties":{"observationId":{"type":"string","minLength":1,"description":"Unique run-local observation id."},"kind":{"type":"string","enum":["software_presence","vulnerable_asset","configuration_exposure","exploit_attempt","suspicious_behavior","confirmed_malicious_behavior"],"description":"Semantic kind of customer-environment observation."},"summary":{"type":"string","minLength":1,"description":"Concise statement of what was observed."},"evidence":{"type":"string","minLength":1,"description":"Cited customer-environment evidence."},"affectedSystems":{"type":"array","items":{"type":"string","description":"Affected system identifier."},"description":"Affected customer assets; empty when none."},"timeWindow":{"type":"object","properties":{"start":{"type":"string","description":"Observation window start."},"end":{"type":"string","description":"Observation window end."}},"required":["start","end"]}},"required":["observationId","kind","summary","evidence","affectedSystems"]}},"researchContext":{"type":"array","items":{"type":"object","properties":{"contextId":{"type":"string","minLength":1,"description":"Unique run-local context id."},"summary":{"type":"string","minLength":1,"description":"Concise public/intel fact."},"evidence":{"type":"string","minLength":1,"description":"Cited evidence for the context fact."}},"required":["contextId","summary","evidence"]}},"conclusion":{"type":"object","properties":{"headline":{"type":"string","minLength":1,"description":"One self-contained sentence stating the environment verdict and the evidence-based interpretation that determines the score. Never merely report that an indicator matched: if activity is attributable to security inspection, scanning, testing, or another evidenced benign cause, state both the match and that interpretation so the reader immediately understands why it is not concerning. When the exposure score is in the residual band (35-59), state the residual condition — what concretely remains exposed, unpatched, or unverified — never a bare \"no exposure found\"."},"summary":{"type":"array","items":{"type":"string","description":"One concise cited verdict bullet."},"minItems":3,"maxItems":8,"description":"3-8 concise bullets explaining the environment verdict."},"supportingFindingIds":{"type":"array","items":{"type":"string","description":"An input-catalog indicatorId that appears in indicatorChecks, or an observationId defined in observations, copied verbatim."},"description":"Authoritative input-check or environment-observation ids supporting the verdict, copied verbatim from ids defined in this output; never discovered-indicator ids, context ids, or invented shorthand ids."},"contextIds":{"type":"array","items":{"type":"string","description":"Research context id used for interpretation."},"description":"Referenced public/intel context ids."}},"required":["headline","summary","supportingFindingIds","contextIds"]},"detectionCoverage":{"type":"object","properties":{"state":{"type":"string","enum":["none","partial","covered","unknown"]},"searches":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"criteria":{"type":"string"},"resultCount":{"type":"number"},"evidence":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["source","criteria","resultCount","evidence","limitations"]}},"matches":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["rule_proposal","deployed_rule","detection_agent"]},"platform":{"type":["string","null"]},"url":{"type":["string","null"]}},"required":["id","name","kind"]},"coverage":{"type":"string","enum":["partial","covered","unknown"]},"rationale":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["ref","coverage","rationale","limitations"]}}},"required":["state","searches","matches"]},"gaps":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"scopeKey":{"type":"string"},"blocking":{"type":"boolean"},"description":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["product","logSource","scopeType","scopeId","scopeKey","blocking","description","limitations"]}},"nextSteps":{"type":"array","items":{"type":"string"}},"timeline":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"description":{"type":"string"}},"required":["timestamp","description"]}},"executionId":{"type":"string"},"runAt":{"type":"string"}},"required":["exposureState","summary","exposureChecks","assets","iocFindings","detectionCoverage","gaps","nextSteps","executionId","runAt"]},"coverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"hasFoundIoc":{"type":"boolean"},"hasBlockingGap":{"type":"boolean"},"diff":{"type":["object","null"],"properties":{"prevRunId":{"type":"string"},"beforeExposureScore":{"type":["number","null"]},"afterExposureScore":{"type":["number","null"]},"beforeExposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"afterExposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"beforeCoverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"afterCoverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["prevRunId","beforeExposureScore","afterExposureScore","beforeExposureState","afterExposureState","beforeCoverageState","afterCoverageState","reasons"]}},"required":["id","threatId","kind","trigger","runAt","relevancyExecutionId","relevancyScore","relevancyExplanation","exposureExecutionId","exposureScore","exposureState","exposureStory","coverageState","hasFoundIoc","hasBlockingGap","diff"]}},"deliverables":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"threatId":{"type":"string"},"executionId":{"type":"string"},"createdAt":{"type":"string"},"supersededById":{"type":["string","null"]},"kind":{"type":"string","const":"rule_proposal"},"proposalId":{"type":["string","null"]},"pullRequestUrl":{"type":["string","null"]},"intent":{"type":"string"},"pinning":{"type":"string","enum":["ioc_pinned","behavioral","mixed"]},"pinnedIocs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}},"required":["type","value"]}},"targetProduct":{"type":["string","null"]},"targetLogSource":{"type":["string","null"]},"lifecycleStatus":{"type":"string","enum":["authoring","drafted","in_review","shipped","dismissed","failed"]}},"required":["id","organizationId","threatId","executionId","createdAt","supersededById","kind","proposalId","pullRequestUrl","intent","pinning","pinnedIocs","targetProduct","targetLogSource","lifecycleStatus"]},{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"threatId":{"type":"string"},"executionId":{"type":"string"},"createdAt":{"type":"string"},"supersededById":{"type":["string","null"]},"kind":{"type":"string","const":"gap"},"gapId":{"type":["string","null"]},"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"scopeKey":{"type":"string"},"blocking":{"type":"boolean"},"description":{"type":"string"},"gapStatus":{"type":"string","enum":["open","resolved","dismissed"]},"establishedAt":{"type":"string"},"statusAt":{"type":["string","null"]},"statusActor":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"agent"},"runId":{"type":"string"}},"required":["type","runId"]},{"type":"object","properties":{"type":{"type":"string","const":"human"},"userId":{"type":"string"}},"required":["type","userId"]},{"type":"null"}]},"statusReason":{"type":["string","null"]},"otherLinkedThreats":{"type":"array","items":{"type":"object","properties":{"threatId":{"type":"string"},"threatTitle":{"type":"string"},"canonicalKey":{"type":"string"},"blocking":{"type":"boolean"}},"required":["threatId","threatTitle","canonicalKey","blocking"]}}},"required":["id","organizationId","threatId","executionId","createdAt","supersededById","kind","product","logSource","scopeType","scopeId","scopeKey","blocking","description","gapStatus","establishedAt","statusAt","statusActor","statusReason"]}]}},"intelItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"publisher":{"type":"string"},"sourceName":{"type":["string","null"]},"url":{"type":["string","null"]},"publishedAt":{"type":"string"},"tldr":{"type":["string","null"]},"attackPath":{"type":"array","items":{"type":"string"}},"summary":{"type":["string","null"]},"attackTechniques":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]}},"malware":{"type":"array","items":{"type":"string"}},"actors":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"type":"string"}},"affectedProducts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"versions":{"type":"array","items":{"type":"string"}}},"required":["name","versions"]}},"eventFirstSeen":{"type":["string","null"]},"eventLastSeen":{"type":["string","null"]}},"required":["id","title","publisher","url","publishedAt","tldr","attackPath"]}},"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]}},"activeHuntAlert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]},"latestAlert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]},"activityEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"threatId":{"type":"string"},"kind":{"type":"string","enum":["threat_created","intel_attached","reassessment_requested","assessment_started","relevancy_completed","exposure_started","assessment_failed"]},"actorType":{"type":"string","enum":["system","agent","human"]},"runId":{"type":["string","null"]},"metadata":{"type":["object","null"],"properties":{"score":{"type":"number"},"hunting":{"type":"boolean"},"executionId":{"type":"string"},"canonicalKey":{"type":"string"},"label":{"type":"string"},"userId":{"type":"string"}}},"createdAt":{"type":"string"}},"required":["id","threatId","kind","actorType","runId","metadata","createdAt"]}},"capabilities":{"type":"object","properties":{"canReadEvidence":{"type":"boolean"},"canReassess":{"type":"boolean"},"canTriage":{"type":"boolean"}},"required":["canReadEvidence","canReassess","canTriage"]}},"required":["threat","runs","deliverables","intelItems","alerts","activeHuntAlert","latestAlert","activityEvents"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Caller lacks the alert.triage permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/threats/{id}/reassess":{"post":{"summary":"Reassess a Threat","description":"Manually trigger a fresh Threat-scoped assessment (relevancy gate -> exposure). Enqueues the assessment job; the run streams in the Threat detail activity timeline.","tags":["Hunt"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/threats/:id/reassess\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"enqueued":{"type":"boolean"},"executionId":{"type":"string"}},"required":["enqueued","executionId"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Caller lacks agent.execute on the built-in Hunt agents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Threat not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/threats/{id}/deliverables/{deliverableId}/gap-status":{"post":{"summary":"Dispose a gap via a threat finding","description":"Resolve or dismiss the observability gap behind a threat's gap finding, attributed to the acting human. The disposition applies to the shared gap entity — every linked threat's finding reflects it — and resolving a blocking gap re-assesses all blocked linked threats.","tags":["Hunt"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/threats/:id/deliverables/:deliverableId/gap-status\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"status\":\"resolved\",\"reason\":\"string\"}'"}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true},{"in":"path","name":"deliverableId","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["resolved","dismissed"]},"reason":{"type":"string"}},"required":["status"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"threat":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"canonicalType":{"type":"string","enum":["vulnerability","campaign"]},"canonicalKeyType":{"type":"string","enum":["cve","advisory","vendor_advisory","campaign_name","malware_family"]},"canonicalKey":{"type":"string"},"title":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"actorId":{"type":["string","null"]},"intelItemIds":{"type":"array","items":{"type":"string"}},"relevancyScore":{"type":["number","null"]},"exposureScore":{"type":["number","null"]},"exposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"coverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"detectionEngineeringNote":{"type":["string","null"]},"latestRunId":{"type":["string","null"]},"assessmentRunningExecutionId":{"type":["string","null"]},"assessmentFailedAt":{"type":["string","null"]},"latestAlertId":{"type":["string","null"]},"activeHuntAlertId":{"type":["string","null"]},"dismissedAt":{"type":["string","null"]},"dismissedByUserId":{"type":["string","null"]},"dismissedReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","canonicalType","canonicalKeyType","canonicalKey","title","aliases","actorId","intelItemIds","relevancyScore","exposureScore","exposureState","coverageState","detectionEngineeringNote","latestRunId","assessmentRunningExecutionId","assessmentFailedAt","latestAlertId","activeHuntAlertId","dismissedAt","dismissedByUserId","dismissedReason","createdAt","updatedAt"]},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"threatId":{"type":"string"},"kind":{"type":"string","enum":["create","update"]},"trigger":{"type":"string","enum":["new_threat","intel_attached","manual","backfill","reclassification"]},"runAt":{"type":"string"},"relevancyExecutionId":{"type":"string"},"relevancyScore":{"type":"number"},"relevancyHeadline":{"type":["string","null"]},"relevancyExplanation":{"type":"array","items":{"type":"string"}},"exposureExecutionId":{"type":["string","null"]},"exposureScore":{"type":["number","null"]},"exposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"exposureStory":{"type":["object","null"],"properties":{"exposureState":{"type":"string","enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive"]},"headline":{"type":"string"},"summary":{"type":"array","items":{"type":"string"}},"exposureChecks":{"type":"array","items":{"type":"object","properties":{"purpose":{"type":"string","enum":["exposure","ioc","telemetry","detection_coverage"]},"indicatorId":{"type":"string"},"authoritative":{"type":"boolean"},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"]},"indicatorRole":{"type":"string","enum":["compromise","relevance"]},"checked":{"type":"string"},"source":{"type":"string"},"scope":{"type":"string"},"timeWindow":{"type":["object","null"],"properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"outcome":{"type":"string","enum":["found","not_found","inconclusive"]},"evidence":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["purpose","checked","source","scope","timeWindow","outcome","evidence","limitations"]}},"assets":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"kind":{"type":"string","enum":["repository","host","service","cloud_resource","identity","package","domain","saas_account","container_image","other"],"default":"other"},"platform":{"type":["string","null"],"default":null},"source":{"type":"string"},"internetFacing":{"type":["boolean","null"]},"evidence":{"type":"string"}},"required":["identifier","kind","platform","source","internetFacing","evidence"]}},"iocFindings":{"type":"array","items":{"type":"object","properties":{"indicatorId":{"type":"string"},"authoritative":{"type":"boolean"},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"]},"role":{"type":"string","enum":["compromise","relevance"],"default":"compromise"},"platform":{"type":["string","null"],"default":null},"iocValue":{"type":"string"},"evidence":{"type":"string"},"affectedSystems":{"type":"array","items":{"type":"string"}}},"required":["iocType","role","platform","iocValue","evidence","affectedSystems"]}},"discoveredIndicators":{"type":"array","items":{"type":"object","properties":{"indicatorId":{"type":"string","minLength":1,"description":"Unique run-local id such as discovered-1."},"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"],"description":"Canonical indicator type."},"role":{"type":"string","enum":["compromise","relevance"],"description":"Required role with no default."},"platform":{"type":"string","description":"Optional registry/ecosystem for package or image indicators."},"iocValue":{"type":"string","minLength":1,"maxLength":2048,"description":"One exact atomic indicator value, never a prose/composite description."},"roleRationale":{"type":"string","minLength":1,"description":"Why a match alone does or does not justify a compromise claim."},"evidence":{"type":"string","minLength":1,"description":"Cited evidence establishing this as a threat indicator."}},"required":["indicatorId","iocType","role","iocValue","roleRationale","evidence"]}},"observations":{"type":"array","items":{"type":"object","properties":{"observationId":{"type":"string","minLength":1,"description":"Unique run-local observation id."},"kind":{"type":"string","enum":["software_presence","vulnerable_asset","configuration_exposure","exploit_attempt","suspicious_behavior","confirmed_malicious_behavior"],"description":"Semantic kind of customer-environment observation."},"summary":{"type":"string","minLength":1,"description":"Concise statement of what was observed."},"evidence":{"type":"string","minLength":1,"description":"Cited customer-environment evidence."},"affectedSystems":{"type":"array","items":{"type":"string","description":"Affected system identifier."},"description":"Affected customer assets; empty when none."},"timeWindow":{"type":"object","properties":{"start":{"type":"string","description":"Observation window start."},"end":{"type":"string","description":"Observation window end."}},"required":["start","end"]}},"required":["observationId","kind","summary","evidence","affectedSystems"]}},"researchContext":{"type":"array","items":{"type":"object","properties":{"contextId":{"type":"string","minLength":1,"description":"Unique run-local context id."},"summary":{"type":"string","minLength":1,"description":"Concise public/intel fact."},"evidence":{"type":"string","minLength":1,"description":"Cited evidence for the context fact."}},"required":["contextId","summary","evidence"]}},"conclusion":{"type":"object","properties":{"headline":{"type":"string","minLength":1,"description":"One self-contained sentence stating the environment verdict and the evidence-based interpretation that determines the score. Never merely report that an indicator matched: if activity is attributable to security inspection, scanning, testing, or another evidenced benign cause, state both the match and that interpretation so the reader immediately understands why it is not concerning. When the exposure score is in the residual band (35-59), state the residual condition — what concretely remains exposed, unpatched, or unverified — never a bare \"no exposure found\"."},"summary":{"type":"array","items":{"type":"string","description":"One concise cited verdict bullet."},"minItems":3,"maxItems":8,"description":"3-8 concise bullets explaining the environment verdict."},"supportingFindingIds":{"type":"array","items":{"type":"string","description":"An input-catalog indicatorId that appears in indicatorChecks, or an observationId defined in observations, copied verbatim."},"description":"Authoritative input-check or environment-observation ids supporting the verdict, copied verbatim from ids defined in this output; never discovered-indicator ids, context ids, or invented shorthand ids."},"contextIds":{"type":"array","items":{"type":"string","description":"Research context id used for interpretation."},"description":"Referenced public/intel context ids."}},"required":["headline","summary","supportingFindingIds","contextIds"]},"detectionCoverage":{"type":"object","properties":{"state":{"type":"string","enum":["none","partial","covered","unknown"]},"searches":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"criteria":{"type":"string"},"resultCount":{"type":"number"},"evidence":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["source","criteria","resultCount","evidence","limitations"]}},"matches":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["rule_proposal","deployed_rule","detection_agent"]},"platform":{"type":["string","null"]},"url":{"type":["string","null"]}},"required":["id","name","kind"]},"coverage":{"type":"string","enum":["partial","covered","unknown"]},"rationale":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["ref","coverage","rationale","limitations"]}}},"required":["state","searches","matches"]},"gaps":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"scopeKey":{"type":"string"},"blocking":{"type":"boolean"},"description":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}},"required":["product","logSource","scopeType","scopeId","scopeKey","blocking","description","limitations"]}},"nextSteps":{"type":"array","items":{"type":"string"}},"timeline":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string"},"description":{"type":"string"}},"required":["timestamp","description"]}},"executionId":{"type":"string"},"runAt":{"type":"string"}},"required":["exposureState","summary","exposureChecks","assets","iocFindings","detectionCoverage","gaps","nextSteps","executionId","runAt"]},"coverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"hasFoundIoc":{"type":"boolean"},"hasBlockingGap":{"type":"boolean"},"diff":{"type":["object","null"],"properties":{"prevRunId":{"type":"string"},"beforeExposureScore":{"type":["number","null"]},"afterExposureScore":{"type":["number","null"]},"beforeExposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"afterExposureState":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found","no_exposure_found","inconclusive",null]},"beforeCoverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"afterCoverageState":{"type":["string","null"],"enum":["none","partial","covered","unknown",null]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["prevRunId","beforeExposureScore","afterExposureScore","beforeExposureState","afterExposureState","beforeCoverageState","afterCoverageState","reasons"]}},"required":["id","threatId","kind","trigger","runAt","relevancyExecutionId","relevancyScore","relevancyExplanation","exposureExecutionId","exposureScore","exposureState","exposureStory","coverageState","hasFoundIoc","hasBlockingGap","diff"]}},"deliverables":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"threatId":{"type":"string"},"executionId":{"type":"string"},"createdAt":{"type":"string"},"supersededById":{"type":["string","null"]},"kind":{"type":"string","const":"rule_proposal"},"proposalId":{"type":["string","null"]},"pullRequestUrl":{"type":["string","null"]},"intent":{"type":"string"},"pinning":{"type":"string","enum":["ioc_pinned","behavioral","mixed"]},"pinnedIocs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}},"required":["type","value"]}},"targetProduct":{"type":["string","null"]},"targetLogSource":{"type":["string","null"]},"lifecycleStatus":{"type":"string","enum":["authoring","drafted","in_review","shipped","dismissed","failed"]}},"required":["id","organizationId","threatId","executionId","createdAt","supersededById","kind","proposalId","pullRequestUrl","intent","pinning","pinnedIocs","targetProduct","targetLogSource","lifecycleStatus"]},{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"threatId":{"type":"string"},"executionId":{"type":"string"},"createdAt":{"type":"string"},"supersededById":{"type":["string","null"]},"kind":{"type":"string","const":"gap"},"gapId":{"type":["string","null"]},"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"scopeKey":{"type":"string"},"blocking":{"type":"boolean"},"description":{"type":"string"},"gapStatus":{"type":"string","enum":["open","resolved","dismissed"]},"establishedAt":{"type":"string"},"statusAt":{"type":["string","null"]},"statusActor":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"agent"},"runId":{"type":"string"}},"required":["type","runId"]},{"type":"object","properties":{"type":{"type":"string","const":"human"},"userId":{"type":"string"}},"required":["type","userId"]},{"type":"null"}]},"statusReason":{"type":["string","null"]},"otherLinkedThreats":{"type":"array","items":{"type":"object","properties":{"threatId":{"type":"string"},"threatTitle":{"type":"string"},"canonicalKey":{"type":"string"},"blocking":{"type":"boolean"}},"required":["threatId","threatTitle","canonicalKey","blocking"]}}},"required":["id","organizationId","threatId","executionId","createdAt","supersededById","kind","product","logSource","scopeType","scopeId","scopeKey","blocking","description","gapStatus","establishedAt","statusAt","statusActor","statusReason"]}]}},"intelItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"publisher":{"type":"string"},"sourceName":{"type":["string","null"]},"url":{"type":["string","null"]},"publishedAt":{"type":"string"},"tldr":{"type":["string","null"]},"attackPath":{"type":"array","items":{"type":"string"}},"summary":{"type":["string","null"]},"attackTechniques":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]}},"malware":{"type":"array","items":{"type":"string"}},"actors":{"type":"array","items":{"type":"string"}},"platforms":{"type":"array","items":{"type":"string"}},"affectedProducts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"versions":{"type":"array","items":{"type":"string"}}},"required":["name","versions"]}},"eventFirstSeen":{"type":["string","null"]},"eventLastSeen":{"type":["string","null"]}},"required":["id","title","publisher","url","publishedAt","tldr","attackPath"]}},"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]}},"activeHuntAlert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]},"latestAlert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Internal alert identifier"},"displayId":{"type":"string","pattern":"^COT-\\d+$","description":"Human-readable alert identifier"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns the alert"},"organizationName":{"type":"string","minLength":1,"description":"URL-safe organization name used in durable alert paths"},"title":{"type":"string","minLength":1,"description":"Human-readable alert title"},"description":{"type":["string","null"],"description":"Markdown summary or details for the alert"},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null],"description":"Alert severity when known"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"duplicateOfAlertId":{"type":["string","null"],"format":"uuid","description":"Canonical alert this alert duplicates, when status is duplicate"},"duplicateCount":{"type":"integer","minimum":0,"description":"Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring."},"source":{"type":"object","properties":{"category":{"type":"string","enum":["detection","trigger","hunt","api","agent"],"description":"Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent."},"name":{"type":"string","enum":["cotool_detection","cotool_code","hunt","api","agent","jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"Filter-oriented alert source name. Trigger-created alerts use the trigger type."},"triggerType":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source when category is trigger"}},"required":["category","name","triggerType"],"description":"Filter-oriented source attribution for an alert."},"detection":{"type":["object","null"],"properties":{"id":{"type":["string","null"],"format":"uuid","description":"Cotool detection identifier when known"},"agentId":{"type":["string","null"],"format":"uuid","description":"Cotool detection agent identifier when known"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection identifier when this alert came from Code Mode"},"ruleId":{"type":["string","null"],"format":"uuid","description":"Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule"},"name":{"type":"string","minLength":1,"description":"Detection display name"},"kind":{"type":"string","enum":["cotool","cotool_code","external"],"description":"Whether this detection attribution is internal or extracted"},"origin":{"type":["string","null"],"enum":["user","orchestrator",null],"description":"Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature."}},"required":["id","agentId","ruleId","name","kind"],"description":"Detection attribution for the alert, when known."},"createdBy":{"type":"string","enum":["agent","trigger","system"],"description":"Actor class that created the alert."},"originAgentId":{"type":["string","null"],"format":"uuid","description":"Agent that produced or owns the source flow"},"originTriggerId":{"type":["string","null"],"format":"uuid","description":"Trigger that created this alert, when source is an external trigger"},"originRunId":{"type":["string","null"],"format":"uuid","description":"Run that minted the alert, stored as chats.id"},"originDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Detection hit that produced this alert, when applicable"},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection that produced this alert, when applicable"},"originCodeDetectionHitId":{"type":["string","null"],"format":"uuid","description":"Code-detection hit that produced this alert, when applicable"},"externalProvider":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"External trigger provider such as jira, linear, email, or webhook"},"externalRef":{"type":["string","null"],"description":"Provider-native event, ticket, message, or alert identifier"},"externalUrl":{"type":["string","null"],"format":"uri","description":"Provider-native URL for the originating object"},"assignedAgentId":{"type":["string","null"],"format":"uuid","description":"Response agent currently assigned to triage this alert"},"triageRunId":{"type":["string","null"],"format":"uuid","description":"Latest response-agent triage run for this alert, stored as chats.id"},"dedupeKey":{"type":["string","null"],"description":"Stable key used for idempotent alert creation"},"createdAt":{"type":"string","description":"ISO timestamp when the alert was created"},"updatedAt":{"type":"string","description":"ISO timestamp when the alert was last updated"},"firstTriagedAt":{"type":["string","null"],"description":"ISO timestamp when triage first started"},"resolvedAt":{"type":["string","null"],"description":"ISO timestamp when the alert reached a terminal closed status"},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Disposition derived from terminal alert status"},"originAgentName":{"type":["string","null"],"description":"Display name for the origin agent, when available"},"assignedAgentName":{"type":["string","null"],"description":"Display name for the assigned triage agent, when available"},"triggerSource":{"type":["string","null"],"enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace",null],"description":"Trigger source for external-trigger alerts"},"resolvedByType":{"type":["string","null"],"enum":["human","agent","system",null],"description":"Actor class that moved the alert to its terminal status. Null while the alert is not closed."},"resolvedByUserId":{"type":["string","null"],"format":"uuid","description":"User who closed the alert, when a human closed it"},"resolvedByAgentName":{"type":["string","null"],"description":"Display name of the agent that closed the alert, when an agent closed it"},"resolvedReason":{"type":["string","null"],"description":"Reason recorded with the closing status change, when provided"},"huntQualifiedBy":{"type":["string","null"],"enum":["compromise_signal_found","exposure_found",null],"description":"Qualifying condition that opened this Hunt alert. Null for non-hunt alerts."}},"required":["id","displayId","organizationId","organizationName","title","description","severity","status","duplicateCount","source","detection","createdBy","originAgentId","originTriggerId","originRunId","originDetectionHitId","codeDetectionId","originCodeDetectionHitId","externalProvider","externalRef","externalUrl","assignedAgentId","triageRunId","dedupeKey","createdAt","updatedAt","firstTriagedAt","resolvedAt","derivedDisposition","originAgentName","assignedAgentName","triggerSource"]},"activityEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"threatId":{"type":"string"},"kind":{"type":"string","enum":["threat_created","intel_attached","reassessment_requested","assessment_started","relevancy_completed","exposure_started","assessment_failed"]},"actorType":{"type":"string","enum":["system","agent","human"]},"runId":{"type":["string","null"]},"metadata":{"type":["object","null"],"properties":{"score":{"type":"number"},"hunting":{"type":"boolean"},"executionId":{"type":"string"},"canonicalKey":{"type":"string"},"label":{"type":"string"},"userId":{"type":"string"}}},"createdAt":{"type":"string"}},"required":["id","threatId","kind","actorType","runId","metadata","createdAt"]}},"capabilities":{"type":"object","properties":{"canReadEvidence":{"type":"boolean"},"canReassess":{"type":"boolean"},"canTriage":{"type":"boolean"}},"required":["canReadEvidence","canReassess","canTriage"]}},"required":["threat","runs","deliverables","intelItems","alerts","activeHuntAlert","latestAlert","activityEvents"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Caller lacks the alert.triage permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/hunt/gaps/{gapId}/status":{"post":{"summary":"Dispose an observability gap","description":"Resolve or dismiss an org-level observability gap once, for every threat it affects. Resolving a blocking gap enqueues a reassessment for each linked threat whose hunt it blocked.","tags":["Hunt"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/hunt/gaps/:gapId/status\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"status\":\"resolved\",\"reason\":\"string\"}'"}],"parameters":[{"in":"path","name":"gapId","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["resolved","dismissed"]},"reason":{"type":"string"}},"required":["status"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"gap":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"product":{"type":"string"},"logSource":{"type":"string"},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"]},"scopeId":{"type":["string","null"]},"scopeKey":{"type":"string"},"blocking":{"type":"boolean"},"status":{"type":"string","enum":["open","resolved","dismissed"]},"establishedAt":{"type":"string"},"statusAt":{"type":["string","null"]},"statusActor":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"agent"},"runId":{"type":"string"}},"required":["type","runId"]},{"type":"object","properties":{"type":{"type":"string","const":"human"},"userId":{"type":"string"}},"required":["type","userId"]},{"type":"null"}]},"statusReason":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","product","logSource","scopeType","scopeId","scopeKey","blocking","status","establishedAt","statusAt","statusActor","statusReason","createdAt","updatedAt"]},"linkedThreats":{"type":"array","items":{"type":"object","properties":{"threatId":{"type":"string"},"threatTitle":{"type":"string"},"canonicalKey":{"type":"string"},"blocking":{"type":"boolean"}},"required":["threatId","threatTitle","canonicalKey","blocking"]}},"reassessedThreatIds":{"type":"array","items":{"type":"string"}}},"required":["gap","linkedThreats","reassessedThreatIds"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Caller lacks the alert.triage permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Gap not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/clis/list":{"get":{"summary":"List CLI integrations","description":"Return a grouped list of CLI integrations available to the organization.","tags":["CLIs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/clis/list\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"clis":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["siem","endpoint","identity","cloud","code","network","email","threat-intel","vulnerability","ticketing","incident-response","documentation","workspace","hr","automation","other"]},"authType":{"type":"string","enum":["oauth","apiKey","none"]},"isAuthenticated":{"type":"boolean"},"isCotoolEnabled":{"type":"boolean"},"isUserEnabled":{"type":"boolean"},"authenticatedAs":{"type":"string"}},"required":["type","name","description","authType","isAuthenticated","isCotoolEnabled","isUserEnabled"]}}},"required":["clis"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/clis/{cliType}/disconnect":{"delete":{"summary":"Disconnect CLI","description":"Remove stored credentials for a CLI integration.","tags":["CLIs"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X DELETE \"https://app.cotool.ai/api/clis/:cliType/disconnect\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"cliType","description":"Type identifier of the CLI integration","schema":{"type":"string","description":"Type identifier of the CLI integration"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/detection-queries/generate":{"post":{"summary":"Generate a SIEM query using AI","description":"> ⚠️ **Deprecated**\n> Standalone query generation is superseded by detection authoring with agents. Run an agent that has your SIEM tool attached (POST /api/agents/{agentId}/run-sync) or author detections in the Cotool app. No sunset is scheduled; the endpoint will be removed once its remaining integration retires.\n> **Use instead:** `/api/agents/:agentId/run-sync`\n\nGenerates a SIEM query based on a natural language prompt using AI.","tags":["Detections"],"deprecated":true,"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/detection-queries/generate\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\":\"string\",\"siemType\":\"splunk\",\"category\":\"baseline_anomaly\"}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"description":"Natural language description of what the query should accomplish"},"siemType":{"type":"string","enum":["splunk","sumologic","elastic","databricks","datadog","scanner","runreveal","microsoftsentinel","cotool","sentinelone","gadmin"],"description":"The detection tool platform to generate the query for (SIEM or endpoint tools like SentinelOne)"},"category":{"type":"string","enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom"],"description":"The detection category to optimize the query for"}},"required":["prompt","siemType"],"description":"Request body for generating a detection query using AI"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"The generated SIEM query"},"systemPrompt":{"type":"string","description":"The customized system prompt for the detection agent"},"explanation":{"type":"string","description":"Optional explanation of what the query does"}},"required":["query","systemPrompt"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/detections":{"get":{"summary":"List detections","description":"Retrieve all detections for the current organization.","tags":["Detections"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/detections\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"detections":{"type":"array","items":{"allOf":[{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":true,"description":"Whether this agent is built in to the system (true for built-in (system-managed) agents)"},"builtInAgentType":{"type":"string","enum":["threat-relevancy","threat-research","autonomous-hunt","code-detection-tuner","test-agent"],"description":"Type of built-in agent (e.g., threat-validation, threat-hunt)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn","builtInAgentType"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this agent"},"name":{"type":"string","description":"Human-readable name of the agent"},"description":{"type":"string","description":"Description of what the agent does and its purpose"},"systemPrompt":{"type":"string","description":"The agent's live system prompt (version history lives in agent_versions)"},"createdAt":{"type":"string","description":"Timestamp when the agent was created"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the agent was soft-deleted, or null if not deleted"},"invocationCount":{"type":"integer","minimum":0,"description":"All-time number of top-level invocations of this agent"},"invocationCount30d":{"type":"integer","minimum":0,"description":"Number of top-level invocations of this agent in the last 30 days"},"lastInvokedAt":{"type":["string","null"],"description":"Timestamp of the most recent top-level invocation, or null if the agent has never been invoked"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Array of tool names that this agent can use during execution"},"toolSelectionMode":{"type":"string","enum":["manual","all_read_only"],"description":"How this agent resolves tools at runtime"},"cliNames":{"type":"array","items":{"type":"string"},"description":"Optional array of CLI integration ids that this agent can use during execution"},"toolActionConfigs":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"slack_sendMessage"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_replyToThread"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readChannelMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_readThreadMessages"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"}},"required":["type","allowedChannels"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"slack_waitForUserResponse"},"allowedChannels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Slack channel ID (for example C123ABC456)"},"name":{"type":"string","minLength":1,"description":"Slack channel name without the leading #"}},"required":["id","name"],"additionalProperties":false},"minItems":1,"description":"Allowlist of Slack channels this agent may access when using this tool action"},"hideAgentButton":{"type":"boolean","description":"When true, omits the \"Open Agent Run in Cotool\" button from Slack messages produced by this tool action. Defaults to false (button is shown)."},"timeout":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"description":"Number of units to wait before an unanswered prompt times out."},"unit":{"type":"string","enum":["minutes","hours","days"],"description":"Unit for the timeout amount."}},"required":["amount","unit"],"additionalProperties":false,"description":"Optional fixed timeout for unanswered prompts. When omitted, the agent decides how long to wait via the tool input (and waits indefinitely if it specifies nothing)."}},"required":["type"],"additionalProperties":false}],"description":"Configuration for a specific tool action"},"description":"Per-tool-action configuration for this agent"},"inputs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","pdf","audio","video"],"description":"The type of input expected by the agent"},"name":{"type":"string","description":"The name of the input field"},"description":{"type":"string","description":"A description of what this input is used for"},"required":{"type":"boolean","description":"Whether this input is required for agent execution"}},"required":["type","name","description","required"]},"description":"Array of input configurations defining what inputs the agent expects"},"modelAlias":{"description":"Model alias specifying which LLM model to use for this agent"},"contextDocs":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["googleDocs","notion","confluence","mcp"]},"id":{"type":"string"},"name":{"type":"string"},"mimeType":{"type":"string"}},"required":["provider","id","name"]},"description":"Optional array of context documents (e.g., Google Docs, Notion pages) to provide to the agent"},"tinesStoryImportId":{"type":["string","null"],"description":"Optional reference to the Tines story import template used to create this agent"},"triggerSummary":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trigger"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"],"description":"The source platform or system that triggers the agent"},"name":{"type":"string","description":"Human-readable name for the trigger"},"enabled":{"type":"boolean","description":"Whether the trigger is currently enabled"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Whether this event runs the agent directly or creates an alert first"},"createsAlert":{"type":"boolean","description":"Legacy compatibility projection of eventMode"}},"required":["id","source","name","enabled"]},"description":"Optional array of triggers configured for this agent"},"planningMode":{"type":"string","enum":["auto","never","always"],"description":"Planning behavior mode for the agent"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"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":{"type":"boolean","description":"Whether this agent may use persistent workspace"},"createAlertsForApiRuns":{"type":"boolean","description":"Legacy compatibility setting: whether direct public API runs create alerts from the same run (new agents default to false)"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100,"description":"A tag label for categorizing agents (normalized to lowercase)"},"description":"Array of tags for categorizing the agent"},"skills":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","format":"uuid","description":"Unique identifier of an attached skill"},"skillVersionId":{"type":["string","null"],"format":"uuid","description":"Pinned version ID, or null/undefined to track latest"},"invocationCount30d":{"type":"number","description":"Distinct chats for this agent in the last 30 days where the skill was read from the sandbox"},"skill":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Skill description"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tool types for this skill"}},"required":["name","description","requiredTools"],"description":"Skill metadata snapshot"}},"required":["skillId","skill"]},"description":"Array of reusable skills attached to this agent"},"acceptanceCriteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500,"description":"A user-configured acceptance criterion that must be satisfied for an agent run"},"maxItems":20,"description":"Optional list of acceptance criteria evaluated for every run"},"agentType":{"type":"string","enum":["response","detection"],"description":"Type of agent: response (standard) or detection (security detection)"},"slackReplyScope":{"type":["string","null"],"enum":["anyone","cotool_users",null],"description":"Default Slack reply scope for chats not started by a Slack trigger (null/absent → cotool_users)"},"origin":{"type":"string","enum":["user","orchestrator"],"description":"Who created this agent: user or orchestrator"},"syncKey":{"type":["string","null"],"description":"Stable logical key for the agent (slug, immutable, unique per org)"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this agent (e.g. \"github\"); null/absent when UI-managed"},"syncFilePath":{"type":["string","null"],"description":"Path of the source YAML file for a GitOps-managed agent"},"syncConfigId":{"type":["string","null"],"description":"Which agent_sync_config (repo source) materialized this managed agent; null when UI-managed"},"detectionCategory":{"type":["string","null"],"enum":["baseline_anomaly","first_occurrence","sequence_pattern","privilege_escalation","custom",null],"description":"Category of detection (only for detection agents)"},"detectionQuery":{"type":["string","null"],"description":"The SIEM query for the detection (only for detection agents)"},"siemType":{"type":["string","null"],"description":"The SIEM platform type (e.g., splunk, elastic) for the detection (only for detection agents)"},"isSuggestion":{"type":"boolean","description":"Whether this detection is a suggestion (only for detection agents)"},"lastDetectionRunAt":{"type":["string","null"],"description":"Timestamp of when this detection was last run (only for detection agents)"},"legacyDetection":{"type":"boolean","description":"Client-side marker for a migrated legacy customer detection remapped to a unified agent"},"isBuiltIn":{"type":"boolean","const":false,"description":"Whether this agent is built in to the system (false for custom (user-created) agents)"}},"required":["id","organizationId","name","description","systemPrompt","createdAt","updatedAt","deletedAt","toolNames","toolSelectionMode","toolActionConfigs","inputs","modelAlias","planningMode","agentType","origin","isBuiltIn"]}],"description":"Agent configuration - can be either a built in (system-managed) or custom (user-created) agent"},{"type":"object","properties":{"persistentWorkspaceEnabled":{"type":"boolean","description":"Whether this detection may use persistent workspace"},"activeSystemPrompt":{"type":"object","properties":{"agentVersionId":{"type":"string","description":"Head agent_versions id for the live prompt"},"prompt":{"type":"string","description":"The system prompt text"},"description":{"type":"string","description":"Description of this prompt version"}},"required":["agentVersionId","prompt","description"],"description":"The currently active system prompt for this detection"},"cronSchedule":{"type":["string","null"],"description":"The cron schedule expression from the trigger (e.g., \"0 * * * *\" for hourly). Use cronToCadence() to derive display cadence."},"enabled":{"type":"boolean","description":"Whether the detection schedule is enabled (from cron trigger)"},"runs30d":{"type":"integer","description":"Total runs in last 30 days"},"runningRuns30d":{"type":"integer","description":"Total active runs in last 30 days"},"hits30d":{"type":"integer","description":"Recorded detection hits in last 30 days"},"avgEvalScore30d":{"type":["number","null"],"description":"Average LLM judge evaluation score (0-100) over last 30 days"},"threatModelSnippet":{"type":["string","null"],"description":"Verbatim quote from the threat model version this agent was grounded in. Powers the \"Why this agent?\" drawer. Null for user-created agents."},"threatModelVersion":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"ID of the threat model version this agent was grounded in"},"version":{"type":"integer","exclusiveMinimum":0,"description":"Monotonic version number of that TM version"},"isCurrent":{"type":"boolean","description":"Whether that TM version is still the current one. False means the TM has since been regenerated."}},"required":["id","version","isCurrent"],"description":"Threat model version this orchestrator agent was built against. Null for user-created agents."}},"required":["cronSchedule","enabled"]}]},"description":"Array of detection agents"},"threatModel":{"type":["object","null"],"properties":{"versionId":{"type":"string","format":"uuid","description":"ID of the current threat model version"},"version":{"type":"integer","exclusiveMinimum":0,"description":"Monotonic version number"},"createdAt":{"type":"string","description":"When the current version was created"},"hasContent":{"type":"boolean","description":"Whether the TM has been generated for this organization"},"content":{"type":"string","description":"Full markdown content of the current TM version (empty string if none generated yet). Used by the Auto Detect section to render an in-page preview and inline-highlight objective snippets."}},"required":["versionId","version","createdAt","hasContent","content"],"description":"Current threat model summary. Provided here so the Detections page can render the TM preview inline alongside Auto Detect agents without a second round-trip."}},"required":["detections"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/detections/hits":{"get":{"summary":"List detection hits","description":"Retrieve a flattened hit feed across all detections in the current organization. Pass `detectionId` to restrict the feed (and its aggregate summary) to a single detection — used by the detection-agent detail page to surface verifier evidence + cited tool calls without leaving the page. Uses a single batch query instead of N concurrent queries per detection.","tags":["Detections"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/detections/hits\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"limit","description":"Maximum number of hits to return per page (1-200, default: 100)","schema":{"type":"integer","minimum":1,"maximum":200,"default":100,"description":"Maximum number of hits to return per page (1-200, default: 100)"}},{"in":"query","name":"offset","description":"Number of hits to skip for pagination (default: 0)","schema":{"type":"integer","minimum":0,"default":0,"description":"Number of hits to skip for pagination (default: 0)"}},{"in":"query","name":"detectionId","description":"Restrict the feed to hits produced by a single detection agent. When omitted, returns hits across all accessible detections.","schema":{"type":"string","format":"uuid","description":"Restrict the feed to hits produced by a single detection agent. When omitted, returns hits across all accessible detections."}},{"in":"query","name":"severityFilter","description":"Comma-separated severities to include, such as \"high,critical\". When omitted, returns all severities.","schema":{"type":"string","description":"Comma-separated severities to include, such as \"high,critical\". When omitted, returns all severities."}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"detectionId":{"type":"string","format":"uuid"},"detectionName":{"type":"string"},"detectionDescription":{"type":["string","null"]},"detectionCategory":{"type":["string","null"]},"detectionIsBuiltIn":{"type":"boolean"},"detectionSiemType":{"type":["string","null"]},"runId":{"type":"string","format":"uuid"},"runTitle":{"type":"string"},"runCreatedAt":{"type":"string"},"hitCreatedAt":{"type":"string","description":"When this hit was recorded"},"isAutonomousHuntHit":{"type":"boolean","description":"Whether this hit was recorded by the autonomous hunt orchestrator"},"status":{"type":"string","enum":["open","dismissed_fp","dismissed_tpb","resolved_tp","dismissed_old"]},"statusHistory":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","enum":["open","dismissed_fp","dismissed_tpb","resolved_tp","dismissed_old"],"description":"Status after this transition"},"at":{"type":"string","format":"date-time","description":"ISO timestamp when the status transition occurred"},"by":{"type":["string","null"],"format":"uuid","description":"User who made the transition, or null for system-created entries"},"reason":{"type":"string","description":"Optional reason or note for the transition"}},"required":["status","at","by"]}},"entityType":{"type":["string","null"]},"confidence":{"type":["number","null"]},"evidence":{"type":"array","items":{"type":"string"}},"summary":{"type":["string","null"]},"headline":{"type":["string","null"]},"cta":{"type":["string","null"]},"statistics":{"type":"array","items":{"type":"string"}},"severity":{"type":"string","enum":["low","medium","high","critical"]},"entity":{"type":"string"},"verifierEvidence":{"type":"array","items":{"type":"string"},"description":"Curated evidence bullets authored by the hit-evidence sub-agent. Each bullet may contain inline <cite id=\"<toolUseId>\">...</cite> spans pointing at the tool calls that established it. Omitted (or empty) when the sub-agent did not produce one."}},"required":["id","detectionId","detectionName","detectionDescription","detectionCategory","detectionIsBuiltIn","detectionSiemType","runId","runTitle","runCreatedAt","hitCreatedAt","isAutonomousHuntHit","entityType","confidence","evidence","summary","headline","cta","statistics","severity","entity"]}},"totalCount":{"type":"number","description":"Total number of hits across all detections (for pagination)"},"summary":{"type":"object","properties":{"uniqueDetections":{"type":"integer","minimum":0,"description":"Number of distinct detections represented by all matching hits"},"avgConfidence":{"type":"number","minimum":0,"description":"Average confidence across all matching hits with a numeric confidence value"},"hitsLast24h":{"type":"integer","minimum":0,"description":"Number of matching hits created in the last 24 hours"},"hitsOverTime":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"UTC date key in YYYY-MM-DD format"},"count":{"type":"integer","minimum":0}},"required":["date","count"]},"description":"Daily hit counts for the trailing 30 days (UTC)"},"severityCounts":{"type":"object","properties":{"critical":{"type":"integer","minimum":0},"high":{"type":"integer","minimum":0},"medium":{"type":"integer","minimum":0},"low":{"type":"integer","minimum":0}},"required":["critical","high","medium","low"],"description":"Severity distribution across all matching hits"}},"required":["uniqueDetections","avgConfidence","hitsLast24h","hitsOverTime","severityCounts"],"description":"Aggregate summary for all matching hits (returned on initial page load)"}},"required":["hits","totalCount"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/output-destinations":{"get":{"summary":"List all output destinations","description":"List all output destinations for the organization.","tags":["Output Destinations"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/output-destinations\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"webhook"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication: \"bearer\" for Authorization: Bearer <token>, \"header\" for custom header"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\" (e.g., \"X-API-Key\")"}},"required":["url","authType"]},"token":{"type":"string","description":"The authentication token (only returned to authorized users)"},"hasToken":{"type":"boolean","description":"Whether a token is configured"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"teams"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["url"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"slack"},"config":{"type":"object","properties":{"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"},"configurationRevision":{"type":"integer","minimum":0,"description":"Revision of user-managed Slack delivery configuration"},"blockedChannels":{"type":"object","additionalProperties":{"type":"object","properties":{"reason":{"type":"string","const":"archived","description":"Why delivery to this Slack channel is blocked"},"blockedAt":{"type":"string","description":"When Slack reported that the channel was archived"}},"required":["reason","blockedAt"]},"description":"Channels that delivery will skip until a user updates the destination"}},"required":["channelIds"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"pagerduty"},"config":{"type":"object","properties":{"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts"},"source":{"type":"string","description":"Optional source identifier (defaults to detection name)"}},"required":["severity"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"linear"},"config":{"type":"object","properties":{"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names for display purposes"},"workflowStateId":{"type":"string","minLength":1,"description":"Linear workflow state ID for created issues"},"workflowStateName":{"type":"string","description":"Cached Linear workflow state name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"tines"},"config":{"type":"object","properties":{"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]}]}}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create output destination","description":"Create a new output destination (webhook, Teams, Slack, PagerDuty, Linear, or Tines) for the organization.","tags":["Output Destinations"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/output-destinations\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\",\"url\":\"string\",\"authType\":\"bearer\",\"headerName\":\"string\",\"token\":\"string\",\"type\":\"webhook\"}'"}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\""},"token":{"type":"string","description":"The authentication token"},"type":{"type":"string","const":"webhook"}},"required":["name","url","authType","type"]},{"type":"object","properties":{"type":{"type":"string","const":"teams","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["type","name","url"]},{"type":"object","properties":{"type":{"type":"string","const":"slack","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"}},"required":["type","name","channelIds"]},{"type":"object","properties":{"type":{"type":"string","const":"pagerduty","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts (defaults to warning)"},"source":{"type":"string","description":"Optional source identifier (defaults to detection name)"}},"required":["type","name"]},{"type":"object","properties":{"type":{"type":"string","const":"linear","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name (for display)"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names (for display)"},"workflowStateId":{"type":"string","minLength":1,"description":"Linear workflow state ID for created issues"},"workflowStateName":{"type":"string","description":"Cached Linear workflow state name (for display)"}},"required":["type","name","teamId"]},{"type":"object","properties":{"type":{"type":"string","const":"tines","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name (for display)"}},"required":["type","name","teamId"]}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"webhook"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication: \"bearer\" for Authorization: Bearer <token>, \"header\" for custom header"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\" (e.g., \"X-API-Key\")"}},"required":["url","authType"]},"token":{"type":"string","description":"The authentication token (only returned to authorized users)"},"hasToken":{"type":"boolean","description":"Whether a token is configured"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"teams"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["url"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"slack"},"config":{"type":"object","properties":{"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"},"configurationRevision":{"type":"integer","minimum":0,"description":"Revision of user-managed Slack delivery configuration"},"blockedChannels":{"type":"object","additionalProperties":{"type":"object","properties":{"reason":{"type":"string","const":"archived","description":"Why delivery to this Slack channel is blocked"},"blockedAt":{"type":"string","description":"When Slack reported that the channel was archived"}},"required":["reason","blockedAt"]},"description":"Channels that delivery will skip until a user updates the destination"}},"required":["channelIds"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"pagerduty"},"config":{"type":"object","properties":{"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts"},"source":{"type":"string","description":"Optional source identifier (defaults to detection name)"}},"required":["severity"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"linear"},"config":{"type":"object","properties":{"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names for display purposes"},"workflowStateId":{"type":"string","minLength":1,"description":"Linear workflow state ID for created issues"},"workflowStateName":{"type":"string","description":"Cached Linear workflow state name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"tines"},"config":{"type":"object","properties":{"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]}]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/output-destinations/{destinationId}":{"put":{"summary":"Update output destination","description":"Update an existing output destination (webhook, Teams, Slack, PagerDuty, Linear, or Tines).","tags":["Output Destinations"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/output-destinations/:destinationId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\",\"url\":\"string\",\"authType\":\"bearer\",\"headerName\":\"string\",\"token\":\"string\",\"type\":\"webhook\"}'"}],"parameters":[{"in":"path","name":"destinationId","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\""},"token":{"type":"string","description":"The authentication token (leave undefined to keep existing)"},"type":{"type":"string","const":"webhook"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"teams","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"slack","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"pagerduty","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts"},"source":{"type":"string","description":"Optional source identifier"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"linear","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name (for display)"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues; an empty array clears labels"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names (for display)"},"workflowStateId":{"type":["string","null"],"minLength":1,"description":"Linear workflow state ID for created issues; null clears the configured state"},"workflowStateName":{"type":["string","null"],"description":"Cached Linear workflow state name (for display); null clears the cached name"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"tines","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name (for display)"}},"required":["type"]}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"webhook"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication: \"bearer\" for Authorization: Bearer <token>, \"header\" for custom header"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\" (e.g., \"X-API-Key\")"}},"required":["url","authType"]},"token":{"type":"string","description":"The authentication token (only returned to authorized users)"},"hasToken":{"type":"boolean","description":"Whether a token is configured"},"usageCount":{"type":"number","description":"Number of detections using this destination"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config","usageCount"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"teams"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["url"]},"usageCount":{"type":"number","description":"Number of detections using this destination"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config","usageCount"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"slack"},"config":{"type":"object","properties":{"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"},"configurationRevision":{"type":"integer","minimum":0,"description":"Revision of user-managed Slack delivery configuration"},"blockedChannels":{"type":"object","additionalProperties":{"type":"object","properties":{"reason":{"type":"string","const":"archived","description":"Why delivery to this Slack channel is blocked"},"blockedAt":{"type":"string","description":"When Slack reported that the channel was archived"}},"required":["reason","blockedAt"]},"description":"Channels that delivery will skip until a user updates the destination"}},"required":["channelIds"]},"usageCount":{"type":"number","description":"Number of detections using this destination"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config","usageCount"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"pagerduty"},"config":{"type":"object","properties":{"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts"},"source":{"type":"string","description":"Optional source identifier (defaults to detection name)"}},"required":["severity"]},"usageCount":{"type":"number","description":"Number of detections using this destination"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config","usageCount"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"linear"},"config":{"type":"object","properties":{"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names for display purposes"},"workflowStateId":{"type":"string","minLength":1,"description":"Linear workflow state ID for created issues"},"workflowStateName":{"type":"string","description":"Cached Linear workflow state name for display purposes"}},"required":["teamId"]},"usageCount":{"type":"number","description":"Number of detections using this destination"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config","usageCount"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"tines"},"config":{"type":"object","properties":{"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"}},"required":["teamId"]},"usageCount":{"type":"number","description":"Number of detections using this destination"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config","usageCount"]}]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/output-destinations/{destinationId}/test":{"post":{"summary":"Send a test payload to an output destination","description":"Deliver an example payload to a single output destination so the configuration can be verified. The send is real and may create a message/incident/issue/case in the destination.","tags":["Output Destinations"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/output-destinations/:destinationId/test\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"outputType\":\"detection\",\"payload\":null,\"structuredOutputSchema\":null,\"agentName\":\"string\"}'"}],"parameters":[{"in":"path","name":"destinationId","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"outputType":{"type":"string","enum":["detection","response","acceptance-criteria","threat-intel","threat","hunt-alert","alert-escalation","code-detection-auto-tune"],"description":"The context the destination is configured in; determines the example payload shape and formatting"},"payload":{"$ref":"#/components/schemas/JsonValue","description":"The (possibly user-edited) example payload to send. For webhook it is the full envelope (POSTed verbatim); for the response context on non-webhook destinations it is just the structured output."},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"For the response context: the agent structured-output schema, so the test send formats the payload the same way the real delivery path does"},"agentName":{"type":"string","description":"For the response context on non-webhook destinations: the agent name shown in the message header"}},"required":["outputType","payload"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true,"description":"Whether the test output was delivered"},"destinationType":{"type":"string","enum":["webhook","teams","slack","pagerduty","linear","tines"],"description":"Type of destination the test was sent to"},"detail":{"type":"string","description":"Optional human-readable detail about the delivery (e.g. created issue identifier)"},"outputUrl":{"type":"string","format":"uri","description":"Direct URL to the created output when the destination provides one"},"outputLinkLabel":{"type":"string","description":"Human-readable label for the created output link"}},"required":["success","destinationType"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/output-destinations/test":{"post":{"summary":"Send a test payload to an unsaved output destination","description":"Deliver an example payload to a configured-but-unsaved output destination so it can be verified before creating it. The send is real and may create a message/incident/issue/case in the destination.","tags":["Output Destinations"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/output-destinations/test\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"outputType\":\"detection\",\"payload\":null,\"destination\":{\"name\":\"string\",\"url\":\"string\",\"authType\":\"bearer\",\"headerName\":\"string\",\"token\":\"string\",\"type\":\"webhook\"},\"existingDestinationId\":\"string\",\"structuredOutputSchema\":null,\"agentName\":\"string\"}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"outputType":{"type":"string","enum":["detection","response","acceptance-criteria","threat-intel","threat","hunt-alert","alert-escalation","code-detection-auto-tune"],"description":"The context the destination is configured in"},"payload":{"$ref":"#/components/schemas/JsonValue","description":"The (possibly user-edited) example payload envelope to send"},"destination":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\""},"token":{"type":"string","description":"The authentication token"},"type":{"type":"string","const":"webhook"}},"required":["name","url","authType","type"]},{"type":"object","properties":{"type":{"type":"string","const":"teams","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["type","name","url"]},{"type":"object","properties":{"type":{"type":"string","const":"slack","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"}},"required":["type","name","channelIds"]},{"type":"object","properties":{"type":{"type":"string","const":"pagerduty","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts (defaults to warning)"},"source":{"type":"string","description":"Optional source identifier (defaults to detection name)"}},"required":["type","name"]},{"type":"object","properties":{"type":{"type":"string","const":"linear","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name (for display)"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names (for display)"},"workflowStateId":{"type":"string","minLength":1,"description":"Linear workflow state ID for created issues"},"workflowStateName":{"type":"string","description":"Cached Linear workflow state name (for display)"}},"required":["type","name","teamId"]},{"type":"object","properties":{"type":{"type":"string","const":"tines","description":"Destination type"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name (for display)"}},"required":["type","name","teamId"]}],"description":"The unsaved destination configuration to test"},"existingDestinationId":{"type":"string","format":"uuid","description":"Existing destination being edited; used to preserve stored secrets when omitted from the unsaved config"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"For the response context: the agent structured-output schema, so the test send formats the payload the same way the real delivery path does"},"agentName":{"type":"string","description":"For the response context on non-webhook destinations: the agent name shown in the message header"}},"required":["outputType","payload","destination"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true,"description":"Whether the test output was delivered"},"destinationType":{"type":"string","enum":["webhook","teams","slack","pagerduty","linear","tines"],"description":"Type of destination the test was sent to"},"detail":{"type":"string","description":"Optional human-readable detail about the delivery (e.g. created issue identifier)"},"outputUrl":{"type":"string","format":"uri","description":"Direct URL to the created output when the destination provides one"},"outputLinkLabel":{"type":"string","description":"Human-readable label for the created output link"}},"required":["success","destinationType"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/roles":{"get":{"summary":"List roles for the current organization","description":"List all roles for the current organization","tags":["Roles"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/roles\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"roles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isSystemRole":{"type":"boolean"}},"required":["id","organizationId","name","description","createdAt","updatedAt","isSystemRole"]}}},"required":["roles"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a role","description":"Create a new role for the current organization","tags":["Roles"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/roles\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\",\"description\":\"string\"}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":"string"}},"required":["name"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isSystemRole":{"type":"boolean"}},"required":["id","organizationId","name","description","createdAt","updatedAt","isSystemRole"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/roles/{id}":{"put":{"summary":"Update a role","description":"Update an existing role for the current organization","tags":["Roles"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/roles/:id\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\",\"description\":\"string\"}'"}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isSystemRole":{"type":"boolean"}},"required":["id","organizationId","name","description","createdAt","updatedAt","isSystemRole"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a role","description":"Delete an existing role for the current organization","tags":["Roles"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X DELETE \"https://app.cotool.ai/api/roles/:id\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Get role by id","description":"Get a specific role by its ID","tags":["Roles"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/roles/:id\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isSystemRole":{"type":"boolean"}},"required":["id","organizationId","name","description","createdAt","updatedAt","isSystemRole"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/roles/{id}/perms":{"get":{"summary":"Get permissions for a role","description":"Get the permissions for a specific role","tags":["Roles"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/roles/:id/perms\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"perms":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"agent.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"detection.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"tool.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"cli.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"chat.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.triage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.perms.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.update"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.invite"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.delete"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.apiKey.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auditLog.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.customModel.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auth.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.tags.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.suggestions.manage"}},"required":["resource","action"]}]}}},"required":["perms"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Apply permission diff to a role","description":"Apply a permission diff to a specific role","tags":["Roles"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/roles/:id/perms\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"toAdd\":[{\"resource\":{\"type\":\"all\"},\"action\":\"agent.create\"}],\"toRemove\":[{\"resource\":{\"type\":\"all\"},\"action\":\"agent.create\"}]}'"}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"toAdd":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"agent.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"detection.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"tool.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"cli.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"chat.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.triage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.perms.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.update"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.invite"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.delete"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.apiKey.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auditLog.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.customModel.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auth.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.tags.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.suggestions.manage"}},"required":["resource","action"]}]}},"toRemove":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"agent.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"detection.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"tool.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"cli.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"chat.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.triage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.perms.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.update"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.invite"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.delete"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.apiKey.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auditLog.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.customModel.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auth.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.tags.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.suggestions.manage"}},"required":["resource","action"]}]}}},"required":["toAdd","toRemove"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"perms":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"agent.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"agent.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"detection.create"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.execute"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"detection.edit"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"tool.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"tool.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"specific"},"id":{"type":"string"}},"required":["type","id"]}]},"action":{"type":"string","const":"cli.use"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"cli.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"chat.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.triage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"alert.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.perms.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.update"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.invite"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.users.delete"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.apiKey.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auditLog.read"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.customModel.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.auth.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.tags.manage"}},"required":["resource","action"]},{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","const":"all"}},"required":["type"]},"action":{"type":"string","const":"setting.suggestions.manage"}},"required":["resource","action"]}]}}},"required":["perms"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mitre/matrix":{"get":{"summary":"Get MITRE ATT&CK matrix with detection coverage","description":"Retrieve the MITRE ATT&CK framework matrix showing detection rule coverage as a heatmap","tags":["MITRE Coverage"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/mitre/matrix\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"matrix":{"type":"object","properties":{"tactics":{"type":"array","items":{"type":"object","properties":{"tacticId":{"type":"string","description":"MITRE ATT&CK tactic ID (e.g., TA0001, TA0002)"},"tacticName":{"type":"string","description":"Human readable tactic name"},"description":{"type":"string","description":"Description of the tactic"},"shortName":{"type":"string","description":"Short name used in kill chain phases"},"techniqueIds":{"type":"array","items":{"type":"string"},"description":"Array of technique IDs in this tactic"},"url":{"type":"string","description":"URL to official MITRE page"},"detectionCount":{"type":"number","description":"Total number of detection rules for techniques in this tactic"},"averageConfidence":{"type":"number","minimum":0,"maximum":1,"description":"Average confidence across all techniques"},"rawData":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"x-mitre-tactic"},"name":{"type":"string"},"description":{"type":"string"},"external_references":{"type":"array","items":{"type":"object","properties":{"source_name":{"type":"string"},"external_id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"}},"required":["source_name"]}},"x_mitre_shortname":{"type":"string"},"x_mitre_version":{"type":"string"},"x_mitre_attack_spec_version":{"type":"string"},"x_mitre_domains":{"type":"array","items":{"type":"string"}},"created":{"type":"string"},"modified":{"type":"string"},"spec_version":{"type":"string"},"object_marking_refs":{"type":"array","items":{"type":"string"}}},"required":["id","type","name","description","x_mitre_shortname","created","modified"],"description":"Raw MITRE ATT&CK tactic data"}},"required":["tacticId","tacticName","description","shortName","techniqueIds","detectionCount"]},"description":"Array of MITRE tactics"},"techniques":{"type":"array","items":{"type":"object","properties":{"techniqueId":{"type":"string","description":"MITRE ATT&CK technique ID (e.g., T1003, T1059.001)"},"techniqueName":{"type":"string","description":"Human readable technique name"},"description":{"type":"string","description":"Description of the technique"},"tactics":{"type":"array","items":{"type":"string"},"description":"Array of tactic short names this technique belongs to"},"isSubtechnique":{"type":"boolean","description":"Whether this is a subtechnique"},"parentTechnique":{"type":"string","description":"Parent technique ID if this is a subtechnique"},"platforms":{"type":"array","items":{"type":"string"},"description":"Supported platforms"},"dataSources":{"type":"array","items":{"type":"string"},"description":"Data sources for detection"},"mitigations":{"type":"array","items":{"type":"string"},"description":"Related mitigation IDs"},"url":{"type":"string","description":"URL to official MITRE page"},"detectionCount":{"type":"number","description":"Number of detection rules mapped to this technique"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Average confidence score for this technique"},"detectionRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"source":{"type":"string","enum":["panther","sublime","scanner","datadog","splunk","sentinelone","microsoftsentinel","elastic","sumologic","runreveal","cotool"]},"confidence":{"type":"number","minimum":0,"maximum":1},"reasoning":{"type":"string"}},"required":["id","name","source","confidence","reasoning"]},"description":"Detection rules mapped to this technique"},"rawData":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"attack-pattern"},"name":{"type":"string"},"description":{"type":"string"},"external_references":{"type":"array","items":{"type":"object","properties":{"source_name":{"type":"string"},"external_id":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"}},"required":["source_name"]}},"kill_chain_phases":{"type":"array","items":{"type":"object","properties":{"kill_chain_name":{"type":"string"},"phase_name":{"type":"string"}},"required":["kill_chain_name","phase_name"]}},"x_mitre_version":{"type":"string"},"x_mitre_attack_spec_version":{"type":"string"},"x_mitre_domains":{"type":"array","items":{"type":"string"}},"x_mitre_is_subtechnique":{"type":"boolean"},"x_mitre_detection":{"type":"string"},"x_mitre_platforms":{"type":"array","items":{"type":"string"}},"x_mitre_data_sources":{"type":"array","items":{"type":"string"}},"aliases":{"type":"array","items":{"type":"string"}},"created":{"type":"string"},"modified":{"type":"string"},"spec_version":{"type":"string"},"object_marking_refs":{"type":"array","items":{"type":"string"}},"revoked":{"type":"boolean"},"x_mitre_deprecated":{"type":"boolean"}},"required":["id","type","name","description","created","modified"],"description":"Raw MITRE ATT&CK technique data"}},"required":["techniqueId","techniqueName","description","tactics","detectionCount","confidence","detectionRules"]},"description":"Array of MITRE techniques"},"matrixCells":{"type":"array","items":{"type":"object","properties":{"techniqueId":{"type":"string","description":"MITRE ATT&CK technique ID"},"techniqueName":{"type":"string","description":"Human readable technique name"},"tacticId":{"type":"string","description":"MITRE ATT&CK tactic ID"},"tacticName":{"type":"string","description":"Human readable tactic name"},"detectionCount":{"type":"number","description":"Number of detection rules for this technique"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Average confidence score"},"coverageLevel":{"type":"string","enum":["none","low","medium","high"],"description":"Coverage level for heatmap coloring"}},"required":["techniqueId","techniqueName","tacticId","tacticName","detectionCount","confidence","coverageLevel"]},"description":"Matrix cells for heatmap visualization"},"lastUpdated":{"type":"string","description":"When the matrix was last updated"},"totalDetectionRules":{"type":"number","description":"Total number of detection rules processed"},"organizationId":{"type":"string","description":"Organization ID this matrix belongs to"}},"required":["tactics","techniques","matrixCells","lastUpdated","totalDetectionRules","organizationId"],"description":"Complete MITRE ATT&CK matrix with detection coverage"}},"required":["matrix"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/users/organizations":{"get":{"summary":"List user organizations","description":"Retrieve all organizations that the current user has access to.","tags":["Users"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/users/organizations\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"organizations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the organization"},"name":{"type":"string","description":"Name of the organization"},"createdAt":{"type":"string","description":"When the organization was created","format":"date-time","example":"2025-06-17T12:34:56.789Z"},"updatedAt":{"type":"string","description":"When the organization was last updated","format":"date-time","example":"2025-06-17T12:34:56.789Z"}},"required":["id","name","createdAt","updatedAt"]},"description":"Array of organization records"},"count":{"type":"number","description":"Total number of organizations returned"}},"required":["organizations","count"],"description":"Response containing organizations and count information"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/org-metrics":{"get":{"summary":"Get organization-level activity metrics","description":"Returns summary counts and timeseries for agent runs, chats, and GitHub PR actions for the authenticated organization.","tags":["Organizations"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/org-metrics\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"range","description":"Time range for metrics (7d, 30d, all)","schema":{"type":"string","enum":["7d","30d","all"],"description":"Time range for metrics (7d, 30d, all)"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"agentRuns":{"type":"object","properties":{"last7Days":{"type":"number"},"last30Days":{"type":"number"},"allTime":{"type":"number"}},"required":["last7Days","last30Days","allTime"]},"chats":{"type":"object","properties":{"last7Days":{"type":"number"},"last30Days":{"type":"number"},"allTime":{"type":"number"}},"required":["last7Days","last30Days","allTime"]},"githubPullRequestsCreated":{"type":"object","properties":{"last7Days":{"type":"number"},"last30Days":{"type":"number"},"allTime":{"type":"number"}},"required":["last7Days","last30Days","allTime"]},"githubPullRequestsUpdated":{"type":"object","properties":{"last7Days":{"type":"number"},"last30Days":{"type":"number"},"allTime":{"type":"number"}},"required":["last7Days","last30Days","allTime"]},"linesOfCodeAdded":{"type":"object","properties":{"last7Days":{"type":"number"},"last30Days":{"type":"number"},"allTime":{"type":"number"}},"required":["last7Days","last30Days","allTime"]},"linesOfCodeRemoved":{"type":"object","properties":{"last7Days":{"type":"number"},"last30Days":{"type":"number"},"allTime":{"type":"number"}},"required":["last7Days","last30Days","allTime"]},"scannerQueries":{"type":"object","properties":{"last7Days":{"type":"number"},"last30Days":{"type":"number"},"allTime":{"type":"number"}},"required":["last7Days","last30Days","allTime"]},"datadogQueries":{"type":"object","properties":{"last7Days":{"type":"number"},"last30Days":{"type":"number"},"allTime":{"type":"number"}},"required":["last7Days","last30Days","allTime"]},"sentinelOneQueries":{"type":"object","properties":{"last7Days":{"type":"number"},"last30Days":{"type":"number"},"allTime":{"type":"number"}},"required":["last7Days","last30Days","allTime"]},"splunkQueries":{"type":"object","properties":{"last7Days":{"type":"number"},"last30Days":{"type":"number"},"allTime":{"type":"number"}},"required":["last7Days","last30Days","allTime"]},"pantherQueries":{"type":"object","properties":{"last7Days":{"type":"number"},"last30Days":{"type":"number"},"allTime":{"type":"number"}},"required":["last7Days","last30Days","allTime"]}},"required":["agentRuns","chats","githubPullRequestsCreated","githubPullRequestsUpdated","linesOfCodeAdded","linesOfCodeRemoved","scannerQueries","datadogQueries","sentinelOneQueries","splunkQueries","pantherQueries"]},"timeseries":{"type":"object","properties":{"agentRuns":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"chats":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"githubPullRequestsCreated":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"githubPullRequestsUpdated":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"linesOfCodeAdded":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"linesOfCodeRemoved":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"scannerQueries":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"datadogQueries":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"sentinelOneQueries":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"splunkQueries":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"pantherQueries":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}}},"required":["agentRuns","chats","githubPullRequestsCreated","githubPullRequestsUpdated","linesOfCodeAdded","linesOfCodeRemoved","scannerQueries","datadogQueries","sentinelOneQueries","splunkQueries","pantherQueries"]}},"required":["summary","timeseries"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/linear/agent-session":{"post":{"summary":"Create Linear agent session for an agent","description":"Creates a Linear Agent Session on an issue and routes the session and its follow-ups to the selected agent using the organization's enabled Linear trigger.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agents/:agentId/linear/agent-session\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"issueId\":\"string\",\"externalUrls\":[{\"label\":\"string\",\"url\":\"string\"}]}'"}],"parameters":[{"in":"path","name":"agentId","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"issueId":{"type":"string","minLength":1},"externalUrls":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"}},"required":["label","url"]}}},"required":["issueId"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"agentSessionId":{"type":"string"},"triggerId":{"type":"string"}},"required":["success","message"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/skills":{"get":{"summary":"List skills","description":"List all active skills in the organization.","tags":["Skills"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/skills\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the skill"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this skill"},"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Description of what this skill teaches an agent to do"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Optional required tool types for this skill"},"userId":{"type":["string","null"],"description":"User ID that owns this user-scoped skill, or null for organization skills"},"createdByUserId":{"type":["string","null"],"description":"User ID that created this skill, or null for system-created records"},"createdAt":{"type":"string","description":"Timestamp when the skill was created"},"updatedAt":{"type":"string","description":"Timestamp when the skill was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the skill was soft-deleted, or null if active"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this skill (e.g. \"github\") when it is GitOps-managed; null/absent when UI-managed"},"usedByAgentCount":{"type":"number","description":"How many agents currently use this skill"},"invocationCount30d":{"type":"number","description":"Distinct chats in the last 30 days where an agent read this skill from the sandbox"},"currentVersion":{"type":"number","description":"Current version number of this skill"}},"required":["id","organizationId","name","description","requiredTools","userId","createdByUserId","createdAt","updatedAt","deletedAt"]}}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create skill","description":"Create a reusable skill in the organization.","tags":["Skills"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/skills\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\",\"userId\":\"string\",\"description\":\"string\",\"instructionPrompt\":\"string\",\"requiredTools\":[\"string\"],\"references\":[{\"filename\":\"string\",\"directory\":\"references\",\"sizeBytes\":0,\"content\":\"string\"}]}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"userId":{"type":["string","null"],"format":"uuid","description":"User owner for user-scoped skills; null or omitted creates an organization skill"},"description":{"type":"string","minLength":1,"description":"Description of what this skill teaches an agent to do"},"instructionPrompt":{"type":"string","minLength":1,"description":"Primary instruction prompt content for this skill"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Optional required tool types for this skill"},"references":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Relative path from skill root"},"directory":{"type":"string","enum":["references","assets","scripts"],"description":"Top-level skill directory where this file resides"},"sizeBytes":{"type":"integer","minimum":0},"content":{"type":"string","description":"File content (empty string allowed)"}},"required":["filename","content"]},"description":"Optional references for initial version creation"}},"required":["name","description","instructionPrompt"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the skill"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this skill"},"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Description of what this skill teaches an agent to do"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Optional required tool types for this skill"},"userId":{"type":["string","null"],"description":"User ID that owns this user-scoped skill, or null for organization skills"},"createdByUserId":{"type":["string","null"],"description":"User ID that created this skill, or null for system-created records"},"createdAt":{"type":"string","description":"Timestamp when the skill was created"},"updatedAt":{"type":"string","description":"Timestamp when the skill was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the skill was soft-deleted, or null if active"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this skill (e.g. \"github\") when it is GitOps-managed; null/absent when UI-managed"},"usedByAgentCount":{"type":"number","description":"How many agents currently use this skill"},"invocationCount30d":{"type":"number","description":"Distinct chats in the last 30 days where an agent read this skill from the sandbox"},"currentVersion":{"type":"number","description":"Current version number of this skill"},"instructionPrompt":{"type":"string","description":"Primary instruction prompt content for this skill"},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the reference file record"},"skillVersionId":{"type":"string","format":"uuid","description":"Version ID this reference belongs to"},"filename":{"type":"string","description":"Relative path from skill root (for example references/guide.md)"},"directory":{"type":"string","enum":["references","assets","scripts"],"description":"Top-level skill directory where this file resides"},"sizeBytes":{"type":"integer","minimum":0,"description":"UTF-8 byte size of the file content"},"content":{"type":"string","description":"Optional file content (included in version detail / export flows)"},"createdAt":{"type":"string","description":"Timestamp when this file was stored"}},"required":["id","skillVersionId","filename","directory","sizeBytes"]},"description":"Resource files for the active/current version"}},"required":["id","organizationId","name","description","requiredTools","userId","createdByUserId","createdAt","updatedAt","deletedAt","instructionPrompt"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/skills/{skillId}":{"get":{"summary":"Get skill","description":"Get one active skill by ID.","tags":["Skills"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/skills/:skillId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"skillId","description":"Unique identifier for the skill","schema":{"type":"string","format":"uuid","description":"Unique identifier for the skill"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the skill"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this skill"},"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Description of what this skill teaches an agent to do"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Optional required tool types for this skill"},"userId":{"type":["string","null"],"description":"User ID that owns this user-scoped skill, or null for organization skills"},"createdByUserId":{"type":["string","null"],"description":"User ID that created this skill, or null for system-created records"},"createdAt":{"type":"string","description":"Timestamp when the skill was created"},"updatedAt":{"type":"string","description":"Timestamp when the skill was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the skill was soft-deleted, or null if active"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this skill (e.g. \"github\") when it is GitOps-managed; null/absent when UI-managed"},"usedByAgentCount":{"type":"number","description":"How many agents currently use this skill"},"invocationCount30d":{"type":"number","description":"Distinct chats in the last 30 days where an agent read this skill from the sandbox"},"currentVersion":{"type":"number","description":"Current version number of this skill"},"instructionPrompt":{"type":"string","description":"Primary instruction prompt content for this skill"},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the reference file record"},"skillVersionId":{"type":"string","format":"uuid","description":"Version ID this reference belongs to"},"filename":{"type":"string","description":"Relative path from skill root (for example references/guide.md)"},"directory":{"type":"string","enum":["references","assets","scripts"],"description":"Top-level skill directory where this file resides"},"sizeBytes":{"type":"integer","minimum":0,"description":"UTF-8 byte size of the file content"},"content":{"type":"string","description":"Optional file content (included in version detail / export flows)"},"createdAt":{"type":"string","description":"Timestamp when this file was stored"}},"required":["id","skillVersionId","filename","directory","sizeBytes"]},"description":"Resource files for the active/current version"}},"required":["id","organizationId","name","description","requiredTools","userId","createdByUserId","createdAt","updatedAt","deletedAt","instructionPrompt"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update skill","description":"Update an existing skill.","tags":["Skills"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/skills/:skillId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\",\"description\":\"string\",\"instructionPrompt\":\"string\",\"requiredTools\":[\"string\"],\"references\":[{\"filename\":\"string\",\"directory\":\"references\",\"sizeBytes\":0,\"content\":\"string\"}]}'"}],"parameters":[{"in":"path","name":"skillId","description":"Unique identifier for the skill","schema":{"type":"string","format":"uuid","description":"Unique identifier for the skill"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","minLength":1,"description":"Updated skill description"},"instructionPrompt":{"type":"string","minLength":1,"description":"Updated instruction prompt content"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Updated required tool types"},"references":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Relative path from skill root"},"directory":{"type":"string","enum":["references","assets","scripts"],"description":"Top-level skill directory where this file resides"},"sizeBytes":{"type":"integer","minimum":0},"content":{"type":"string","description":"File content (empty string allowed)"}},"required":["filename","content"]},"description":"Optional full replacement references for the new version"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the skill"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this skill"},"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Description of what this skill teaches an agent to do"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Optional required tool types for this skill"},"userId":{"type":["string","null"],"description":"User ID that owns this user-scoped skill, or null for organization skills"},"createdByUserId":{"type":["string","null"],"description":"User ID that created this skill, or null for system-created records"},"createdAt":{"type":"string","description":"Timestamp when the skill was created"},"updatedAt":{"type":"string","description":"Timestamp when the skill was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the skill was soft-deleted, or null if active"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this skill (e.g. \"github\") when it is GitOps-managed; null/absent when UI-managed"},"usedByAgentCount":{"type":"number","description":"How many agents currently use this skill"},"invocationCount30d":{"type":"number","description":"Distinct chats in the last 30 days where an agent read this skill from the sandbox"},"currentVersion":{"type":"number","description":"Current version number of this skill"},"instructionPrompt":{"type":"string","description":"Primary instruction prompt content for this skill"},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the reference file record"},"skillVersionId":{"type":"string","format":"uuid","description":"Version ID this reference belongs to"},"filename":{"type":"string","description":"Relative path from skill root (for example references/guide.md)"},"directory":{"type":"string","enum":["references","assets","scripts"],"description":"Top-level skill directory where this file resides"},"sizeBytes":{"type":"integer","minimum":0,"description":"UTF-8 byte size of the file content"},"content":{"type":"string","description":"Optional file content (included in version detail / export flows)"},"createdAt":{"type":"string","description":"Timestamp when this file was stored"}},"required":["id","skillVersionId","filename","directory","sizeBytes"]},"description":"Resource files for the active/current version"}},"required":["id","organizationId","name","description","requiredTools","userId","createdByUserId","createdAt","updatedAt","deletedAt","instructionPrompt"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete skill","description":"Soft delete a skill.","tags":["Skills"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X DELETE \"https://app.cotool.ai/api/skills/:skillId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"skillId","description":"Unique identifier for the skill","schema":{"type":"string","format":"uuid","description":"Unique identifier for the skill"},"required":true}],"responses":{"200":{"description":"Successful response - no content"},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/skills/{skillId}/agents":{"get":{"summary":"List agents using skill","description":"List all agents currently using this skill.","tags":["Skills"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/skills/:skillId/agents\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"skillId","description":"Unique identifier for the skill","schema":{"type":"string","format":"uuid","description":"Unique identifier for the skill"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the agent"},"name":{"type":"string","description":"Agent name"},"description":{"type":"string","description":"Agent description"},"agentType":{"type":"string","enum":["response","detection"],"description":"Agent type"},"updatedAt":{"type":"string","description":"Timestamp when the agent was last updated"},"invocationCount30d":{"type":"number","description":"How many times this skill was invoked by the agent in the last 30 days"}},"required":["id","name","description","agentType","updatedAt","invocationCount30d"]}}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/skills/{skillId}/versions":{"get":{"summary":"List skill versions","description":"List all versions for a skill in descending order.","tags":["Skills"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/skills/:skillId/versions\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"skillId","description":"Unique identifier for the skill","schema":{"type":"string","format":"uuid","description":"Unique identifier for the skill"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the skill version"},"skillId":{"type":"string","format":"uuid","description":"Parent skill ID"},"version":{"type":"integer","exclusiveMinimum":0,"description":"Monotonic version number for the skill"},"createdByUserId":{"type":["string","null"],"description":"User who created this version, if available"},"createdAt":{"type":"string","description":"Timestamp when this version was created"}},"required":["id","skillId","version","createdByUserId","createdAt"]}}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/skills/{skillId}/versions/{versionId}":{"get":{"summary":"Get skill version","description":"Get one specific skill version with references.","tags":["Skills"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/skills/:skillId/versions/:versionId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"skillId","description":"Unique identifier for the skill","schema":{"type":"string","format":"uuid","description":"Unique identifier for the skill"},"required":true},{"in":"path","name":"versionId","description":"Unique identifier for the skill version","schema":{"type":"string","format":"uuid","description":"Unique identifier for the skill version"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the skill version"},"skillId":{"type":"string","format":"uuid","description":"Parent skill ID"},"version":{"type":"integer","exclusiveMinimum":0,"description":"Monotonic version number for the skill"},"createdByUserId":{"type":["string","null"],"description":"User who created this version, if available"},"createdAt":{"type":"string","description":"Timestamp when this version was created"},"instructionPrompt":{"type":"string","description":"Instruction content for this specific version"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tools snapshot for this specific version"},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the reference file record"},"skillVersionId":{"type":"string","format":"uuid","description":"Version ID this reference belongs to"},"filename":{"type":"string","description":"Relative path from skill root (for example references/guide.md)"},"directory":{"type":"string","enum":["references","assets","scripts"],"description":"Top-level skill directory where this file resides"},"sizeBytes":{"type":"integer","minimum":0,"description":"UTF-8 byte size of the file content"},"content":{"type":"string","description":"Optional file content (included in version detail / export flows)"},"createdAt":{"type":"string","description":"Timestamp when this file was stored"}},"required":["id","skillVersionId","filename","directory","sizeBytes"]},"description":"References attached to this specific version"}},"required":["id","skillId","version","createdByUserId","createdAt","instructionPrompt","requiredTools","references"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/skills/{skillId}/versions/{versionId}/restore":{"post":{"summary":"Restore a skill version","description":"Restore a previous skill snapshot as a new current version.","tags":["Skills"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/skills/:skillId/versions/:versionId/restore\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"skillId","description":"Unique identifier for the skill","schema":{"type":"string","format":"uuid","description":"Unique identifier for the skill"},"required":true},{"in":"path","name":"versionId","description":"Unique identifier for the skill version","schema":{"type":"string","format":"uuid","description":"Unique identifier for the skill version"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the skill"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this skill"},"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Description of what this skill teaches an agent to do"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Optional required tool types for this skill"},"userId":{"type":["string","null"],"description":"User ID that owns this user-scoped skill, or null for organization skills"},"createdByUserId":{"type":["string","null"],"description":"User ID that created this skill, or null for system-created records"},"createdAt":{"type":"string","description":"Timestamp when the skill was created"},"updatedAt":{"type":"string","description":"Timestamp when the skill was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the skill was soft-deleted, or null if active"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this skill (e.g. \"github\") when it is GitOps-managed; null/absent when UI-managed"},"usedByAgentCount":{"type":"number","description":"How many agents currently use this skill"},"invocationCount30d":{"type":"number","description":"Distinct chats in the last 30 days where an agent read this skill from the sandbox"},"currentVersion":{"type":"number","description":"Current version number of this skill"},"instructionPrompt":{"type":"string","description":"Primary instruction prompt content for this skill"},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the reference file record"},"skillVersionId":{"type":"string","format":"uuid","description":"Version ID this reference belongs to"},"filename":{"type":"string","description":"Relative path from skill root (for example references/guide.md)"},"directory":{"type":"string","enum":["references","assets","scripts"],"description":"Top-level skill directory where this file resides"},"sizeBytes":{"type":"integer","minimum":0,"description":"UTF-8 byte size of the file content"},"content":{"type":"string","description":"Optional file content (included in version detail / export flows)"},"createdAt":{"type":"string","description":"Timestamp when this file was stored"}},"required":["id","skillVersionId","filename","directory","sizeBytes"]},"description":"Resource files for the active/current version"}},"required":["id","organizationId","name","description","requiredTools","userId","createdByUserId","createdAt","updatedAt","deletedAt","instructionPrompt"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/skills/import":{"post":{"summary":"Import skill","description":"Import a skill package payload and create the skill.","tags":["Skills"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/skills/import\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\",\"userId\":\"string\",\"description\":\"string\",\"instructionPrompt\":\"string\",\"requiredTools\":[\"string\"],\"references\":[{\"filename\":\"string\",\"directory\":\"references\",\"sizeBytes\":0,\"content\":\"string\"}]}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"userId":{"type":["string","null"],"format":"uuid","description":"User owner for user-scoped skills; null or omitted creates an organization skill"},"description":{"type":"string","minLength":1,"description":"Description of what this skill teaches an agent to do"},"instructionPrompt":{"type":"string","minLength":1,"description":"Primary instruction prompt content for this skill"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Optional required tool types for this skill"},"references":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Relative path from skill root"},"directory":{"type":"string","enum":["references","assets","scripts"],"description":"Top-level skill directory where this file resides"},"sizeBytes":{"type":"integer","minimum":0},"content":{"type":"string","description":"File content (empty string allowed)"}},"required":["filename","content"]},"description":"Optional references for initial version creation"}},"required":["name","description","instructionPrompt"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the skill"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this skill"},"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Description of what this skill teaches an agent to do"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Optional required tool types for this skill"},"userId":{"type":["string","null"],"description":"User ID that owns this user-scoped skill, or null for organization skills"},"createdByUserId":{"type":["string","null"],"description":"User ID that created this skill, or null for system-created records"},"createdAt":{"type":"string","description":"Timestamp when the skill was created"},"updatedAt":{"type":"string","description":"Timestamp when the skill was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the skill was soft-deleted, or null if active"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this skill (e.g. \"github\") when it is GitOps-managed; null/absent when UI-managed"},"usedByAgentCount":{"type":"number","description":"How many agents currently use this skill"},"invocationCount30d":{"type":"number","description":"Distinct chats in the last 30 days where an agent read this skill from the sandbox"},"currentVersion":{"type":"number","description":"Current version number of this skill"},"instructionPrompt":{"type":"string","description":"Primary instruction prompt content for this skill"},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the reference file record"},"skillVersionId":{"type":"string","format":"uuid","description":"Version ID this reference belongs to"},"filename":{"type":"string","description":"Relative path from skill root (for example references/guide.md)"},"directory":{"type":"string","enum":["references","assets","scripts"],"description":"Top-level skill directory where this file resides"},"sizeBytes":{"type":"integer","minimum":0,"description":"UTF-8 byte size of the file content"},"content":{"type":"string","description":"Optional file content (included in version detail / export flows)"},"createdAt":{"type":"string","description":"Timestamp when this file was stored"}},"required":["id","skillVersionId","filename","directory","sizeBytes"]},"description":"Resource files for the active/current version"}},"required":["id","organizationId","name","description","requiredTools","userId","createdByUserId","createdAt","updatedAt","deletedAt","instructionPrompt"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/skills/{skillId}/export":{"get":{"summary":"Export skill","description":"Export a skill payload including current detail and version metadata.","tags":["Skills"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/skills/:skillId/export\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"skillId","description":"Unique identifier for the skill","schema":{"type":"string","format":"uuid","description":"Unique identifier for the skill"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"skill":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the skill"},"organizationId":{"type":"string","description":"Unique identifier of the organization that owns this skill"},"name":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","minLength":1,"maxLength":64,"description":"Machine-safe skill name used in sandbox paths and imports"},"description":{"type":"string","description":"Description of what this skill teaches an agent to do"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Optional required tool types for this skill"},"userId":{"type":["string","null"],"description":"User ID that owns this user-scoped skill, or null for organization skills"},"createdByUserId":{"type":["string","null"],"description":"User ID that created this skill, or null for system-created records"},"createdAt":{"type":"string","description":"Timestamp when the skill was created"},"updatedAt":{"type":"string","description":"Timestamp when the skill was last updated"},"deletedAt":{"type":["string","null"],"description":"Timestamp when the skill was soft-deleted, or null if active"},"syncSource":{"type":["string","null"],"description":"Sync backend managing this skill (e.g. \"github\") when it is GitOps-managed; null/absent when UI-managed"},"usedByAgentCount":{"type":"number","description":"How many agents currently use this skill"},"invocationCount30d":{"type":"number","description":"Distinct chats in the last 30 days where an agent read this skill from the sandbox"},"currentVersion":{"type":"number","description":"Current version number of this skill"},"instructionPrompt":{"type":"string","description":"Primary instruction prompt content for this skill"},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the reference file record"},"skillVersionId":{"type":"string","format":"uuid","description":"Version ID this reference belongs to"},"filename":{"type":"string","description":"Relative path from skill root (for example references/guide.md)"},"directory":{"type":"string","enum":["references","assets","scripts"],"description":"Top-level skill directory where this file resides"},"sizeBytes":{"type":"integer","minimum":0,"description":"UTF-8 byte size of the file content"},"content":{"type":"string","description":"Optional file content (included in version detail / export flows)"},"createdAt":{"type":"string","description":"Timestamp when this file was stored"}},"required":["id","skillVersionId","filename","directory","sizeBytes"]},"description":"Resource files for the active/current version"}},"required":["id","organizationId","name","description","requiredTools","userId","createdByUserId","createdAt","updatedAt","deletedAt","instructionPrompt"]},"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the skill version"},"skillId":{"type":"string","format":"uuid","description":"Parent skill ID"},"version":{"type":"integer","exclusiveMinimum":0,"description":"Monotonic version number for the skill"},"createdByUserId":{"type":["string","null"],"description":"User who created this version, if available"},"createdAt":{"type":"string","description":"Timestamp when this version was created"}},"required":["id","skillId","version","createdByUserId","createdAt"]}},"activeVersion":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the skill version"},"skillId":{"type":"string","format":"uuid","description":"Parent skill ID"},"version":{"type":"integer","exclusiveMinimum":0,"description":"Monotonic version number for the skill"},"createdByUserId":{"type":["string","null"],"description":"User who created this version, if available"},"createdAt":{"type":"string","description":"Timestamp when this version was created"},"instructionPrompt":{"type":"string","description":"Instruction content for this specific version"},"requiredTools":{"type":"array","items":{"type":"string"},"description":"Required tools snapshot for this specific version"},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the reference file record"},"skillVersionId":{"type":"string","format":"uuid","description":"Version ID this reference belongs to"},"filename":{"type":"string","description":"Relative path from skill root (for example references/guide.md)"},"directory":{"type":"string","enum":["references","assets","scripts"],"description":"Top-level skill directory where this file resides"},"sizeBytes":{"type":"integer","minimum":0,"description":"UTF-8 byte size of the file content"},"content":{"type":"string","description":"Optional file content (included in version detail / export flows)"},"createdAt":{"type":"string","description":"Timestamp when this file was stored"}},"required":["id","skillVersionId","filename","directory","sizeBytes"]},"description":"References attached to this specific version"}},"required":["id","skillId","version","createdByUserId","createdAt","instructionPrompt","requiredTools","references"]}},"required":["skill","versions","activeVersion"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/list":{"get":{"summary":"List tools","description":"Return a grouped list of tools available to the organization.","tags":["Tools"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/tools/list\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"tools":{"description":"Complex structure containing grouped tools available to the organization"}},"description":"Response containing organized tool groups"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/{toolType}/disconnect":{"delete":{"summary":"Disconnect tool","description":"Remove stored credentials for a given tool type, disconnecting it from the organization.","tags":["Tools"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X DELETE \"https://app.cotool.ai/api/tools/:toolType/disconnect\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"toolType","description":"Type identifier of the tool to disconnect","schema":{"type":"string","description":"Type identifier of the tool to disconnect"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the tool was successfully disconnected"}},"required":["success"],"description":"Response confirming tool disconnection"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/get-tool-use-raw-output":{"get":{"summary":"Get raw tool output","description":"Fetch raw data captured for a previous tool invocation specified by uuid.","tags":["Tools"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/tools/get-tool-use-raw-output\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"uuid","description":"Unique identifier of the tool use to retrieve raw output for","schema":{"type":"string","description":"Unique identifier of the tool use to retrieve raw output for"},"required":true},{"in":"query","name":"offset","description":"Character offset for chunked raw output retrieval","schema":{"type":"integer","minimum":0,"description":"Character offset for chunked raw output retrieval"}},{"in":"query","name":"limit","description":"Maximum characters to return for chunked raw output retrieval","schema":{"type":"integer","minimum":1,"maximum":5242880,"description":"Maximum characters to return for chunked raw output retrieval"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"Raw output data from the tool invocation"},"offset":{"type":"number"},"limit":{"type":"number"},"sizeBytes":{"type":"number"},"hasMore":{"type":"boolean"},"nextOffset":{"type":["number","null"]},"contentType":{"type":"string"}},"description":"Raw tool output data"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/threat-model":{"get":{"summary":"Get threat model","description":"Get the current threat model for the organization.","tags":["Threat Model"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/threat-model\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"threatModel":{"type":["object","null"],"properties":{"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this threat model"},"currentVersion":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this threat model version"},"version":{"type":"integer","exclusiveMinimum":0,"description":"Monotonic version number"},"isCurrent":{"type":"boolean","description":"Whether this version is currently active for the organization"},"authorType":{"type":"string","enum":["ai","user"],"description":"Whether this version was created by AI or a human"},"authorId":{"type":["string","null"],"format":"uuid","description":"User ID for human edits, or null for AI-authored versions"},"modelAlias":{"type":["string","null"],"description":"Model alias that produced this version, or null for human edits"},"changeDescription":{"type":["string","null"],"description":"Short description of why this version was created"},"createdAt":{"type":"string","description":"Timestamp when this version was created"},"content":{"type":"string","description":"Full markdown content for this threat model version"}},"required":["id","version","isCurrent","authorType","authorId","modelAlias","changeDescription","createdAt","content"],"description":"Current active version for the organization"}},"required":["organizationId","currentVersion"],"description":"Current threat model for the org, or null if none exists yet"},"generationJob":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Active threat model generation job ID"},"status":{"type":"string","enum":["pending","in_progress"],"description":"Current active generation job status"},"createdAt":{"type":"string","description":"Timestamp when the active generation job was created"}},"required":["id","status","createdAt"],"description":"Active threat model generation job, if one is currently pending or running"},"recentVersionWindow":{"type":"integer","exclusiveMinimum":0,"description":"How many recent versions threat model logic typically needs to look at"}},"required":["threatModel","recentVersionWindow"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update threat model","description":"Save a user-edited threat model as a new version in the organization history.","tags":["Threat Model"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/threat-model\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"content\":\"string\",\"changeDescription\":\"string\"}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"description":"Updated full markdown content for the threat model"},"changeDescription":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Optional reason for the change"}},"required":["content"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this threat model"},"currentVersion":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this threat model version"},"version":{"type":"integer","exclusiveMinimum":0,"description":"Monotonic version number"},"isCurrent":{"type":"boolean","description":"Whether this version is currently active for the organization"},"authorType":{"type":"string","enum":["ai","user"],"description":"Whether this version was created by AI or a human"},"authorId":{"type":["string","null"],"format":"uuid","description":"User ID for human edits, or null for AI-authored versions"},"modelAlias":{"type":["string","null"],"description":"Model alias that produced this version, or null for human edits"},"changeDescription":{"type":["string","null"],"description":"Short description of why this version was created"},"createdAt":{"type":"string","description":"Timestamp when this version was created"},"content":{"type":"string","description":"Full markdown content for this threat model version"}},"required":["id","version","isCurrent","authorType","authorId","modelAlias","changeDescription","createdAt","content"],"description":"Current active version for the organization"}},"required":["organizationId","currentVersion"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/threat-model/board":{"get":{"summary":"Get structured threat model board","description":"Get the structured per-surface board (lean generated layer + live detection-agent overlay).","tags":["Threat Model"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/threat-model/board\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"coverageRefreshPending":{"type":"boolean","description":"Whether async inventory or surface classification updates are still refreshing coverage overlays."},"presentPlatforms":{"type":"array","items":{"type":"string"},"description":"ATT&CK platforms the org runs (passthrough from the board projection); used to hide techniques for absent platforms."},"surfaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["identity","cloud","endpoint","saas","email","network","source-code","application"]},"label":{"type":"string"},"environment":{"type":"object","properties":{"summary":{"type":"string"},"components":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"A concrete thing on this surface, e.g. \"Okta (acme.okta.com)\"."},"detail":{"type":"string","description":"One-line characterization of that component."}},"required":["name","detail"]}}},"required":["summary","components"]},"gaps":{"type":"array","items":{"type":"string"}},"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"hits30d":{"type":"integer"},"runs30d":{"type":"integer"}},"required":["id","name","hits30d","runs30d"]}}},"required":["id","label","environment","gaps","agents"]},"description":"All fixed surfaces, ordered, with live detection-agent overlay."}},"required":["presentPlatforms","surfaces"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/threat-model/regenerate":{"post":{"summary":"Regenerate threat model","description":"Enqueue a threat model regeneration job using current environment data.","tags":["Threat Model"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/threat-model/regenerate\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"changeDescription\":\"string\"}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"changeDescription":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Optional reason shown on the new AI-authored version"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"startedLocally":{"type":"boolean"}},"required":["jobId","startedLocally"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/threat-model/versions":{"get":{"summary":"List threat model version history","description":"List the full threat model version history for the organization.","tags":["Threat Model"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/threat-model/versions\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this threat model version"},"version":{"type":"integer","exclusiveMinimum":0,"description":"Monotonic version number"},"isCurrent":{"type":"boolean","description":"Whether this version is currently active for the organization"},"authorType":{"type":"string","enum":["ai","user"],"description":"Whether this version was created by AI or a human"},"authorId":{"type":["string","null"],"format":"uuid","description":"User ID for human edits, or null for AI-authored versions"},"modelAlias":{"type":["string","null"],"description":"Model alias that produced this version, or null for human edits"},"changeDescription":{"type":["string","null"],"description":"Short description of why this version was created"},"createdAt":{"type":"string","description":"Timestamp when this version was created"}},"required":["id","version","isCurrent","authorType","authorId","modelAlias","changeDescription","createdAt"]},"description":"Full version history for this threat model"},"recentVersionWindow":{"type":"integer","exclusiveMinimum":0,"description":"How many recent versions threat model logic typically needs to look at"}},"required":["versions","recentVersionWindow"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/threat-model/versions/{versionId}":{"get":{"summary":"Get threat model version","description":"Get one threat model version from the organization history by ID.","tags":["Threat Model"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/threat-model/versions/:versionId\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"versionId","description":"Unique identifier for a threat model version in the organization history","schema":{"type":"string","format":"uuid","description":"Unique identifier for a threat model version in the organization history"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this threat model version"},"version":{"type":"integer","exclusiveMinimum":0,"description":"Monotonic version number"},"isCurrent":{"type":"boolean","description":"Whether this version is currently active for the organization"},"authorType":{"type":"string","enum":["ai","user"],"description":"Whether this version was created by AI or a human"},"authorId":{"type":["string","null"],"format":"uuid","description":"User ID for human edits, or null for AI-authored versions"},"modelAlias":{"type":["string","null"],"description":"Model alias that produced this version, or null for human edits"},"changeDescription":{"type":["string","null"],"description":"Short description of why this version was created"},"createdAt":{"type":"string","description":"Timestamp when this version was created"},"content":{"type":"string","description":"Full markdown content for this threat model version"}},"required":["id","version","isCurrent","authorType","authorId","modelAlias","changeDescription","createdAt","content"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/users":{"get":{"summary":"List users","description":"Retrieve all users within the current organization.","tags":["Users"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/users\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the user"},"email":{"type":"string","description":"Email address of the user"},"displayName":{"type":"string","description":"Profile display name, falling back to email"},"imageUrl":{"type":["string","null"],"description":"OAuth profile image URL when available"},"roleId":{"type":"string","description":"Role assigned to the user"},"createdAt":{"type":"string","description":"When the user account was created","format":"date-time","example":"2025-06-17T12:34:56.789Z"},"updatedAt":{"type":"string","description":"When the user account was last updated","format":"date-time","example":"2025-06-17T12:34:56.789Z"},"lastLogin":{"type":["string","null"],"description":"When the user last logged in (null if never)","format":"date-time","example":"2025-06-17T12:34:56.789Z"},"organization":{"type":"string","description":"Organization the user belongs to"}},"required":["id","email","createdAt","updatedAt","lastLogin","organization"]},"description":"Array of user records"},"count":{"type":"number","description":"Total number of users returned"}},"required":["users","count"],"description":"Response containing users and count information"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/users/{id}":{"delete":{"summary":"Delete user","description":"Delete a user by ID within your organization.","tags":["Users"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X DELETE \"https://app.cotool.ai/api/users/:id\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","description":"User ID","schema":{"type":"string","format":"uuid","description":"User ID"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"userId":{"type":"string","format":"uuid"}},"required":["message","userId"],"description":"User deletion response"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update user","description":"Update a user's role assignment within your organization.","tags":["Users"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/users/:id\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"roleId\":\"string\"}'"}],"parameters":[{"in":"path","name":"id","description":"User ID","schema":{"type":"string","format":"uuid","description":"User ID"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"roleId":{"type":"string","minLength":1,"description":"Update the user's role assignment"}},"required":["roleId"],"description":"Fields that may be updated on a user via the API"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/detection-library":{"get":{"summary":"List the Cotool detection library","description":"Returns every library entry with eligibility derived at request time from the organization's connected tools, and the org detection created from it when already added. Never includes notebook source. Requires tool.read; added detection IDs are limited to detections the caller can read.","tags":["Detections"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/detection-library\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","description":"Kebab-case library entry identity"},"name":{"type":"string"},"summary":{"type":"string","description":"1–3 sentence plain-prose headline of what the detection is meant to detect"},"description":{"type":"string","description":"Operational GitHub-flavored markdown covering the signal and the fire condition"},"revision":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the entry notebook"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Tool actions the entry notebook calls"},"requiredLogSources":{"type":"array","items":{"type":"string"},"description":"Cotool Logs warehouse sources the notebook queries (e.g. okta); eligibility requires the org to have their log ingest enabled"},"missingLogSources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Ingest source registry id"},"displayName":{"type":"string","description":"Human-readable log source name"}},"required":["id","displayName"],"additionalProperties":false},"description":"Required log sources the organization is not ingesting"},"missingTools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Tool action called by the entry notebook"},"displayName":{"type":"string","description":"Human-readable integration name from the tools registry"}},"required":["name","displayName"],"additionalProperties":false},"description":"Required integration tool actions the organization cannot run"},"mitreTechniqueIds":{"type":"array","items":{"type":"string"}},"defaultIntervalMinutes":{"anyOf":[{"type":"number","const":10},{"type":"number","const":30},{"type":"number","const":60},{"type":"number","const":360},{"type":"number","const":1440}],"description":"Run interval enabled when the entry is added"},"defaultMinSeverity":{"type":"string","enum":["low","medium","high","critical"]},"eligible":{"type":"boolean","description":"Whether missingLogSources and missingTools are both empty"},"addedDetectionId":{"type":["string","null"],"format":"uuid","description":"The org detection created from this entry, when already added"}},"required":["slug","name","summary","description","revision","toolNames","requiredLogSources","mitreTechniqueIds","defaultIntervalMinutes","defaultMinSeverity","eligible","addedDetectionId"],"additionalProperties":false}}},"required":["entries"],"additionalProperties":false}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Caller lacks tool.read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/detection-library/{slug}":{"get":{"summary":"Read one detection library entry","description":"Returns the entry with its notebook source and the globally cached logic summary, for review before adding. Requires tool.read.","tags":["Detections"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/detection-library/:slug\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"slug","schema":{"type":"string","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","description":"Kebab-case library entry identity"},"name":{"type":"string"},"summary":{"type":"string","description":"1–3 sentence plain-prose headline of what the detection is meant to detect"},"description":{"type":"string","description":"Operational GitHub-flavored markdown covering the signal and the fire condition"},"revision":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"SHA-256 of the entry notebook"},"toolNames":{"type":"array","items":{"type":"string"},"description":"Tool actions the entry notebook calls"},"requiredLogSources":{"type":"array","items":{"type":"string"},"description":"Cotool Logs warehouse sources the notebook queries (e.g. okta); eligibility requires the org to have their log ingest enabled"},"missingLogSources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Ingest source registry id"},"displayName":{"type":"string","description":"Human-readable log source name"}},"required":["id","displayName"],"additionalProperties":false},"description":"Required log sources the organization is not ingesting"},"missingTools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Tool action called by the entry notebook"},"displayName":{"type":"string","description":"Human-readable integration name from the tools registry"}},"required":["name","displayName"],"additionalProperties":false},"description":"Required integration tool actions the organization cannot run"},"mitreTechniqueIds":{"type":"array","items":{"type":"string"}},"defaultIntervalMinutes":{"anyOf":[{"type":"number","const":10},{"type":"number","const":30},{"type":"number","const":60},{"type":"number","const":360},{"type":"number","const":1440}],"description":"Run interval enabled when the entry is added"},"defaultMinSeverity":{"type":"string","enum":["low","medium","high","critical"]},"eligible":{"type":"boolean","description":"Whether missingLogSources and missingTools are both empty"},"addedDetectionId":{"type":["string","null"],"format":"uuid","description":"The org detection created from this entry, when already added"},"content":{"type":"string","description":"The entry notebook source, for read-only preview"},"interpretation":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["ready","empty"],"description":"\"empty\" when the notebook has no interpretable cells yet"},"interpretation":{"type":["object","null"],"properties":{"notebookRevision":{"type":"string","description":"Notebook revision this interpretation describes"},"lanes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable step identifier carried across regenerations"},"title":{"type":"string","description":"2-5 word verb-first objective"},"summary":{"type":"string","description":"Plain-language explanation of this step only"},"kind":{"type":"string","enum":["source","transform","decision","output"]},"cellHashes":{"type":"array","items":{"type":"string"},"description":"Content hashes of the cells this step owns"},"substeps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","description":"Short plain-language action, a few words"},"detail":{"type":"string","description":"One or two sentences describing the concrete logic"},"cellHash":{"type":"string","description":"Content hash of the cell this substep describes"}},"required":["id","title","detail","cellHash"],"additionalProperties":false}}},"required":["id","title","summary","kind","cellHashes","substeps"],"additionalProperties":false},"description":"Ordered steps; each step feeds the next"}},"required":["id","steps"],"additionalProperties":false},"description":"Disjoint simple paths over the semantic steps"}},"required":["notebookRevision","lanes"],"additionalProperties":false},"cells":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Cell function name; \"_\" when anonymous"},"code":{"type":"string","description":"Cell body source without the def/return scaffolding"},"refs":{"type":"array","items":{"type":"string"},"description":"Variables the cell consumes from other cells"},"defs":{"type":"array","items":{"type":"string"},"description":"Variables the cell defines for other cells"},"params":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Constant name, e.g. LOOKBACK_HOURS"},"value":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"boolean"}]},"line":{"type":"integer","description":"Absolute notebook line of the assignment"}},"required":["name","value","line"],"additionalProperties":false},"description":"Tunable literal constants declared by this cell"},"lineStart":{"type":"integer","description":"First line of the cell in the notebook file"},"lineEnd":{"type":"integer","description":"Last line of the cell in the notebook file"},"contentHash":{"type":"string","description":"SHA-256 of the cell body source"}},"required":["name","code","refs","defs","params","lineStart","lineEnd","contentHash"],"additionalProperties":false},"description":"Cells of the interpreted revision, for code display and referencing"}},"required":["status","interpretation","cells"],"additionalProperties":false,"description":"Logic summary computed once per notebook revision and cached globally; null until the interpretation job produces it"}},"required":["slug","name","summary","description","revision","toolNames","requiredLogSources","mitreTechniqueIds","defaultIntervalMinutes","defaultMinSeverity","eligible","addedDetectionId","content","interpretation"],"additionalProperties":false}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Caller lacks tool.read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Library entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/detection-library/{slug}/add":{"post":{"summary":"Add a detection library entry","description":"Creates an org-owned detection from the entry, publishes its notebook as version 1, and enables the entry's default schedule.","tags":["Detections"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/detection-library/:slug/add\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"slug","schema":{"type":"string","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"chatId":{"type":["string","null"],"format":"uuid","description":"Caller-owned editor chat on detail responses; always null in catalog rows"},"revision":{"type":"string","pattern":"^[0-9a-f]{64}$"},"name":{"type":["string","null"]},"summary":{"type":["string","null"],"description":"1–3 sentence plain-prose headline of what the detection is meant to detect. No bullet lists."},"howItWorks":{"type":["string","null"],"description":"How the detection works, as operational GitHub-flavored markdown: typically two or three bullets covering the signal it watches and the condition that fires"},"toolNames":{"type":"array","items":{"type":"string"}},"mitreTechniqueIds":{"type":"array","items":{"type":"string"}},"metadataStatus":{"type":"string","enum":["pending","ready","failed"]},"librarySlug":{"type":["string","null"],"description":"Detection library entry this detection was added from, when any"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"publishedVersionId":{"type":["string","null"],"format":"uuid"},"recentHits":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"executionId":{"type":"string","format":"uuid"},"entity":{"type":"string"},"entityType":{"type":["string","null"]},"severity":{"type":["string","null"],"enum":["low","medium","high","critical",null]},"headline":{"type":["string","null"]},"summary":{"type":["string","null"]},"evidence":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"description":"The emitted row backing this hit"},"closedAt":{"type":["string","null"],"format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"},"lastSeenExecutionId":{"type":["string","null"],"format":"uuid"},"seenCount":{"type":"integer","exclusiveMinimum":0},"linkedAlert":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"displayId":{"type":"string","pattern":"^COT-\\d+$"},"status":{"type":"string","enum":["open","in_progress","escalated","closed_true_positive","closed_false_positive","closed_true_positive_benign","dismissed","duplicate","expired"],"description":"Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists."},"derivedDisposition":{"type":["string","null"],"enum":["true_positive","false_positive","true_positive_benign",null],"description":"Verdict credited to this hit. For an alert archived as a duplicate this is the canonical alert's verdict."},"assignedAgent":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1}},"required":["id","name"],"additionalProperties":false}},"required":["id","displayId","status","derivedDisposition","assignedAgent"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","executionId","entity","entityType","severity","headline","summary","evidence","closedAt","lastSeenAt","lastSeenExecutionId","seenCount","linkedAlert","createdAt","updatedAt"],"additionalProperties":false}},"feedback":{"type":"object","properties":{"detectionId":{"type":"string","format":"uuid"},"windowDays":{"type":"integer","exclusiveMinimum":0},"dispositions":{"type":"object","properties":{"truePositive":{"type":"integer","minimum":0},"falsePositive":{"type":"integer","minimum":0},"benign":{"type":"integer","minimum":0}},"required":["truePositive","falsePositive","benign"],"additionalProperties":false,"description":"Alert verdicts credited to the detection. Alerts archived as duplicates inherit the verdict of their canonical alert."},"statuses":{"type":"object","properties":{"open":{"type":"integer","minimum":0},"inProgress":{"type":"integer","minimum":0},"escalated":{"type":"integer","minimum":0},"duplicate":{"type":"integer","minimum":0,"description":"Duplicates whose canonical alert has no verdict yet. Once the canonical alert is dispositioned the duplicate moves into that disposition count."},"dismissed":{"type":"integer","minimum":0},"expired":{"type":"integer","minimum":0}},"required":["open","inProgress","escalated","duplicate","dismissed","expired"],"additionalProperties":false},"precision":{"type":"object","properties":{"value":{"type":["number","null"],"minimum":0,"maximum":1},"numerator":{"type":"integer","minimum":0},"denominator":{"type":"integer","minimum":0}},"required":["value","numerator","denominator"],"additionalProperties":false},"versions":{"type":"array","items":{"type":"object","properties":{"versionId":{"type":"string","format":"uuid"},"version":{"type":"integer","exclusiveMinimum":0},"dispositions":{"type":"object","properties":{"truePositive":{"type":"integer","minimum":0},"falsePositive":{"type":"integer","minimum":0},"benign":{"type":"integer","minimum":0}},"required":["truePositive","falsePositive","benign"],"additionalProperties":false,"description":"Alert verdicts credited to the detection. Alerts archived as duplicates inherit the verdict of their canonical alert."},"precision":{"type":"object","properties":{"value":{"type":["number","null"],"minimum":0,"maximum":1},"numerator":{"type":"integer","minimum":0},"denominator":{"type":"integer","minimum":0}},"required":["value","numerator","denominator"],"additionalProperties":false}},"required":["versionId","version","dispositions","precision"],"additionalProperties":false}},"falsePositiveEntities":{"type":"array","items":{"type":"object","properties":{"entity":{"type":"string"},"entityType":{"type":["string","null"]},"count":{"type":"integer","exclusiveMinimum":0}},"required":["entity","entityType","count"],"additionalProperties":false}},"actorSplit":{"type":"object","properties":{"human":{"type":"object","properties":{"truePositive":{"type":"integer","minimum":0},"falsePositive":{"type":"integer","minimum":0},"benign":{"type":"integer","minimum":0}},"required":["truePositive","falsePositive","benign"],"additionalProperties":false,"description":"Alert verdicts credited to the detection. Alerts archived as duplicates inherit the verdict of their canonical alert."},"agent":{"type":"object","properties":{"truePositive":{"type":"integer","minimum":0},"falsePositive":{"type":"integer","minimum":0},"benign":{"type":"integer","minimum":0}},"required":["truePositive","falsePositive","benign"],"additionalProperties":false,"description":"Alert verdicts credited to the detection. Alerts archived as duplicates inherit the verdict of their canonical alert."}},"required":["human","agent"],"additionalProperties":false},"scheduledExecutions":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"succeeded":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"interrupted":{"type":"integer","minimum":0},"running":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1},"averageRuntimeMs":{"type":["number","null"],"minimum":0},"errorCount":{"type":"integer","minimum":0},"recentErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"count":{"type":"integer","exclusiveMinimum":0},"lastOccurredAt":{"type":"string","format":"date-time"}},"required":["message","count","lastOccurredAt"],"additionalProperties":false}},"lastScheduledRunAt":{"type":["string","null"],"format":"date-time"},"lastFinishedStatus":{"type":["string","null"],"enum":["succeeded","failed","interrupted",null]}},"required":["total","succeeded","failed","interrupted","running","successRate","averageRuntimeMs","errorCount","recentErrors","lastScheduledRunAt","lastFinishedStatus"],"additionalProperties":false},"volume":{"type":"object","properties":{"hits":{"type":"integer","minimum":0},"alerts":{"type":"integer","minimum":0},"lastResultAt":{"type":["string","null"],"format":"date-time"},"lastAlertAt":{"type":["string","null"],"format":"date-time"}},"required":["hits","alerts","lastResultAt","lastAlertAt"],"additionalProperties":false},"everEscalated":{"type":"integer","minimum":0},"meanTimeToDispositionSeconds":{"type":["number","null"],"minimum":0}},"required":["detectionId","windowDays","dispositions","statuses","precision","versions","falsePositiveEntities","actorSplit","scheduledExecutions","volume","everEscalated","meanTimeToDispositionSeconds"],"additionalProperties":false}},"required":["id","chatId","revision","name","summary","howItWorks","toolNames","mitreTechniqueIds","metadataStatus","librarySlug","createdAt","updatedAt","publishedVersionId","recentHits","feedback"],"additionalProperties":false}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"404":{"description":"Library entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Entry already added or its tools are not connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/hunt/alert-creation-settings":{"get":{"summary":"Get Hunt Alert creation settings","description":"Get the organization-wide minimum exposure band and compromise-signal override used to create or reopen Hunt Alerts.","tags":["Hunt"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/hunt/alert-creation-settings\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"minimumExposureBand":{"type":"string","enum":["medium","high","critical"],"description":"Minimum exposure band that creates or reopens a Hunt Alert."},"alertOnCompromiseBelowThreshold":{"type":"boolean","description":"Whether a live compromise signal creates or reopens a Hunt Alert below the minimum exposure band."}},"required":["minimumExposureBand","alertOnCompromiseBelowThreshold"],"additionalProperties":false}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update Hunt Alert creation settings","description":"Update the organization-wide minimum exposure band and compromise-signal override used to create or reopen Hunt Alerts.","tags":["Hunt"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/hunt/alert-creation-settings\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"minimumExposureBand\":\"medium\",\"alertOnCompromiseBelowThreshold\":true}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"minimumExposureBand":{"type":"string","enum":["medium","high","critical"],"description":"Minimum exposure band that creates or reopens a Hunt Alert."},"alertOnCompromiseBelowThreshold":{"type":"boolean","description":"Whether a live compromise signal creates or reopens a Hunt Alert below the minimum exposure band."}},"required":["minimumExposureBand","alertOnCompromiseBelowThreshold"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"minimumExposureBand":{"type":"string","enum":["medium","high","critical"],"description":"Minimum exposure band that creates or reopens a Hunt Alert."},"alertOnCompromiseBelowThreshold":{"type":"boolean","description":"Whether a live compromise signal creates or reopens a Hunt Alert below the minimum exposure band."}},"required":["minimumExposureBand","alertOnCompromiseBelowThreshold"],"additionalProperties":false}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/trigger/{triggerId}/move":{"post":{"summary":"Move trigger to another agent","description":"Re-assign a trigger to a different agent. The webhook URL and secret are unchanged (they embed only the trigger id), so externally configured webhooks keep working.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/agents/:agentId/trigger/:triggerId/move\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"targetAgentId\":\"string\"}'"}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true},{"in":"path","name":"triggerId","description":"Unique identifier of the trigger","schema":{"type":"string","format":"uuid","description":"Unique identifier of the trigger"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"targetAgentId":{"type":"string","format":"uuid","description":"Agent that should own and run this trigger"}},"required":["targetAgentId"],"description":"Request body for moving a trigger to a different agent"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the move succeeded"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"source":{"type":"string","enum":["jira","jira-automation","slack","linear","cron","webhook","email","bugcrowd","hackerone","zscaler","darktrace"]},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"First-class event behavior. Missing only on legacy serialized snapshots."},"name":{"type":"string"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"cronSchedule":{"type":["string","null"]},"emailAddress":{"type":["string","null"]},"config":{"type":"object","additionalProperties":{}},"lastRunAttemptedAt":{"type":["string","null"]},"lastRunSucceededAt":{"type":["string","null"]}},"required":["id","agentId","organizationId","source","name","enabled","createdAt","updatedAt","config"]}},"required":["success","data"],"description":"Response confirming the trigger was moved to the target agent"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/trigger-sources/{source}/fields":{"get":{"summary":"Get webhook fields for a trigger source","description":"Generate a webhook URL, secret, and any additional fields required to configure an external webhook, before the trigger is assigned to an agent.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/trigger-sources/:source/fields\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"source","description":"Source type for the trigger (e.g., jira, slack, linear, hackerone)","schema":{"type":"string","description":"Source type for the trigger (e.g., jira, slack, linear, hackerone)"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the webhook fields were generated successfully"},"data":{"type":"object","properties":{"secret":{"type":"string","description":"Generated secret for webhook authentication"},"webhookUrl":{"type":"string","description":"Generated webhook URL for external services to call"},"additionalFields":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"jira"},"jiraUrl":{"type":"string","description":"URL to Jira webhook configuration page"}},"required":["type","jiraUrl"]},{"type":"object","properties":{"type":{"type":"string","const":"jira-automation"},"authHeader":{"type":"string","description":"Header name for authentication (X-Webhook-Auth)"},"instructions":{"type":"string","description":"Instructions for Jira Automation Send web request setup"}},"required":["type","authHeader","instructions"]},{"type":"object","properties":{"type":{"type":"string","const":"slack"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"linear"},"workspaceName":{"type":"string","description":"Name of the Linear workspace"}},"required":["type","workspaceName"]},{"type":"object","properties":{"type":{"type":"string","const":"webhook"},"authHeader":{"type":"string","description":"Header name for authentication (X-Webhook-Auth)"},"instructions":{"type":"string","description":"Simple instructions for webhook setup"}},"required":["type","authHeader","instructions"]},{"type":"object","properties":{"type":{"type":"string","const":"hackerone"},"signatureHeader":{"type":"string","description":"Header HackerOne uses to sign deliveries (X-H1-Signature)"},"instructions":{"type":"string","description":"Instructions for HackerOne webhook setup"}},"required":["type","signatureHeader","instructions"]},{"type":"object","properties":{"type":{"type":"string","const":"bugcrowd"},"signatureHeader":{"type":"string","description":"Header Bugcrowd uses to sign deliveries (X-Bugcrowd-Digest)"},"instructions":{"type":"string","description":"Instructions for configuring an Outgoing Webhook in Bugcrowd"}},"required":["type","signatureHeader","instructions"]},{"type":"object","properties":{"type":{"type":"string","const":"zscaler"},"authHeader":{"type":"string","description":"Header carrying the token in Zscaler deliveries (X-Cotool-Webhook-Token)"},"instructions":{"type":"string","description":"Instructions for pointing a Zscaler Cloud NSS feed or alert webhook at this trigger"}},"required":["type","authHeader","instructions"]},{"type":"object","properties":{"type":{"type":"string","const":"darktrace"},"basicUsername":{"type":"string","description":"HTTP Basic authentication username (the trigger ID)"},"instructions":{"type":"string","description":"Instructions for configuring the Darktrace HTTPS module"}},"required":["type","basicUsername","instructions"]}],"description":"Additional configuration fields specific to the trigger source type"}},"required":["secret","webhookUrl","additionalFields"],"description":"Webhook configuration data"}},"required":["success","data"],"description":"Response containing webhook configuration fields for external service setup"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/{agentId}/trigger/{triggerId}/event-mode":{"patch":{"summary":"Update trigger event mode","description":"Set whether a trigger creates an alert before running the agent or runs the agent directly.","tags":["Agent Triggers"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PATCH \"https://app.cotool.ai/api/agents/:agentId/trigger/:triggerId/event-mode\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"eventMode\":\"direct\"}'"}],"parameters":[{"in":"path","name":"agentId","description":"Unique identifier of the agent","schema":{"type":"string","format":"uuid","description":"Unique identifier of the agent"},"required":true},{"in":"path","name":"triggerId","description":"Unique identifier of the trigger","schema":{"type":"string","format":"uuid","description":"Unique identifier of the trigger"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Run the agent directly or create an alert before running it"}},"required":["eventMode"],"description":"Request body for updating whether a trigger creates alerts"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the event mode update was successful"},"eventMode":{"type":"string","enum":["direct","alert_source"],"description":"Current event mode of the trigger after update"}},"required":["success","eventMode"],"description":"Response confirming trigger event mode update"}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/intel/iocs":{"get":{"summary":"List flattened threat-intel indicators (IOCs)","description":"Flattens indicators from all in-scope intel items, resolves per-indicator hunt status, and supports server-side search, status, and type filtering with pagination.","tags":["Intel"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/intel/iocs\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"page","schema":{"type":"number","minimum":1}},{"in":"query","name":"perPage","schema":{"type":"number","minimum":1,"maximum":200}},{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","enum":["found","clean","unchecked","unknown"]}},{"in":"query","name":"type","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string"},"type":{"type":"string"},"intelItemId":{"type":"string"},"intelTitle":{"type":"string"},"sourceLabel":{"type":"string"},"lastCheckedAt":{"type":["string","null"]},"status":{"type":"string","enum":["found","clean","unchecked","unknown"]}},"required":["id","value","type","intelItemId","intelTitle","sourceLabel","lastCheckedAt","status"]}},"total":{"type":"number"},"page":{"type":"number"},"perPage":{"type":"number"},"hasNext":{"type":"boolean"},"statusCounts":{"type":"object","properties":{"found":{"type":"number"},"clean":{"type":"number"},"unchecked":{"type":"number"},"unknown":{"type":"number"}},"required":["found","clean","unchecked","unknown"]},"availableTypes":{"type":"array","items":{"type":"string"}}},"required":["rows","total","page","perPage","hasNext","statusCounts","availableTypes"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/intel/items":{"get":{"summary":"List threat intelligence items","description":"Retrieves a paginated list of threat intelligence items with support for filtering by severity, platform, status, source, and text search","tags":["Intel"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/intel/items\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"query","name":"page","schema":{"type":"number","minimum":1}},{"in":"query","name":"perPage","schema":{"type":"number","minimum":1,"maximum":100}},{"in":"query","name":"severity","schema":{"type":"string","enum":["none","low","medium","high","critical"]}},{"in":"query","name":"platform","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","enum":["active","corrected","retracted"]}},{"in":"query","name":"source","schema":{"type":"string"}},{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"minRelevancyScore","schema":{"type":"number","minimum":0,"maximum":100}},{"in":"query","name":"relevancyMode","schema":{"type":"string","enum":["relevant","all"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"externalId":{"type":"string"},"source":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"name":{"type":"string"},"publisher":{"type":"string"},"publishTime":{"type":"string"},"tlp":{"type":"string","enum":["CLEAR","GREEN","AMBER","AMBER+STRICT","RED"]},"license":{"type":"string"},"language":{"type":"string"}},"required":["url","publisher","publishTime","language"]},"event":{"type":"object","properties":{"title":{"type":"string"},"eventFirstSeen":{"type":"string"},"eventLastSeen":{"type":"string"},"severity":{"type":"string","enum":["none","low","medium","high","critical"]},"confidence":{"type":"number","minimum":0,"maximum":1},"status":{"type":"string","enum":["active","corrected","retracted"]}},"required":["title","severity","confidence","status"]},"summary":{"type":"string"},"abstract":{"type":"string"},"tldr":{"type":"string","maxLength":240},"attackPath":{"type":"array","items":{"type":"string"}},"classification":{"type":"object","properties":{"attack":{"type":"array","items":{"type":"object","properties":{"technique":{"type":"string"},"subTechnique":{"type":"string","description":"Sub-technique ID when applicable (e.g., T1059.001)."},"techniqueName":{"type":"string","description":"Resolved human-readable technique name. Omit when unknown."},"confidence":{"type":"number","minimum":0,"maximum":1},"evidenceRef":{"type":"string","description":"Optional reference to supporting evidence (e.g., passage index or quote id)."}},"description":"ATT&CK technique mapping with confidence. Include techniqueName when resolvable."}},"killChain":{"type":"array","items":{"type":"string","enum":["reconnaissance","weaponization","delivery","exploitation","installation","c2","actions"]},"description":"Relevant kill chain phases demonstrated in the content. Return [] when not evidenced."},"malware":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Malware family/tool name."},"confidence":{"type":"number","minimum":0,"maximum":1},"aliases":{"type":"array","items":{"type":"string"},"description":"Known aliases for the malware family/tool."}},"required":["name"],"description":"Malware identification claim."}},"actor":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Threat actor/group name."},"confidence":{"type":"number","minimum":0,"maximum":1},"aliases":{"type":"array","items":{"type":"string"},"description":"Known aliases for the actor/group."}},"required":["name"],"description":"Threat actor attribution claim."}},"platforms":{"type":"array","items":{"type":"string","enum":["windows","linux","macos","ios","android","aws","gcp","azure","o365","okta","kubernetes"]},"description":"Affected platforms/environments. Return [] when not stated."},"mappings":{"type":"array","items":{"type":"object","properties":{"framework":{"type":"string","description":"Framework name (e.g., NIST, CIS)."},"id":{"type":"string","description":"Framework control/technique identifier."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Optional confidence in mapping in [0,1]."}},"required":["framework","id"],"description":"Mapping to other security frameworks."},"description":"Mappings to other frameworks (e.g., NIST, CIS). Return [] when not applicable."}},"required":["attack","killChain","malware","actor","platforms","mappings"],"description":"Classification including ATT&CK mapping, kill chain phases, actors, malware, and platforms."},"affectedProducts":{"type":"array","items":{"type":"object","properties":{"vendor":{"type":"string"},"product":{"type":"string"},"versions":{"type":"array","items":{"type":"string"},"default":[]},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Optional confidence in product impact in [0,1]."}},"required":["versions"],"description":"Affected vendor/product versions relevant for scoping detections."}},"iocs":{"type":"object","properties":{"ipv4":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"ipv6":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"domains":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"urls":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"hashes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"files":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"registryKeys":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"processes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"certs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"cloudIds":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"mobileIds":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}}},"description":"Grouped IOCs (read-tolerant)."},"provenance":{"type":"object","properties":{"supportingPassages":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","description":"Exact quoted text supporting a technical claim. Do not paraphrase."},"sourceUrl":{"type":"string","format":"uri","description":"Optional URL if the passage is from a different source."},"charSpan":{"type":"object","properties":{"start":{"type":"number","description":"Start character offset (inclusive) of quoted span within content."},"end":{"type":"number","description":"End character offset (exclusive) of quoted span within the analyzed content."}},"required":["start","end"],"description":"Character span for the quoted passage within the analyzed content."}},"required":["text"],"description":"Supporting evidence passages used to justify extracted claims."},"description":"Evidence snippets grounding technical claims and mappings. Use [] when no precise evidence exists."}},"required":["supportingPassages"],"description":"Provenance information tying claims to exact sources/passages."},"version":{"type":"integer","exclusiveMinimum":0},"lastUpdated":{"type":"string"},"createdAt":{"type":"string"},"addedToFeedAt":{"type":"string"},"canonicalKey":{"type":"string"},"duplicateOf":{"type":"string"},"tenantOverrides":{}},"required":["id","source","event","summary","tldr","attackPath","classification","affectedProducts","iocs","provenance","version"],"description":"Backwards-compatible intel item for read/API responses (tolerates legacy stored shapes)."}},"total":{"type":"number"},"page":{"type":"number"},"perPage":{"type":"number"},"hasNext":{"type":"boolean"},"validations":{"type":"object","additionalProperties":{"type":["object","null"],"properties":{"relevancyScore":{"type":"number","minimum":0,"maximum":100,"description":"Single numeric score from 0-100 for how APPLICABLE the threat is to this organization — whether the affected products/platforms/versions/ecosystems/surface are present here. NOT about whether compromise was found or telemetry is complete. 70-100: affected surface confirmed present (proceed to hunt even with no compromise evidence / limited telemetry); 50-69: plausibly present, unconfirmed; 0-49: genuinely absent / not applicable. Do not lower the score for missing compromise evidence or telemetry gaps."},"relevancyHeadline":{"type":"string","description":"ONE self-contained, answer-first sentence stating whether and why this threat applies to this environment — always include it. Lead with the conclusion, then the concrete reason (e.g. \"The Acrobat Chrome extension is not installed on any managed browser, so this threat does not apply.\"). Never lead with background inventory or scene-setting. Wrap tool-backed clauses in <cite id=\"qN\">...</cite> spans as in explanation."},"explanation":{"type":"array","items":{"type":"string","description":"One concise tool-backed finding. Wrap each clause supported by a tool call in <cite id=\"qN\">...</cite>. Example: Confirmed <cite id=\"q1\">12 macOS hosts</cite> running <cite id=\"q2\">vulnerable Atlas v3.1</cite>."},"description":"3-6 compact bullets citing specific tool observations about applicability, visibility, and gaps. Wrap the specific clause(s) backed by a tool call in inline citation spans of the form <cite id=\"qN\">...</cite>, where qN matches a <cotool_citation id=\"qN\" /> marker that preceded a tool result in this run."},"agentId":{"type":"string","format":"uuid"},"executionId":{"type":"string","format":"uuid"},"runAt":{"type":"string","format":"date-time","description":"ISO timestamp when the validation completed."},"toolsUsed":{"type":"array","items":{"type":"string"},"description":"Tool identifiers actually invoked during validation (e.g., \"splunk.query\", \"sentinelone.search\", \"aws.ec2.describe\")."}},"required":["relevancyScore","explanation","agentId","executionId","runAt","toolsUsed"],"description":"Structured output for the built-in threat relevancy agent."}},"outputs":{"type":"object","additionalProperties":{"type":["object","null"],"properties":{"exposureScore":{"type":"number","minimum":0,"maximum":100,"description":"Single numeric score (0-100) estimating likelihood of exposure, based strictly on tool evidence. ~90-100: compromised; 60-89: suspicious activity; 1-59: no evidence; 0: unknown."},"headline":{"type":"string","description":"ONE self-contained sentence: the verdict line rendered standalone on the Alert card/list, without the intel or the other bullets for context — always include it. It must answer \"why am I being shown this alert?\": state the concrete indicator/activity or exposure found, the affected system/account/environment, and the evidence-based interpretation that determines the score. If a match is attributable to security inspection, scanning, testing, or another evidenced benign cause, state both the match and that interpretation so the reader immediately understands why it is not concerning. Never use background/applicability context (platform presence, telemetry availability, intel restatement) as the headline, and never use bare back-references (\"Both IPs\", \"the IOCs\") that assume prior context. Wrap tool-backed clauses in <cite id=\"qN\">...</cite> spans as in exposureExplanation."},"exposureExplanation":{"type":"array","items":{"type":"string"},"description":"3-8 concise bullets summarizing the strongest findings that drive the score. Each bullet should reference specific tool evidence (hostnames, query ids, brief log snippet summaries). Wrap the specific clause(s) backed by a tool call in inline citation spans of the form <cite id=\"qN\">...</cite>, where qN matches a <cotool_citation id=\"qN\" /> marker that preceded a tool result in this run."},"iocFindings":{"type":"array","items":{"type":"object","properties":{"iocType":{"type":"string","enum":["ip","domain","url","hash","file_path","process","registry_key","certificate","cloud_id","package","email","user_agent","mutex","other"],"description":"Canonical indicator type: one of ip, domain, url, hash, file_path, process, registry_key, certificate, cloud_id, package, email, user_agent, mutex, other. Use the canonical type of the indicator you were given (or the closest match for one you discovered); use \"other\" only when none fit."},"role":{"type":"string","enum":["compromise","relevance"],"default":"compromise","description":"Carry the role the indicator was given in the input: \"compromise\" for attacker-controlled/attacker-specific artifacts indicative on their own; \"relevance\" for legitimate/dual-use artifacts the threat uses, abuses, or targets (a match proves environment relevance, NEVER compromise on its own). Never promote \"relevance\" to \"compromise\" or demote \"compromise\" to \"relevance\". For an indicator you discovered yourself (not in the input), assign the role by the same test: would a credible match alone justify reporting a compromise signal?"},"platform":{"type":"string","description":"For package/image indicators, the registry/ecosystem it lives in (\"npm\", \"pypi\", \"nuget\", \"dockerhub\", \"github\") so its logo can be shown. Omit for domain/ip/hash indicators and anything with no brandable registry. Never the SIEM/EDR tool that detected it."},"iocValue":{"type":"string","description":"Exact indicator value that was searched."},"found":{"type":"boolean","description":"True if any credible matches were identified in tool results."},"evidence":{"type":"string","description":"Short evidence note (≤280 chars): include minimal context such as a timestamp, log id, query reference, or snippet summary. Do not paste full logs. May contain inline citation spans of the form <cite id=\"qN\">...</cite> referencing the tool call that produced the finding."},"affectedSystems":{"type":"array","items":{"type":"string"},"description":"Compact list of implicated assets (hostnames, asset ids, instance ids) if applicable."}},"required":["iocType","role","iocValue","found"]},"description":"Per-indicator results actually searched. Include only when indicators were checked; omit entirely if no indicator search was performed."},"assets":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string","description":"Asset identifier — hostname, asset id, instance id, ARN, repo, or account."},"kind":{"type":"string","enum":["repository","host","service","cloud_resource","identity","package","domain","saas_account","container_image","other"],"description":"What kind of asset this is. Pick the closest match; use \"other\" only when none fit."},"platform":{"type":"string","description":"The brandable system the asset NATIVELY lives in / is managed from — e.g. \"github\"/\"gitlab\" for a repo, \"aws\"/\"gcp\"/\"azure\" for a cloud resource, \"okta\" for an identity — so we can show its logo. Set ONLY to where the asset resides, NOT the telemetry/SIEM tool you observed it through (a host seen in Splunk/CrowdStrike still has no platform unless it genuinely lives in a brandable product). Omit when there is no brandable home."},"source":{"type":"string","description":"Where the asset was OBSERVED — the tool/integration that surfaced it, e.g. \"CrowdStrike\", \"Datadog APM\", \"GitHub\". This is the evidence source, not necessarily where the asset lives."},"internetFacing":{"type":"boolean","description":"True when the asset is reachable from the internet, false when confirmed internal. Omit when unknown."},"evidence":{"type":"string","description":"Short cited note on why this asset drives exposure. May contain inline citation spans of the form <cite id=\"qN\">...</cite>."}},"required":["identifier","kind"]},"description":"Concrete assets whose cited evidence drives exposure (e.g. vulnerable internet-facing hosts). Populate for exposure-found results even when no IOC was found; omit when no concrete asset was established."},"timeline":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","description":"ISO timestamp of the notable event."},"description":{"type":"string","description":"Short description of what happened and where."}},"required":["timestamp","description"]},"description":"Optional, up to 10 items, ordered by time. Include only if notable events were established from tool evidence."},"gaps":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string","description":"Product whose telemetry is missing/weak."},"logSource":{"type":"string","description":"The missing/weak logs as a short plain-language description (1-3 words, e.g. \"DNS query logs\", \"CI/CD audit logs\") — human-readable words, never a snake_case/technical identifier."},"scopeType":{"type":"string","enum":["org","integration","account","environment","asset_group","tenant","domain"],"description":"Scope of the gap; defaults to org."},"blocking":{"type":"boolean","description":"True when the gap blocked a reliable answer."},"description":{"type":"string","description":"Why the missing/weak log source blocked or weakened the hunt. May contain <cite> spans."}},"required":["product","logSource","description"]},"description":"Observability gaps: missing or weak log sources that blocked or weakened this hunt."},"detectionCoverage":{"type":"object","properties":{"state":{"type":"string","enum":["none","partial","covered","unknown"],"description":"Whether existing detections cover this threat."},"matches":{"type":"array","items":{"type":"object","properties":{"detectionId":{"type":"string","description":"Detection id if a Cotool detection."},"detectionName":{"type":"string","description":"Name of the matched detection."},"source":{"type":"string","description":"Detection engine / SIEM the rule lives in, lowercase key when known (e.g. \"datadog\", \"splunk\", \"scanner\", \"crowdstrike\", \"sentinelone\"). Drives the engine logo in the UI."},"coverage":{"type":"string","enum":["partial","covered","unknown"],"description":"How well this detection covers the threat."},"rationale":{"type":"string","description":"Cited evidence the detection is deployed, scoped, healthy, and matches. May contain <cite> spans."}},"required":["detectionName","coverage","rationale"]},"description":"Detections evaluated as covering this threat. Only covered/partial with cited deploy/scope/health/logic evidence."}},"required":["state"],"description":"Existing detection coverage assessment (separate axis from exposure)."},"agentId":{"type":"string","format":"uuid"},"executionId":{"type":"string","format":"uuid"},"runAt":{"type":"string","format":"date-time","description":"ISO timestamp when the threat hunt completed."},"toolsUsed":{"type":"array","items":{"type":"string"},"description":"Tool identifiers actually invoked during the hunt (e.g., \"splunk.query\", \"crowdstrike.search\", \"vpcflow.scan\")."}},"required":["exposureScore","exposureExplanation","agentId","executionId","runAt","toolsUsed"]}}},"required":["items","total","page","perPage","hasNext"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/intel/items/{id}":{"get":{"summary":"Get specific intel item","description":"Retrieves detailed information for a specific threat intelligence item by its ID","tags":["Intel"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/intel/items/:id\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"externalId":{"type":"string"},"source":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"name":{"type":"string"},"publisher":{"type":"string"},"publishTime":{"type":"string"},"tlp":{"type":"string","enum":["CLEAR","GREEN","AMBER","AMBER+STRICT","RED"]},"license":{"type":"string"},"language":{"type":"string"}},"required":["url","publisher","publishTime","language"]},"event":{"type":"object","properties":{"title":{"type":"string"},"eventFirstSeen":{"type":"string"},"eventLastSeen":{"type":"string"},"severity":{"type":"string","enum":["none","low","medium","high","critical"]},"confidence":{"type":"number","minimum":0,"maximum":1},"status":{"type":"string","enum":["active","corrected","retracted"]}},"required":["title","severity","confidence","status"]},"summary":{"type":"string"},"abstract":{"type":"string"},"tldr":{"type":"string","maxLength":240},"attackPath":{"type":"array","items":{"type":"string"}},"classification":{"type":"object","properties":{"attack":{"type":"array","items":{"type":"object","properties":{"technique":{"type":"string"},"subTechnique":{"type":"string","description":"Sub-technique ID when applicable (e.g., T1059.001)."},"techniqueName":{"type":"string","description":"Resolved human-readable technique name. Omit when unknown."},"confidence":{"type":"number","minimum":0,"maximum":1},"evidenceRef":{"type":"string","description":"Optional reference to supporting evidence (e.g., passage index or quote id)."}},"description":"ATT&CK technique mapping with confidence. Include techniqueName when resolvable."}},"killChain":{"type":"array","items":{"type":"string","enum":["reconnaissance","weaponization","delivery","exploitation","installation","c2","actions"]},"description":"Relevant kill chain phases demonstrated in the content. Return [] when not evidenced."},"malware":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Malware family/tool name."},"confidence":{"type":"number","minimum":0,"maximum":1},"aliases":{"type":"array","items":{"type":"string"},"description":"Known aliases for the malware family/tool."}},"required":["name"],"description":"Malware identification claim."}},"actor":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Threat actor/group name."},"confidence":{"type":"number","minimum":0,"maximum":1},"aliases":{"type":"array","items":{"type":"string"},"description":"Known aliases for the actor/group."}},"required":["name"],"description":"Threat actor attribution claim."}},"platforms":{"type":"array","items":{"type":"string","enum":["windows","linux","macos","ios","android","aws","gcp","azure","o365","okta","kubernetes"]},"description":"Affected platforms/environments. Return [] when not stated."},"mappings":{"type":"array","items":{"type":"object","properties":{"framework":{"type":"string","description":"Framework name (e.g., NIST, CIS)."},"id":{"type":"string","description":"Framework control/technique identifier."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Optional confidence in mapping in [0,1]."}},"required":["framework","id"],"description":"Mapping to other security frameworks."},"description":"Mappings to other frameworks (e.g., NIST, CIS). Return [] when not applicable."}},"required":["attack","killChain","malware","actor","platforms","mappings"],"description":"Classification including ATT&CK mapping, kill chain phases, actors, malware, and platforms."},"affectedProducts":{"type":"array","items":{"type":"object","properties":{"vendor":{"type":"string"},"product":{"type":"string"},"versions":{"type":"array","items":{"type":"string"},"default":[]},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Optional confidence in product impact in [0,1]."}},"required":["versions"],"description":"Affected vendor/product versions relevant for scoping detections."}},"iocs":{"type":"object","properties":{"ipv4":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"ipv6":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"domains":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"urls":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"hashes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"files":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"registryKeys":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"processes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"certs":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"cloudIds":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}},"mobileIds":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string","description":"Indicator value string as observed."},"normalizedValue":{"type":"string","description":"Optional normalized form (e.g., lowercase domain without trailing dot)."},"firstSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was first observed. Omit when unknown."},"lastSeen":{"type":"string","description":"ISO-8601 timestamp when IOC was last observed. Omit when unknown."},"ttlDays":{"type":"number","description":"Suggested TTL in days (domains≈30, IPs≈7, hashes≈365). Omit when unknown."},"status":{"type":"string","enum":["active","revoked","superseded","expired"]},"confidence":{"type":"number","minimum":0,"maximum":1},"indicatorRole":{"type":"string","enum":["compromise","relevance","reference"],"description":"'compromise' (IOC) for attacker-controlled/attacker-specific artifacts indicative on their own; 'relevance' (IOR) for legitimate/dual-use artifacts the threat uses, abuses, or targets — a match proves environment relevance, never compromise; 'reference' for artifacts that merely locate the reporting (source/reference URLs, publishing platforms, researcher profiles). Missing means legacy data and is treated as 'compromise'."}},"required":["value"],"description":"A single indicator with role (compromise vs. relevance vs. reference), temporal context, and confidence."}}},"description":"Grouped IOCs (read-tolerant)."},"provenance":{"type":"object","properties":{"supportingPassages":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","description":"Exact quoted text supporting a technical claim. Do not paraphrase."},"sourceUrl":{"type":"string","format":"uri","description":"Optional URL if the passage is from a different source."},"charSpan":{"type":"object","properties":{"start":{"type":"number","description":"Start character offset (inclusive) of quoted span within content."},"end":{"type":"number","description":"End character offset (exclusive) of quoted span within the analyzed content."}},"required":["start","end"],"description":"Character span for the quoted passage within the analyzed content."}},"required":["text"],"description":"Supporting evidence passages used to justify extracted claims."},"description":"Evidence snippets grounding technical claims and mappings. Use [] when no precise evidence exists."}},"required":["supportingPassages"],"description":"Provenance information tying claims to exact sources/passages."},"version":{"type":"integer","exclusiveMinimum":0},"lastUpdated":{"type":"string"},"createdAt":{"type":"string"},"addedToFeedAt":{"type":"string"},"canonicalKey":{"type":"string"},"duplicateOf":{"type":"string"},"tenantOverrides":{}},"required":["id","source","event","summary","tldr","attackPath","classification","affectedProducts","iocs","provenance","version"],"description":"Backwards-compatible intel item for read/API responses (tolerates legacy stored shapes)."}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/intel/notification-settings":{"get":{"summary":"Get threat intel notification settings","description":"Retrieve organization-wide threat intel notification settings and available destinations.","tags":["Intel"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/intel/notification-settings\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for threat intel notification settings"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns these settings"},"notifyAllItems":{"type":"boolean","description":"Whether every assessed threat should notify"},"notifyRelevantItems":{"type":"boolean","description":"Whether threats relevant to the environment should notify"},"notifyExposedItems":{"type":"boolean","description":"Whether exposed threats (Hunt Alert created/refreshed) should notify"},"destinationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Destinations for threat intel hunt notifications"},"createdAt":{"type":"string","description":"When the settings were created"},"updatedAt":{"type":"string","description":"When the settings were last updated"}},"required":["id","organizationId","notifyAllItems","notifyRelevantItems","notifyExposedItems","destinationIds","createdAt","updatedAt"],"description":"Organization-wide notification settings for threat intel"},"destinations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"webhook"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication: \"bearer\" for Authorization: Bearer <token>, \"header\" for custom header"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\" (e.g., \"X-API-Key\")"}},"required":["url","authType"]},"token":{"type":"string","description":"The authentication token (only returned to authorized users)"},"hasToken":{"type":"boolean","description":"Whether a token is configured"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"teams"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["url"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"slack"},"config":{"type":"object","properties":{"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"},"configurationRevision":{"type":"integer","minimum":0,"description":"Revision of user-managed Slack delivery configuration"},"blockedChannels":{"type":"object","additionalProperties":{"type":"object","properties":{"reason":{"type":"string","const":"archived","description":"Why delivery to this Slack channel is blocked"},"blockedAt":{"type":"string","description":"When Slack reported that the channel was archived"}},"required":["reason","blockedAt"]},"description":"Channels that delivery will skip until a user updates the destination"}},"required":["channelIds"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"pagerduty"},"config":{"type":"object","properties":{"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts"},"source":{"type":"string","description":"Optional source identifier (defaults to detection name)"}},"required":["severity"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"linear"},"config":{"type":"object","properties":{"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names for display purposes"},"workflowStateId":{"type":"string","minLength":1,"description":"Linear workflow state ID for created issues"},"workflowStateName":{"type":"string","description":"Cached Linear workflow state name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"tines"},"config":{"type":"object","properties":{"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]}]},"description":"Available output destinations for the organization"}},"required":["settings","destinations"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Update threat intel notification settings","description":"Update organization-wide threat intel notification settings.","tags":["Intel"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/intel/notification-settings\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"notifyAllItems\":true,\"notifyRelevantItems\":true,\"notifyExposedItems\":true,\"destinationIds\":[\"string\"]}'"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notifyAllItems":{"type":"boolean","description":"Whether every threat intel item should notify"},"notifyRelevantItems":{"type":"boolean","description":"Whether relevant threat intel items should notify"},"notifyExposedItems":{"type":"boolean","description":"Whether exposed threat intel items should notify"},"destinationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Destinations for threat intel notifications"}},"required":["notifyAllItems","notifyRelevantItems","notifyExposedItems","destinationIds"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"settings":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for threat intel notification settings"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns these settings"},"notifyAllItems":{"type":"boolean","description":"Whether every assessed threat should notify"},"notifyRelevantItems":{"type":"boolean","description":"Whether threats relevant to the environment should notify"},"notifyExposedItems":{"type":"boolean","description":"Whether exposed threats (Hunt Alert created/refreshed) should notify"},"destinationIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Destinations for threat intel hunt notifications"},"createdAt":{"type":"string","description":"When the settings were created"},"updatedAt":{"type":"string","description":"When the settings were last updated"}},"required":["id","organizationId","notifyAllItems","notifyRelevantItems","notifyExposedItems","destinationIds","createdAt","updatedAt"],"description":"Organization-wide notification settings for threat intel"},"destinations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"webhook"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The webhook URL to POST to"},"authType":{"type":"string","enum":["bearer","header"],"description":"Type of authentication: \"bearer\" for Authorization: Bearer <token>, \"header\" for custom header"},"headerName":{"type":"string","description":"Custom header name when authType is \"header\" (e.g., \"X-API-Key\")"}},"required":["url","authType"]},"token":{"type":"string","description":"The authentication token (only returned to authorized users)"},"hasToken":{"type":"boolean","description":"Whether a token is configured"}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"teams"},"config":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The Microsoft Teams workflow webhook URL to POST to"}},"required":["url"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"slack"},"config":{"type":"object","properties":{"channelIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Slack channel IDs to post messages to"},"configurationRevision":{"type":"integer","minimum":0,"description":"Revision of user-managed Slack delivery configuration"},"blockedChannels":{"type":"object","additionalProperties":{"type":"object","properties":{"reason":{"type":"string","const":"archived","description":"Why delivery to this Slack channel is blocked"},"blockedAt":{"type":"string","description":"When Slack reported that the channel was archived"}},"required":["reason","blockedAt"]},"description":"Channels that delivery will skip until a user updates the destination"}},"required":["channelIds"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"pagerduty"},"config":{"type":"object","properties":{"severity":{"type":"string","enum":["critical","error","warning","info"],"description":"Default severity level for alerts"},"source":{"type":"string","description":"Optional source identifier (defaults to detection name)"}},"required":["severity"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"linear"},"config":{"type":"object","properties":{"teamId":{"type":"string","minLength":1,"description":"Linear team ID where issues should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"},"labelIds":{"type":"array","items":{"type":"string"},"description":"Linear label IDs to apply to created issues"},"labelNames":{"type":"array","items":{"type":"string"},"description":"Cached Linear label names for display purposes"},"workflowStateId":{"type":"string","minLength":1,"description":"Linear workflow state ID for created issues"},"workflowStateName":{"type":"string","description":"Cached Linear workflow state name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the destination"},"organizationId":{"type":"string","format":"uuid","description":"Organization that owns this destination"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for this destination"},"createdAt":{"type":"string","description":"When the destination was created"},"updatedAt":{"type":"string","description":"When the destination was last updated"},"type":{"type":"string","const":"tines"},"config":{"type":"object","properties":{"teamId":{"type":"string","pattern":"^\\d+$","description":"Tines team ID where cases should be created"},"teamName":{"type":"string","description":"Cached team name for display purposes"}},"required":["teamId"]}},"required":["id","organizationId","name","createdAt","updatedAt","type","config"]}]},"description":"Available output destinations for the organization"}},"required":["settings","destinations"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/intel/sources":{"get":{"summary":"List intel sources","description":"Lists built-in and custom intel sources for the current organization","tags":["Intel"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/intel/sources\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"description":{"type":["string","null"]},"kind":{"type":"string","enum":["rss","api"]},"apiType":{"type":["string","null"]},"isBuiltIn":{"type":"boolean"},"feedUrl":{"type":["string","null"]},"serverUrl":{"type":["string","null"]},"organizationId":{"type":["string","null"]},"createdBy":{"type":["string","null"]},"hasApiKey":{"type":"boolean"},"enabled":{"type":"boolean"},"sourceEnabled":{"type":"boolean"},"subscriptionEnabled":{"type":"boolean"},"scheduleCron":{"type":["string","null"]},"maxEntries":{"type":"number"},"lastFetchedAt":{"type":["string","null"]},"lastStatus":{"type":["string","null"]},"lastError":{"type":["string","null"]},"itemCountLast24h":{"type":"number"},"syncJob":{"type":["object","null"],"properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["pending","retrying","waiting","in_progress","succeeded","failed","canceled","expired","skipped"]},"queuedAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"updatedAt":{"type":"string"},"attemptCount":{"type":"number"},"error":{"type":["string","null"]}},"required":["jobId","status","queuedAt","startedAt","finishedAt","updatedAt","attemptCount","error"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","displayName","description","kind","apiType","isBuiltIn","feedUrl","serverUrl","organizationId","createdBy","hasApiKey","enabled","sourceEnabled","subscriptionEnabled","scheduleCron","maxEntries","lastFetchedAt","lastStatus","lastError","itemCountLast24h","createdAt","updatedAt"]}}},"required":["sources"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create intel source","description":"Creates a custom RSS, MISP, or TAXII intel source","tags":["Intel"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/intel/sources\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"kind\":\"rss\",\"name\":\"string\",\"feedUrl\":\"string\",\"enabled\":true}'"}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"rss"},"name":{"type":"string","minLength":1,"maxLength":200},"feedUrl":{"type":"string","format":"uri"},"enabled":{"type":"boolean"}},"required":["kind","name","feedUrl"]},{"type":"object","properties":{"kind":{"type":"string","const":"api"},"apiType":{"type":"string","enum":["misp","taxii"]},"name":{"type":"string","minLength":1,"maxLength":200},"serverUrl":{"type":"string","format":"uri"},"apiKey":{"type":"string"},"enabled":{"type":"boolean"}},"required":["kind","apiType","name","serverUrl"]}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"description":{"type":["string","null"]},"kind":{"type":"string","enum":["rss","api"]},"apiType":{"type":["string","null"]},"isBuiltIn":{"type":"boolean"},"feedUrl":{"type":["string","null"]},"serverUrl":{"type":["string","null"]},"organizationId":{"type":["string","null"]},"createdBy":{"type":["string","null"]},"hasApiKey":{"type":"boolean"},"enabled":{"type":"boolean"},"sourceEnabled":{"type":"boolean"},"subscriptionEnabled":{"type":"boolean"},"scheduleCron":{"type":["string","null"]},"maxEntries":{"type":"number"},"lastFetchedAt":{"type":["string","null"]},"lastStatus":{"type":["string","null"]},"lastError":{"type":["string","null"]},"itemCountLast24h":{"type":"number"},"syncJob":{"type":["object","null"],"properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["pending","retrying","waiting","in_progress","succeeded","failed","canceled","expired","skipped"]},"queuedAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"updatedAt":{"type":"string"},"attemptCount":{"type":"number"},"error":{"type":["string","null"]}},"required":["jobId","status","queuedAt","startedAt","finishedAt","updatedAt","attemptCount","error"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","displayName","description","kind","apiType","isBuiltIn","feedUrl","serverUrl","organizationId","createdBy","hasApiKey","enabled","sourceEnabled","subscriptionEnabled","scheduleCron","maxEntries","lastFetchedAt","lastStatus","lastError","itemCountLast24h","createdAt","updatedAt"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/intel/sources/{id}":{"put":{"summary":"Update intel source","description":"Updates a custom intel source or toggles a built-in source subscription","tags":["Intel"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X PUT \"https://app.cotool.ai/api/intel/sources/:id\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"string\",\"feedUrl\":\"string\",\"serverUrl\":\"string\",\"apiKey\":\"string\",\"enabled\":true}'"}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"feedUrl":{"type":"string","format":"uri"},"serverUrl":{"type":"string","format":"uri"},"apiKey":{"type":"string","minLength":1},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"description":{"type":["string","null"]},"kind":{"type":"string","enum":["rss","api"]},"apiType":{"type":["string","null"]},"isBuiltIn":{"type":"boolean"},"feedUrl":{"type":["string","null"]},"serverUrl":{"type":["string","null"]},"organizationId":{"type":["string","null"]},"createdBy":{"type":["string","null"]},"hasApiKey":{"type":"boolean"},"enabled":{"type":"boolean"},"sourceEnabled":{"type":"boolean"},"subscriptionEnabled":{"type":"boolean"},"scheduleCron":{"type":["string","null"]},"maxEntries":{"type":"number"},"lastFetchedAt":{"type":["string","null"]},"lastStatus":{"type":["string","null"]},"lastError":{"type":["string","null"]},"itemCountLast24h":{"type":"number"},"syncJob":{"type":["object","null"],"properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["pending","retrying","waiting","in_progress","succeeded","failed","canceled","expired","skipped"]},"queuedAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"updatedAt":{"type":"string"},"attemptCount":{"type":"number"},"error":{"type":["string","null"]}},"required":["jobId","status","queuedAt","startedAt","finishedAt","updatedAt","attemptCount","error"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","displayName","description","kind","apiType","isBuiltIn","feedUrl","serverUrl","organizationId","createdBy","hasApiKey","enabled","sourceEnabled","subscriptionEnabled","scheduleCron","maxEntries","lastFetchedAt","lastStatus","lastError","itemCountLast24h","createdAt","updatedAt"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete intel source","description":"Deletes a custom intel source and associated intel items","tags":["Intel"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X DELETE \"https://app.cotool.ai/api/intel/sources/:id\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/intel/sources/{id}/sync":{"post":{"summary":"Trigger intel source sync","description":"Enqueues an immediate sync job for a custom intel source","tags":["Intel"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X POST \"https://app.cotool.ai/api/intel/sources/:id/sync\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"description":{"type":["string","null"]},"kind":{"type":"string","enum":["rss","api"]},"apiType":{"type":["string","null"]},"isBuiltIn":{"type":"boolean"},"feedUrl":{"type":["string","null"]},"serverUrl":{"type":["string","null"]},"organizationId":{"type":["string","null"]},"createdBy":{"type":["string","null"]},"hasApiKey":{"type":"boolean"},"enabled":{"type":"boolean"},"sourceEnabled":{"type":"boolean"},"subscriptionEnabled":{"type":"boolean"},"scheduleCron":{"type":["string","null"]},"maxEntries":{"type":"number"},"lastFetchedAt":{"type":["string","null"]},"lastStatus":{"type":["string","null"]},"lastError":{"type":["string","null"]},"itemCountLast24h":{"type":"number"},"syncJob":{"type":["object","null"],"properties":{"jobId":{"type":"string"},"status":{"type":"string","enum":["pending","retrying","waiting","in_progress","succeeded","failed","canceled","expired","skipped"]},"queuedAt":{"type":"string"},"startedAt":{"type":["string","null"]},"finishedAt":{"type":["string","null"]},"updatedAt":{"type":"string"},"attemptCount":{"type":"number"},"error":{"type":["string","null"]}},"required":["jobId","status","queuedAt","startedAt","finishedAt","updatedAt","attemptCount","error"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","displayName","description","kind","apiType","isBuiltIn","feedUrl","serverUrl","organizationId","createdBy","hasApiKey","enabled","sourceEnabled","subscriptionEnabled","scheduleCron","maxEntries","lastFetchedAt","lastStatus","lastError","itemCountLast24h","createdAt","updatedAt"]},"jobId":{"type":"string"}},"required":["source","jobId"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/intel/stats":{"get":{"summary":"Get intel feed statistics","description":"Retrieves aggregated statistics for the threat intelligence feed including severity breakdown, platform breakdown, and recent items","tags":["Intel"],"x-codeSamples":[{"lang":"shell","label":"cURL","source":"curl -X GET \"https://app.cotool.ai/api/intel/stats\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\""}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"totalItems":{"type":"number"},"severityBreakdown":{"type":"object","properties":{"critical":{"type":"number"},"high":{"type":"number"},"medium":{"type":"number"},"low":{"type":"number"},"none":{"type":"number"}},"required":["critical","high","medium","low","none"]},"platformBreakdown":{"type":"object","additionalProperties":{"type":"number"}},"sourcePublishers":{"type":"array","items":{"type":"string"}},"recentItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"severity":{"type":"string"},"publishTime":{"type":"string"}},"required":["id","title","severity","publishTime"]}}},"required":["totalItems","severityBreakdown","platformBreakdown","sourcePublishers","recentItems"]}}}},"400":{"description":"Bad request — input validation failed or the request was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Unauthorized — missing or invalid API key / session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — the authenticated user lacks the required permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API Key authentication for programmatic access. Include your API key in the Authorization header as: `Bearer your_api_key_here`"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]},"ValidationError":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"},"issues":{"type":"array","description":"Detailed validation issues, present when request or response schema validation fails","items":{"type":"object","additionalProperties":true}}},"required":["error"]},"PermissionError":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"},"missingPerms":{"type":"array","description":"Permissions the authenticated user is missing for this operation","items":{"type":"string"}}},"required":["error"]},"ChatEvent":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"chat"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"sender":{"type":"string","enum":["user","assistant"],"description":"Who sent the message"},"messageType":{"type":"string","enum":["text","image","file","tool_result","tool_call"],"description":"Type of message content"},"content":{"type":"string","description":"Message content"},"attachments":{"type":"array","items":{"type":"object","properties":{"fileId":{"type":"string","description":"Unique file identifier"},"fileName":{"type":"string","description":"Original file name"},"size":{"type":"number","description":"File size in bytes"},"objectPath":{"type":"string","description":"Storage path for retrieval"},"fileType":{"type":"string","enum":["image","pdf","spreadsheet","document","presentation","file"],"description":"Semantic file type"},"previewText":{"type":"string","description":"Optional preview text for text files"}},"required":["fileId"]},"description":"Optional message attachments"},"agentInputVersion":{"type":"integer","description":"Version of structured agent input metadata"},"agentInputSourceType":{"type":"string","description":"Source type for structured agent input (e.g. jira_webhook, cron_trigger)"},"agentInputSchemaType":{"type":"string","description":"Human-readable schema classification for structured agent input"},"agentInputHeadline":{"type":"string","description":"Primary summary line for structured agent input"},"agentInputContext":{"type":"string","description":"Secondary context summary for structured agent input"},"agentInputSeverity":{"type":"string","description":"Severity level for structured agent input, when available"},"agentInputLinkLabel":{"type":"string","description":"Label for an external deep-link associated with structured agent input"},"agentInputLinkUrl":{"type":"string","description":"URL for an external deep-link associated with structured agent input"},"agentInputPayload":{"$ref":"#/components/schemas/JsonValue","description":"Normalized structured agent input payload"},"modelAlias":{"description":"Model used for this message"},"toolCalls":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"tool-call"},"toolCallId":{"type":"string","description":"Unique tool call identifier"},"toolName":{"type":"string","description":"Name of the tool being called"},"input":{"description":"Tool arguments"}},"required":["type","toolCallId","toolName"]},"description":"Tool calls made in this message"}},"required":["id","type","timestamp","chatId","sender","messageType","modelAlias"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"liveStatus"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"text":{"type":"string","description":"Status text (e.g., \"Thinking\", \"Planning\")"}},"required":["id","type","timestamp","chatId","text"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"toolUsed"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"toolUseId":{"type":"string","description":"Unique tool use identifier"},"parentToolUseId":{"type":"string","description":"Parent tool use identifier when this tool was invoked by another tool"},"codeModeBlockId":{"type":"string","description":"Code Mode JavaScript block or marimo cell that invoked this tool"},"toolName":{"type":"string","description":"Name of the tool used"},"toolDisplayName":{"type":"string","description":"Display name of the tool"},"briefActionDescription":{"type":"string","description":"Brief description of the action"},"visibleActionInput":{"type":"string","description":"Visible input to the tool"},"status":{"type":"string","enum":["inProgress","success","error"],"description":"Tool execution status"},"noRender":{"type":"boolean","description":"Whether this tool event should stay out of the chat timeline"},"input":{"description":"Tool input data"},"frontendOutput":{"description":"Tool output for frontend display"},"rawOutputUuid":{"type":"string","description":"UUID for raw output retrieval"},"toolResultPart":{"description":"Raw result for LLM"},"agentChatId":{"type":"string","description":"Chat ID where agent execution occurred (for agent tools)"},"slackThread":{"type":"object","properties":{"teamId":{"type":"string","description":"Slack workspace/team ID"},"channelId":{"type":"string","description":"Slack channel ID"},"threadTs":{"type":"string","description":"Thread timestamp (parent message ts)"}},"required":["teamId","channelId","threadTs"],"description":"Slack thread metadata for linking this tool call to a Slack thread"}},"required":["id","type","timestamp","chatId","toolUseId","toolName","toolDisplayName","briefActionDescription","status"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"toolUseConfirmation"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"toolName":{"type":"string","description":"Name of the tool requiring confirmation"},"toolDescription":{"type":"string","description":"Description of the tool"},"uuid":{"type":"string","description":"Confirmation UUID"},"input":{"description":"Tool input data"},"toolDisplayName":{"type":"string","description":"Display name of the tool"},"briefActionDescription":{"type":"string","description":"Brief description of the action"}},"required":["id","type","timestamp","chatId","toolName","toolDescription","uuid"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"waitingForUserResponse"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"toolName":{"type":"string","description":"Name of the tool that is waiting"},"toolCallId":{"type":"string","description":"The AI SDK tool call ID"},"toolEventId":{"type":"string","description":"The tool event ID for updates"},"toolUseId":{"type":"string","description":"The unique tool use ID"},"message":{"type":"string","description":"The message/question being asked"},"buttonLabels":{"type":"array","items":{"type":"string"},"description":"Labels for the response buttons"},"slackChannelId":{"type":"string","description":"Slack channel ID if message was sent to Slack"},"slackMessageTs":{"type":"string","description":"Slack message timestamp if message was sent to Slack"},"promptStatus":{"type":"string","enum":["pending","resolved","cancelled"],"description":"Current status of the waiting prompt"},"selectedLabel":{"type":"string","description":"The label that was selected (when resolved)"},"answeredBy":{"type":"string","enum":["slack","ui","timeout"],"description":"How the prompt was resolved: a response from Slack or the UI, or `timeout` when it elapsed with no user response (mirrors the timed-wait event's resolvedBy discriminator)."},"slackUserId":{"type":"string","description":"Slack user ID of responder if answered via Slack"}},"required":["id","type","timestamp","chatId","toolName","toolCallId","toolEventId","toolUseId","message","buttonLabels","promptStatus"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"timedWait"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"toolName":{"type":"string","description":"Name of the wait tool"},"toolCallId":{"type":"string","description":"The AI SDK tool call ID"},"toolEventId":{"type":"string","description":"The tool event ID for updates"},"toolUseId":{"type":"string","description":"The unique tool use ID"},"waitSeconds":{"type":"integer","minimum":60,"maximum":86400,"description":"Requested wait duration in seconds"},"resumeAtTimestamp":{"type":"number","description":"Unix timestamp in milliseconds when the wait should resume"},"waitStatus":{"type":"string","enum":["pending","completed","cancelled"],"description":"Current status of the timed wait"},"resolvedBy":{"type":"string","enum":["timer","user"],"description":"How the wait finished"}},"required":["id","type","timestamp","chatId","toolName","toolCallId","toolEventId","toolUseId","waitSeconds","resumeAtTimestamp","waitStatus"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"statusUpdate"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"agentStatus":{"type":"string","enum":["planning","warning","executing","error","completed","idle"],"description":"Current agent status"},"brief":{"type":"string","description":"Brief status summary"},"description":{"type":"string","description":"Detailed status description"},"planStepId":{"type":"string","description":"Associated plan step ID"},"noRender":{"type":"boolean","description":"UI rendering hint"},"slackThread":{"type":"object","properties":{"teamId":{"type":"string","description":"Slack workspace/team ID"},"channelId":{"type":"string","description":"Slack channel ID"},"threadTs":{"type":"string","description":"Thread timestamp (parent message ts)"}},"required":["teamId","channelId","threadTs"],"description":"Slack thread metadata linking this chat to a Slack thread for re-entry lookup"}},"required":["id","type","timestamp","chatId","agentStatus","brief"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"structuredOutputStatus"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"status":{"type":"string","enum":["pending","generating","ready","error"],"description":"Current status of structured output generation"},"error":{"type":"string","description":"Error information when generation fails"},"output":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/JsonValue"},"schema":{"$ref":"#/components/schemas/CotoolJsonSchema"}},"description":"The structured output result and schema when ready"}},"required":["id","type","timestamp","chatId","status"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"chatChunk"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"sender":{"type":"string","const":"assistant","description":"Always assistant for streaming"},"chunk":{"type":"string","description":"Text chunk delta"},"position":{"type":"number","description":"Chunk position in overall content"},"modelAlias":{"description":"Model alias for the chunk"},"isReasoning":{"type":"boolean","description":"Whether this is a reasoning chunk"}},"required":["id","type","timestamp","chatId","sender","chunk","position"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"reportChunk"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"position":{"type":"number","description":"Chunk position in report"},"content":{"type":"string","description":"Report chunk content"}},"required":["id","type","timestamp","chatId","position","content"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"reportComplete"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"content":{"type":"string","description":"Complete report content"}},"required":["id","type","timestamp","chatId","content"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"reportError"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"content":{"type":"string","description":"Error message"}},"required":["id","type","timestamp","chatId","content"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"artifact"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"artifactId":{"type":"string","description":"Unique artifact identifier"},"artifactType":{"type":"string","enum":["markdown-file","file","image","pdf","spreadsheet"],"description":"Type of artifact"},"title":{"type":"string","description":"Artifact title"},"description":{"type":"string","description":"Artifact description"},"docStoreKeyStr":{"type":"string","description":"Document store key for retrieval"},"isReport":{"type":"boolean","description":"Whether this is a report artifact"},"previewText":{"type":"string","description":"Content preview"},"metadata":{"type":"object","additionalProperties":{},"description":"Additional metadata"},"fileName":{"type":"string","description":"Original file name if this is a file-based artifact"},"mimeType":{"type":"string","description":"MIME type for file-based artifacts"},"size":{"type":"number","description":"File size in bytes for file-based artifacts"}},"required":["id","type","timestamp","chatId","artifactId","artifactType","title","docStoreKeyStr"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"artifactUpdate"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"artifactId":{"type":"string","description":"Artifact being updated"},"artifactType":{"type":"string","enum":["markdown-file","file","image","pdf","spreadsheet"],"description":"Type of artifact"},"title":{"type":"string","description":"Updated artifact title"},"description":{"type":"string","description":"Updated artifact description"},"isReport":{"type":"boolean","description":"Whether this is a report artifact"},"previewText":{"type":"string","description":"Updated content preview"},"metadata":{"type":"object","additionalProperties":{},"description":"Updated metadata"},"fileName":{"type":"string","description":"Original file name if this is a file-based artifact"},"mimeType":{"type":"string","description":"MIME type for file-based artifacts"},"size":{"type":"number","description":"File size in bytes for file-based artifacts"}},"required":["id","type","timestamp","chatId","artifactId","artifactType","title"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"reasoningMessage"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"sender":{"type":"string","const":"assistant","description":"Always assistant for reasoning"},"content":{"type":"string","description":"Reasoning content"},"modelAlias":{"description":"Model that generated the reasoning"},"signature":{"type":"string","description":"Reasoning signature"},"metadata":{"type":"object","properties":{"openai":{"type":"object","properties":{"itemId":{"type":"string","description":"OpenAI Responses reasoning item ID"},"reasoningEncryptedContent":{"type":["string","null"],"description":"Opaque encrypted OpenAI reasoning state"}}}},"description":"Provider state required to continue reasoning across model turns"}},"required":["id","type","timestamp","chatId","sender","content"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"compactionStarted"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"modelAlias":{"description":"Model alias used for compaction"},"trigger":{"type":"string","enum":["automatic","manual"],"description":"Whether compaction was automatic or user-requested"},"beforeMessages":{"type":"integer","minimum":0,"description":"Model messages before compaction"}},"required":["id","type","timestamp","chatId"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"compactionFinished"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"content":{"type":"string","description":"Hidden compacted context payload used to reconstruct future model history"},"modelAlias":{"description":"Model alias that produced the compacted payload"},"trigger":{"type":"string","enum":["automatic","manual"],"description":"Whether compaction was automatic or user-requested"},"completedAt":{"type":"number","description":"Wall-clock completion time when timestamp is backdated for history replay"},"metadata":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","const":"anthropic"}},"required":["provider"]},{"type":"object","properties":{"provider":{"type":"string","const":"openai"},"itemId":{"type":"string","description":"Opaque OpenAI compaction item identifier"},"encryptedContent":{"type":"string","description":"Opaque encrypted OpenAI compaction state"}},"required":["provider","itemId"]}],"description":"Provider-native state required to resume from this compaction"},"stats":{"type":"object","properties":{"beforeTokens":{"type":"integer","minimum":0,"description":"Estimated context tokens before compaction"},"afterTokens":{"type":"integer","minimum":0,"description":"Estimated context tokens after compaction"},"savedTokens":{"type":"integer","minimum":0,"description":"Estimated tokens removed by compaction"},"reductionPercentage":{"type":"number","minimum":0,"maximum":100,"description":"Estimated percentage reduction in context tokens"},"beforeMessages":{"type":"integer","minimum":0,"description":"Model messages before compaction"},"afterMessages":{"type":"integer","minimum":0,"description":"Model messages after compaction"}},"required":["beforeTokens","afterTokens","savedTokens","reductionPercentage","beforeMessages","afterMessages"],"description":"Estimated context size before and after compaction"},"status":{"type":"string","const":"error","description":"Marks a started compaction that did not produce reusable state"},"description":{"type":"string","description":"User-facing explanation when compaction fails"}},"required":["id","type","timestamp","chatId","content"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"tokenUsage"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"modelAlias":{"description":"Model for which usage is tracked"},"inputTokens":{"type":"number","description":"Tokens used for prompt in this turn"},"outputTokens":{"type":"number","description":"Tokens used for completion in this turn"},"totalTokens":{"type":"number","description":"Total tokens used in this turn"},"inputTokensCumulative":{"type":"number","description":"Cumulative prompt tokens"},"outputTokensCumulative":{"type":"number","description":"Cumulative completion tokens"},"totalTokensCumulative":{"type":"number","description":"Cumulative total tokens"},"loop":{"type":"number","description":"Turn/loop number that produced this usage"}},"required":["id","type","timestamp","chatId","modelAlias","inputTokens","outputTokens","totalTokens","inputTokensCumulative","outputTokensCumulative","totalTokensCumulative","loop"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"tokenUsageV2"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"modelAlias":{"description":"Model for which usage is tracked"},"totalTokens":{"type":"number","description":"The estimated context occupancy for the next model turn. This is not cumulative usage across the agent run."},"contextManagedInputTokens":{"type":"number","description":"The provider-reported input tokens for the current model turn, including cached input exactly once."},"contextManagedOutputTokens":{"type":"number","description":"The provider-reported output tokens generated by the current model turn."},"contextManagedTotalTokens":{"type":"number","description":"The provider-reported input plus output tokens, used to estimate context occupancy for the next model turn."},"loop":{"type":"number","description":"Turn/loop number that produced this usage"}},"required":["id","type","timestamp","chatId","modelAlias","totalTokens","contextManagedInputTokens","contextManagedOutputTokens","contextManagedTotalTokens","loop"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"parseError"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"content":{"type":"string","description":"Error content"},"modelAlias":{"description":"Model alias that produced the error"}},"required":["id","type","timestamp","chatId","content","modelAlias"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"userFileUploaded"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"fileId":{"type":"string","description":"Unique file identifier"},"fileName":{"type":"string","description":"Original file name"},"mimeType":{"type":"string","description":"MIME type of the file"},"size":{"type":"number","description":"File size in bytes"},"fileType":{"type":"string","enum":["image","pdf","spreadsheet","document","presentation","file"],"description":"Type of file"},"objectPath":{"type":"string","description":"Storage path for file retrieval"},"previewText":{"type":"string","description":"Content preview for text files"},"metadata":{"type":"object","additionalProperties":{},"description":"Additional file metadata"}},"required":["id","type","timestamp","chatId"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"chatTitleChanged"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"title":{"type":"string","description":"New chat title"},"previousTitle":{"type":"string","description":"Previous title if available"}},"required":["id","type","timestamp","chatId","title"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"codeDetectionInterpretationStale"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"reason":{"type":"string","enum":["stale","changed"],"description":"Whether notebook edits made the current interpretation stale or a refreshed interpretation is now available"},"revision":{"type":"string","description":"Notebook revision associated with the staleness or refreshed interpretation"},"staleStepIds":{"type":"array","items":{"type":"string"},"description":"Interpretation steps whose cells changed for stale events; empty when the whole view is stale or the interpretation changed"},"structural":{"type":"boolean","description":"Whether the update should render as a structural workflow change"}},"required":["id","type","timestamp","chatId","reason","revision","staleStepIds","structural"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"codeDetectionCellExecutionProgress"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"cellHash":{"type":"string","description":"Content hash of the notebook cell that started executing"},"runId":{"type":"string","description":"Identity of the run this progress belongs to; matches the runId of the corresponding codeDetectionRunStarted event. Optional only for events persisted before run identity existed."}},"required":["id","type","timestamp","chatId","cellHash"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"codeDetectionRunStarted"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"runStartedAt":{"type":"number","description":"Epoch ms the run started; correlates progress and completion events"},"runId":{"type":"string","description":"Identity shared by this run's start, progress, and completion events so overlapping runs cannot cross-contaminate. Optional only for events persisted before run identity existed."}},"required":["id","type","timestamp","chatId","runStartedAt"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"codeDetectionRunCompleted"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"runStartedAt":{"type":"number","description":"Epoch ms the run started; matches the corresponding codeDetectionRunStarted event"},"runId":{"type":"string","description":"Identity of the run that completed; matches the runId of the corresponding codeDetectionRunStarted event. Optional only for events persisted before run identity existed."},"execution":{"type":"object","properties":{"revision":{"type":"string","description":"Executed notebook revision"},"returnCode":{"type":"integer"},"stdout":{"type":"string"},"stderr":{"type":"string"},"results":{"type":["array","null"],"items":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"description":"Rows the notebook passed to emit_results(), or null when it never called it"},"executionId":{"type":["string","null"],"format":"uuid","description":"Persisted execution identity, or null when the editor run has no detection record"},"executionTimeMs":{"type":"integer","minimum":0}},"required":["revision","returnCode","stdout","stderr","results","executionTimeMs"],"additionalProperties":false,"description":"Run outcome in the same shape as a panel-initiated run response"}},"required":["id","type","timestamp","chatId","runStartedAt","execution"]},{"type":"object","properties":{"id":{"type":"string","description":"Unique event identifier"},"type":{"type":"string","const":"codeDetectionEditorUrlChanged"},"timestamp":{"type":"number","description":"Event timestamp"},"chatId":{"type":"string","description":"Chat ID this event belongs to"},"editorUrl":{"type":"string","description":"Tunnel URL of the recreated notebook editor"}},"required":["id","type","timestamp","chatId","editorUrl"]}],"description":"A chat event that can be one of many types: chat messages, tool usage, status updates, artifacts, etc. Each event has a discriminator field \"type\" that determines its structure."},"JsonValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/components/schemas/JsonValue"}},{"type":"object","additionalProperties":{"$ref":"#/components/schemas/JsonValue"}}],"description":"A JSON value (string, number, boolean, null, array, or object)"},"CotoolJsonSchema":{"type":"object","properties":{"type":{"type":"string","enum":["string","number","boolean","null","object","array"]},"title":{"type":"string"},"description":{"type":"string"},"properties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CotoolJsonSchema"}},"items":{"$ref":"#/components/schemas/CotoolJsonSchema"},"minItems":{"type":"integer","minimum":0},"maxItems":{"type":"integer","minimum":0},"required":{"type":"array","items":{"type":"string"}},"enum":{"type":"array","items":{"type":"string"}},"additionalProperties":{"type":"boolean"},"x-cotool":{"type":"object","properties":{"presetId":{"type":"string","enum":["classification","markdown","templatedReport","toolCallEvidence"]},"viewerId":{"type":"string"}},"additionalProperties":{"$ref":"#/components/schemas/JsonValue"}}},"required":["type"],"description":"A JSON Schema definition with Cotool-specific extensions for structured output presets"},"Chat":{"type":"object","properties":{"id":{"type":"string","description":"Unique chat identifier"},"userId":{"type":["string","null"],"description":"User who owns this chat (null for agent or detection chats)"},"agentId":{"type":["string","null"],"description":"Agent who owns this chat (null for user or detection chats)"},"detectionId":{"type":["string","null"],"description":"Detection this chat belongs to (null for user or agent chats)"},"parentChatId":{"type":["string","null"],"description":"Parent chat for nested sub-agent chats (null for top-level chats)"},"organizationId":{"type":"string","description":"Organization this chat belongs to"},"title":{"type":["string","null"],"description":"Chat title"},"createdAt":{"type":"string","description":"When the chat was created","format":"date-time","example":"2025-06-17T12:34:56.789Z"},"updatedAt":{"type":"string","description":"When the chat was last updated","format":"date-time","example":"2025-06-17T12:34:56.789Z"},"experience":{"type":"string","enum":["chat","write-detection"],"description":"The type of chat experience. Default is \"chat\"."},"detectionPlatform":{"type":["string","null"],"enum":["panther","sublime","scanner","datadog","splunk","sentinelone","microsoftsentinel","elastic","sumologic","runreveal",null],"description":"The detection platform for write-detection chats (e.g., scanner, splunk, panther). Null for regular chats."},"command":{"type":["string","null"],"enum":["create-agent","create-detection-agent","create-response-agent","create-skill","hunt-intel","tune-detection","update-detection-agent","update-response-agent","update-skill",null],"description":"Slash command that started this chat (e.g., create-response-agent). Null for regular chats."},"codeDetectionId":{"type":["string","null"],"format":"uuid","description":"Code detection this chat is bound to, for Code Mode editor/tuning sessions. Null for regular chats."},"codeDetectionSessionMode":{"type":["string","null"],"enum":["editor","tuning",null],"description":"How this chat relates to its bound code detection: freeform editing or feedback-driven tuning. Detection-bound chats open in the Code Mode layout."},"modelAlias":{"description":"Model alias used for this chat. Must be a valid model from the registry: auto:chat:default, anthropic:chat:sonnet-5, anthropic:chat:sonnet-4.6, anthropic:chat:sonnet-4.5, anthropic:chat:opus-5, anthropic:chat:opus-4.8, anthropic:chat:opus-4.6, anthropic:chat:opus-4.5, anthropic:chat:latest-no-reasoning, anthropic:chat:latest, anthropic:chat:opus-4.1, anthropic:chat:opus, google:chat:latest, openai:chat:gpt-5.6-sol, openai:chat:gpt-5.6-terra, openai:chat:gpt-5.6-luna, openai:chat:gpt-5.5, openai:chat:gpt-5.4, openai:chat:gpt-5.3-codex, openai:chat:gpt-5.2-codex, openai:chat:gpt-5.2, openai:chat:gpt-5.1, openai:chat:gpt-5, openai:chat:latest, openai:chat:4o, openai:chat:o3, fireworks:chat:glm-5.3, fireworks:chat:glm-5.3-flash, fireworks:chat:glm-5.2, fireworks:chat:glm-5.2-fast, fireworks:chat:deepseek-v4-pro, fireworks:chat:deepseek-v4-flash, fireworks:chat:kimi-k3, fireworks:chat:kimi-k2.7-code, fireworks:chat:kimi-k2.6, fireworks:chat:minimax-m3, fireworks:chat:qwen3.7-plus"},"triggerId":{"type":["string","null"],"description":"ID of the trigger that created this chat"},"triggerName":{"type":["string","null"],"description":"Name of the trigger"},"triggerSource":{"type":["string","null"],"description":"Source of the trigger (e.g., api, manual, jira, cron, slack)"},"triggerDescription":{"type":["string","null"],"description":"Description of the trigger"},"linearOrganizationId":{"type":["string","null"],"description":"Linear workspace bound to this chat for Agent Session re-entry"},"linearIssueId":{"type":["string","null"],"description":"Linear issue used while reserving an API-created Agent Session"},"linearAgentSessionId":{"type":["string","null"],"description":"Linear Agent Session bound to this chat for follow-up routing"},"status":{"type":"string","enum":["queued","running","waiting","done","error","interrupted"],"description":"Chat execution status: queued (created but not yet claimed), running (actively executing), waiting (awaiting user response), done (completed), error (failed), interrupted (stopped by user)"},"statusMessage":{"type":["string","null"],"description":"Additional status context, typically error messages for error status or waiting prompt details"},"result":{"oneOf":[{"$ref":"#/components/schemas/JsonValue"},{"type":"null"}],"description":"Structured chat result data that matches the agent schema"},"structuredOutputSchema":{"oneOf":[{"$ref":"#/components/schemas/CotoolJsonSchema"},{"type":"null"}],"description":"The schema used to generate the structured output result"},"shareToken":{"type":["string","null"],"format":"uuid","description":"Share token for this chat (null if not shared)"},"isPinned":{"type":"boolean","description":"Whether the chat is pinned by its owner. Pinned chats appear in a dedicated section in the sidebar."},"evalScore":{"type":["number","null"],"description":"LLM judge evaluation score (0-100)"},"evalExplanation":{"type":["string","null"],"description":"Explanation for the evaluation score"},"evalBulletSummary":{"type":["array","null"],"items":{"type":"string"},"description":"Bullet point summary of the evaluation"},"criticalIssue":{"type":["object","null"],"properties":{"category":{"type":"string","enum":["authentication","connectivity","missing_data","permission","configuration","service_unavailable","content_filter"],"description":"Category of the critical issue (see: authentication, connectivity, missing_data, permission, configuration, service_unavailable)"},"explanation":{"type":"string","description":"One sentence explaining what went wrong"}},"required":["category","explanation"],"description":"Critical external blocker detected by LLM judge evaluation"},"acceptanceCriteriaResults":{"type":["array","null"],"items":{"type":"object","properties":{"criterion":{"type":"string","description":"The acceptance criterion being evaluated"},"met":{"type":"boolean","description":"Whether the agent run satisfied this acceptance criterion"},"explanation":{"type":"string","description":"Brief explanation of why the criterion was or was not met"}},"required":["criterion","met","explanation"]},"description":"Per-criterion acceptance criteria evaluation results from the LLM judge"}},"required":["id","organizationId","title","createdAt","updatedAt","experience","modelAlias","status"],"description":"A chat conversation between a user/agent and the AI system"},"JsonObject":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"description":"A JSON object whose values are valid JSON values"}}}}