# Cotool Documentation - [Introduction](https://docs.cotool.ai/index.md) - [Getting Started](https://docs.cotool.ai/getting-started.md): Get up and running with Cotool in under 15 minutes - [What is an Agent?](https://docs.cotool.ai/core-concepts/what-is-an-agent.md): Understanding AI agents in Cotool - [Tools and Integrations](https://docs.cotool.ai/core-concepts/tools-and-integrations.md): How tools power your AI agents - [System Prompts](https://docs.cotool.ai/core-concepts/system-prompts.md): Writing effective prompts for your agents - [Using Chat](https://docs.cotool.ai/chat/using-chat.md): Interactive chat interface for ad-hoc investigations - [File Attachments](https://docs.cotool.ai/chat/file-attachments.md): Attach images, PDFs, and documents to your chat messages - [Creating Agents from Chat](https://docs.cotool.ai/chat/creating-agents-from-chat.md): Convert successful chat conversations into reusable agents - [Generating Reports](https://docs.cotool.ai/chat/generating-reports.md): Create formatted reports from chat conversations - [Creating Agents](https://docs.cotool.ai/agents/creating-agents.md): Step-by-step guide to creating your first agent - [Response Agents as Code](https://docs.cotool.ai/agents/response-agents-as-code.md): Manage response agents as YAML in your own GitHub repo, synced automatically into Cotool - [Skills](https://docs.cotool.ai/agents/skills.md): Reusable instructions and resources you can attach across agents - [Agent Filesystem](https://docs.cotool.ai/agents/agent-filesystem.md): Keep an agent's files and workspace between runs - [Triggering Agents](https://docs.cotool.ai/agents/triggering-agents.md): Understanding all trigger types and when to use them - [Context Documents](https://docs.cotool.ai/agents/context-documents.md): Providing agents with context from Google Docs and Notion - [Planning Modes](https://docs.cotool.ai/agents/planning-modes.md): Understanding agent planning strategies - [Agent Outputs](https://docs.cotool.ai/agents/structured-outputs.md): Define structured JSON schemas for consistent agent output - [Alerts](https://docs.cotool.ai/alerts/overview.md): Track security work from detection through triage and disposition - [Working Alerts](https://docs.cotool.ai/alerts/working-alerts.md): Investigate alerts, start response-agent triage, and record dispositions - [Alert Routing](https://docs.cotool.ai/alerts/routing.md): Route detection and trigger-created alerts to response agents - [Hunt](https://docs.cotool.ai/hunt/overview.md): Turn threat intelligence into tracked threats, exposure assessments, and Hunt alerts - [Detections Overview](https://docs.cotool.ai/detections/overview.md): Comprehensive detection management across your security stack - [MITRE Coverage Mapping](https://docs.cotool.ai/detections/mitre-mapping.md): Unified detection coverage across your entire security stack - [Cotool Detection Authoring](https://docs.cotool.ai/detections/detection-authoring.md): Iteratively craft production-ready detections with Cotool assistance - [Pattern-Based Detection with Agents](https://docs.cotool.ai/detections/pattern-based-detection.md): Detect threats using behavioral analysis beyond rigid rule-based logic - [Automatic Evaluations](https://docs.cotool.ai/improving-agents/evaluations.md): Every agent run is automatically scored to identify improvement opportunities - [Acceptance Criteria](https://docs.cotool.ai/improving-agents/acceptance-criteria.md): Define pass/fail conditions that are checked on every agent run - [AI-Suggested Improvements](https://docs.cotool.ai/improving-agents/ai-suggested-improvements.md): Automatic prompt improvements based on evaluation results - [Agent Versioning](https://docs.cotool.ai/improving-agents/system-prompt-versioning.md): Track changes to the whole agent definition, diff versions, and restore previous ones - [Manual Feedback](https://docs.cotool.ai/improving-agents/feedback-system.md): Supplement automatic evaluations with manual user feedback - [Audit Logs](https://docs.cotool.ai/settings/audit-logs.md): Track all activity with comprehensive audit logging - [Audit Event Reference](https://docs.cotool.ai/settings/audit-log-events.md): Every event type the Cotool audit log can record - [Roles & Permissions Overview](https://docs.cotool.ai/settings/roles-permissions-overview.md): Understanding role-based access control in Cotool - [Managing Roles & Users](https://docs.cotool.ai/settings/managing-roles.md): How to create custom roles, assign permissions, and manage user access - [SSO](https://docs.cotool.ai/settings/sso.md): Single Sign-On configuration for enterprise authentication - [Integrations Overview](https://docs.cotool.ai/integrations/overview.md): Connect Cotool to 40+ security and productivity tools - [SAML and SCIM IdP setup](https://docs.cotool.ai/integrations/identity/saml-scim.md): Public endpoint reference for configuring Cotool in identity providers such as Okta - [Okta Integration](https://docs.cotool.ai/integrations/identity/okta.md): Connect Cotool to Okta for identity and access management - [Microsoft Graph Admin Integration](https://docs.cotool.ai/integrations/identity/microsoft-graph-admin.md): Connect Cotool to Microsoft Graph with tenant-wide admin consent for Entra ID and Microsoft 365 investigations - [Slack Integration](https://docs.cotool.ai/integrations/communication/slack.md): Connect Cotool to Slack for team communication and agent triggers - [Linear Integration](https://docs.cotool.ai/integrations/ticketing/linear.md): Connect Cotool to Linear for issue tracking and AI agent sessions - [Zscaler Integration](https://docs.cotool.ai/integrations/security-tools/network/zscaler.md): Connect Cotool to Zscaler for ZIA, ZPA, ZDX, and Client Connector access, detection-rule sync, and alert-driven response agents - [Azure Event Hub Integration](https://docs.cotool.ai/integrations/security-tools/siem/azure-event-hub.md): Stream Azure Activity Logs, resource diagnostic logs, Entra ID diagnostic logs, and Defender for Cloud alerts into Cotool Logs - [GitHub Integration](https://docs.cotool.ai/integrations/dev-tools/github.md): Connect Cotool to GitHub for repository access and Response Agents as Code sync - [IPinfo IP Enrichment](https://docs.cotool.ai/integrations/threat-intel/ipinfo.md): Ingest-time IP geolocation and ASN enrichment for Cotool Logs, powered by IPinfo - [API Overview](https://docs.cotool.ai/api-reference/introduction.md): Authenticate, understand responses, and find the endpoints for common integrations - [List detection rule proposals](https://docs.cotool.ai/api-reference/detection-rules/list-detection-rule-proposals.md): Retrieve all detection rule proposals for the organization. - [Get a detection rule proposal](https://docs.cotool.ai/api-reference/detection-rules/get-a-detection-rule-proposal.md): Retrieve a specific detection rule proposal by ID. - [Dismiss a detection rule proposal](https://docs.cotool.ai/api-reference/detection-rules/dismiss-a-detection-rule-proposal.md): Mark a proposal as dismissed so it won't be shown again. - [Restore a dismissed detection rule proposal](https://docs.cotool.ai/api-reference/detection-rules/restore-a-dismissed-detection-rule-proposal.md): Restore a previously dismissed proposal back to proposed status. - [Test a detection query](https://docs.cotool.ai/api-reference/detection-rules/test-a-detection-query.md): Execute a detection query and return sample results. Uses limited time range and row count. - [Execute a detection query](https://docs.cotool.ai/api-reference/detection-rules/execute-a-detection-query.md): Execute an ad-hoc detection query against a connected SIEM platform. Returns sample results. - [Get publishing options for a platform](https://docs.cotool.ai/api-reference/detection-rules/get-publishing-options-for-a-platform.md): Returns the available publishing methods for a given SIEM platform. - [List available GitHub repositories](https://docs.cotool.ai/api-reference/detection-rules/list-available-github-repositories.md): List GitHub repositories accessible for creating detection PRs. - [Smart publish detection to GitHub (SSE)](https://docs.cotool.ai/api-reference/detection-rules/smart-publish-detection-to-github-sse.md): Uses an AI agent to find the best repo, adapt the detection format, and create a PR. Streams progress via SSE. Optionally pass a draft to publish instead of the original proposal. - [Smart deploy detection to native platform (SSE)](https://docs.cotool.ai/api-reference/detection-rules/smart-deploy-detection-to-native-platform-sse.md): Uses an AI agent to deploy a detection directly to the SIEM platform with appropriate parameters. Streams progress via SSE. Optionally pass a draft to deploy instead of the original proposal. - [Create a detection authoring draft](https://docs.cotool.ai/api-reference/detection-authoring/create-a-detection-authoring-draft.md): Creates a new per-chat draft for detection authoring. If proposalId is provided, copies fields from the proposal. Otherwise creates a blank draft for the given platform. - [Get a detection authoring draft](https://docs.cotool.ai/api-reference/detection-authoring/get-a-detection-authoring-draft.md): Retrieves an existing draft by chat ID. - [Update a detection authoring draft](https://docs.cotool.ai/api-reference/detection-authoring/update-a-detection-authoring-draft.md): Updates an existing draft with new field values. - [Smart publish a draft detection to GitHub](https://docs.cotool.ai/api-reference/detection-authoring/smart-publish-a-draft-detection-to-github.md): Uses an AI agent to create a GitHub PR for a draft detection (no source proposal required). - [Smart deploy a draft detection to a SIEM platform](https://docs.cotool.ai/api-reference/detection-authoring/smart-deploy-a-draft-detection-to-a-siem-platform.md): Uses an AI agent to deploy a draft detection directly to the native SIEM (no source proposal required). - [Bulk toggle trigger alert creation](https://docs.cotool.ai/api-reference/agent-triggers/bulk-toggle-trigger-alert-creation.md): Enable or disable alert creation for every trigger belonging to each of the supplied response agents. - [List agent triggers](https://docs.cotool.ai/api-reference/agent-triggers/list-agent-triggers.md): Retrieve all triggers configured for a specific agent. - [Retrieve an agent trigger secret](https://docs.cotool.ai/api-reference/agent-triggers/retrieve-an-agent-trigger-secret.md): Retrieve a trigger signing secret. Requires edit access to the owning agent. - [Update trigger status](https://docs.cotool.ai/api-reference/agent-triggers/update-trigger-status.md): Enable or disable a trigger for the specified agent. - [Update trigger definition](https://docs.cotool.ai/api-reference/agent-triggers/update-trigger-definition.md): Modify metadata or configuration of an existing trigger. - [Delete trigger](https://docs.cotool.ai/api-reference/agent-triggers/delete-trigger.md): Delete an existing trigger from an agent. - [Get webhook fields](https://docs.cotool.ai/api-reference/agent-triggers/get-webhook-fields.md): Generate a webhook URL, secret, and any additional fields required to configure an external webhook for a trigger. - [Save trigger definition](https://docs.cotool.ai/api-reference/agent-triggers/save-trigger-definition.md): Create and save a new trigger definition for Jira, Jira Automation, Slack, Linear, Cron, generic Webhook, or HackerOne sources. - [Webhook trigger](https://docs.cotool.ai/api-reference/agent-triggers/webhook-trigger.md): Invoke an agent trigger via incoming webhook. External services post to this endpoint. - [Email webhook](https://docs.cotool.ai/api-reference/agent-triggers/email-webhook.md): Receives email events forwarded from Cloudflare Email Worker with env-var HMAC auth. - [Move trigger to another agent](https://docs.cotool.ai/api-reference/agent-triggers/move-trigger-to-another-agent.md): 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. - [Get webhook fields for a trigger source](https://docs.cotool.ai/api-reference/agent-triggers/get-webhook-fields-for-a-trigger-source.md): Generate a webhook URL, secret, and any additional fields required to configure an external webhook, before the trigger is assigned to an agent. - [Update trigger event mode](https://docs.cotool.ai/api-reference/agent-triggers/update-trigger-event-mode.md): Set whether a trigger creates an alert before running the agent or runs the agent directly. - [Get chat history](https://docs.cotool.ai/api-reference/chat/get-chat-history.md): 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`. - [Get chat metadata](https://docs.cotool.ai/api-reference/chat/get-chat-metadata.md): 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. - [Interrupt chat](https://docs.cotool.ai/api-reference/chat/interrupt-chat.md): Send an interrupt signal to stop an ongoing chat stream. - [Answer a waiting prompt](https://docs.cotool.ai/api-reference/chat/answer-a-waiting-prompt.md): Submit a response to a waiting user prompt (e.g., from a Slack button prompt). This allows answering from the UI instead of Slack. - [Cancel a waiting prompt](https://docs.cotool.ai/api-reference/chat/cancel-a-waiting-prompt.md): Cancel a waiting user response prompt (e.g., from a Slack button prompt). This ends the agent run gracefully. - [Override a timed wait](https://docs.cotool.ai/api-reference/chat/override-a-timed-wait.md): Cancel a pending native wait timer and resume execution immediately. - [List chats](https://docs.cotool.ai/api-reference/chat/list-chats.md): Retrieve a paginated list of chats for the current user or agent. - [Submit thumbs feedback for a chat](https://docs.cotool.ai/api-reference/chat/submit-thumbs-feedback-for-a-chat.md): Records a thumbs up/down for a chat if the user has access to it. - [Delete chat](https://docs.cotool.ai/api-reference/chat/delete-chat.md): Delete a chat conversation by its unique identifier. - [Run agent asynchronously](https://docs.cotool.ai/api-reference/agents/run-agent-asynchronously.md): 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. - [Get async run status](https://docs.cotool.ai/api-reference/agents/get-async-run-status.md): > ⚠️ **Deprecated** > Updated our Chat Schema > **Use instead:** `/api/agents/:agentId/run-async/:runId/status` - [Get async run status](https://docs.cotool.ai/api-reference/agents/get-async-run-status-1.md): 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. - [Get async run result](https://docs.cotool.ai/api-reference/agents/get-async-run-result.md): Retrieve the completed result of an asynchronous agent run. Use the status endpoint first and call this endpoint once the run status is `done`. - [Run agent synchronously](https://docs.cotool.ai/api-reference/agents/run-agent-synchronously.md): Execute an agent run in a blocking manner and return the complete result once finished. - [List all agents](https://docs.cotool.ai/api-reference/agents/list-all-agents.md): Retrieve a list of all AI agents available in the organization - [Create a new agent](https://docs.cotool.ai/api-reference/agents/create-a-new-agent.md): Create a new AI agent with specified configuration including system prompt, tools, and model settings - [Get agent](https://docs.cotool.ai/api-reference/agents/get-agent.md): Retrieve detailed information about a specific agent by ID. - [Update agent](https://docs.cotool.ai/api-reference/agents/update-agent.md): Modify an agent's configuration, such as tools, prompts, or model settings. - [Delete agent](https://docs.cotool.ai/api-reference/agents/delete-agent.md): Remove an agent from the system. - [Convert a disconnected managed agent into a manual agent](https://docs.cotool.ai/api-reference/agents/convert-a-disconnected-managed-agent-into-a-manual-agent.md): 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. - [Batch update agents](https://docs.cotool.ai/api-reference/agents/batch-update-agents.md): 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. - [Get response-agent notification defaults](https://docs.cotool.ai/api-reference/agents/get-response-agent-notification-defaults.md): Retrieve organization-wide default notification settings for response-agent acceptance criteria failures and critical issues. - [Update response-agent notification defaults](https://docs.cotool.ai/api-reference/agents/update-response-agent-notification-defaults.md): Update organization-wide default notification settings inherited by response agents. - [List agent runs/chats](https://docs.cotool.ai/api-reference/agents/list-agent-runschats.md): Retrieve a paginated list of runs/chats associated with a specific agent. - [List agent runs](https://docs.cotool.ai/api-reference/agents/list-agent-runs.md): Retrieve a paginated list of historical agent execution runs with optional filters. - [List critical issues](https://docs.cotool.ai/api-reference/agents/list-critical-issues.md): Retrieve normalized critical issues from agent evaluations and code-detection circuit breakers. - [Dismiss critical issue](https://docs.cotool.ai/api-reference/agents/dismiss-critical-issue.md): Dismiss an open critical issue so it no longer appears in the active issues feed. - [Get feedback metrics for multiple agents](https://docs.cotool.ai/api-reference/agents/get-feedback-metrics-for-multiple-agents.md): Retrieves feedback metrics (average score, up rate, totals) for multiple agents over 7-day and 30-day periods - [Get detailed feedback metrics for an agent](https://docs.cotool.ai/api-reference/agents/get-detailed-feedback-metrics-for-an-agent.md): Retrieves comprehensive feedback metrics for a single agent including time-series data, per-prompt breakdown (optional), and all-time statistics - [Get LLM evaluation metrics](https://docs.cotool.ai/api-reference/agents/get-llm-evaluation-metrics.md): Retrieve system LLM evaluation metrics for an agent (default evaluator: llm-judge). - [Get LLM evaluation metrics for multiple agents](https://docs.cotool.ai/api-reference/agents/get-llm-evaluation-metrics-for-multiple-agents.md): Retrieve system LLM evaluation metrics (llm-judge) for multiple agents in batch. - [List trigger sources](https://docs.cotool.ai/api-reference/agents/list-trigger-sources.md): Retrieve all distinct trigger sources used across agent runs in this organization. - [List agent tags](https://docs.cotool.ai/api-reference/agents/list-agent-tags.md): Retrieve all tags available in the organization with their usage counts. - [Create agent tag](https://docs.cotool.ai/api-reference/agents/create-agent-tag.md): Create a new tag in the organization. - [Rename agent tag](https://docs.cotool.ai/api-reference/agents/rename-agent-tag.md): Rename a tag in the organization. Requires setting.tags.manage permission. - [Delete agent tag](https://docs.cotool.ai/api-reference/agents/delete-agent-tag.md): Delete a tag from the organization. Requires setting.tags.manage permission. Will fail if the tag is still assigned to any agents. - [List agent templates](https://docs.cotool.ai/api-reference/agents/list-agent-templates.md): Retrieve all available agent templates for the current organization. - [Update agent operational settings (deprecated)](https://docs.cotool.ai/api-reference/agents/update-agent-operational-settings-deprecated.md): Deprecated: legacy API-run alerting is retired — new agents use explicit alert sources and default to alert-free API runs. Kept for backward compatibility so existing consumers can still toggle createAlertsForApiRuns on response agents. - [Submit feedback for an agent run](https://docs.cotool.ai/api-reference/agentruns/submit-feedback-for-an-agent-run.md): Submits user feedback (thumbs up/down) for a specific agent run, optionally including a comment and chat event reference - [Submit feedback for multiple agent runs](https://docs.cotool.ai/api-reference/agentruns/submit-feedback-for-multiple-agent-runs.md): Submits user feedback (thumbs up/down) for multiple agent runs in a single batch operation - [Get feedback summary for an agent run](https://docs.cotool.ai/api-reference/agentruns/get-feedback-summary-for-an-agent-run.md): Retrieves aggregated feedback statistics (up/down counts, total, average score) for a specific agent run - [Generate JSON Schema](https://docs.cotool.ai/api-reference/agentschemas/generate-json-schema.md): Generate a JSON schema for agent structured output based on system prompt and description using an LLM. - [List agent versions](https://docs.cotool.ai/api-reference/agent-versions/list-agent-versions.md): List the whole-definition version timeline for an agent (newest first) - [Revert an agent to a previous version](https://docs.cotool.ai/api-reference/agent-versions/revert-an-agent-to-a-previous-version.md): 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. - [List alerts](https://docs.cotool.ai/api-reference/alerts/list-alerts.md): Retrieve first-class alert work items for the current organization. Archived dismissed, duplicate, and expired alerts are excluded unless a status filter is provided. - [Get alert filter options](https://docs.cotool.ai/api-reference/alerts/get-alert-filter-options.md): Return alert filter options derived from readable alerts, including Cotool and externally extracted detections. - [Get alert routing overview](https://docs.cotool.ai/api-reference/alerts/get-alert-routing-overview.md): Return detection alert routing defaults, per-detection effective routing, alert producers, and response-agent handling summary. - [Update default alert routing](https://docs.cotool.ai/api-reference/alerts/update-default-alert-routing.md): Update the organization-wide default agent for alerts without an explicit route. - [Get detection alert routing](https://docs.cotool.ai/api-reference/alerts/get-detection-alert-routing.md): Return a detection agent alert routing override and effective routing setting. - [Update detection alert routing](https://docs.cotool.ai/api-reference/alerts/update-detection-alert-routing.md): Set or clear a per-detection alert routing override. - [Get alert for run](https://docs.cotool.ai/api-reference/alerts/get-alert-for-run.md): Resolve the alert a run triaged or created, used to link an agent run back to its alert. - [Get alert](https://docs.cotool.ai/api-reference/alerts/get-alert.md): Retrieve one alert and its initial timeline page. - [Update alert details](https://docs.cotool.ai/api-reference/alerts/update-alert-details.md): Update an alert title and/or description and append matching timeline entries. - [Get alert timeline](https://docs.cotool.ai/api-reference/alerts/get-alert-timeline.md): Retrieve paginated timeline entries for an alert. - [Get alert source payload](https://docs.cotool.ai/api-reference/alerts/get-alert-source-payload.md): Retrieve the stored raw source payload for an alert. - [Add alert comment](https://docs.cotool.ai/api-reference/alerts/add-alert-comment.md): Append a timeline comment to an alert. - [Update alert status](https://docs.cotool.ai/api-reference/alerts/update-alert-status.md): 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. - [Get escalated alert notification defaults](https://docs.cotool.ai/api-reference/alerts/get-escalated-alert-notification-defaults.md): Get the organization-wide destinations notified when an alert moves into escalated status. - [Update escalated alert notification defaults](https://docs.cotool.ai/api-reference/alerts/update-escalated-alert-notification-defaults.md): Update the organization-wide destinations notified when an alert moves into escalated status. - [Update alert severity](https://docs.cotool.ai/api-reference/alerts/update-alert-severity.md): Update an alert severity and append a severity-change timeline entry. - [Start alert triage run](https://docs.cotool.ai/api-reference/alerts/start-alert-triage-run.md): Assign an alert to a response agent and enqueue an alert-triage run. - [Validate Response-Agent-as-Code YAML](https://docs.cotool.ai/api-reference/agentsync/validate-response-agent-as-code-yaml.md): 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. - [Get artifact](https://docs.cotool.ai/api-reference/artifacts/get-artifact.md): Fetch the content and metadata of a stored artifact by its ID for a given chat. - [Count audit logs](https://docs.cotool.ai/api-reference/audit-logs/count-audit-logs.md): Return the total number of audit-log records that match a set of optional filters. - [Get audit event types](https://docs.cotool.ai/api-reference/audit-logs/get-audit-event-types.md): > ⚠️ **Deprecated** > This endpoint only returns event types. Use /api/audit-logs/filter-options to retrieve all audit-log filter dropdown values. > **Use instead:** `/api/audit-logs/filter-options` - [Get audit-log filter options](https://docs.cotool.ai/api-reference/audit-logs/get-audit-log-filter-options.md): 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. - [Get audit-log event catalog](https://docs.cotool.ai/api-reference/audit-logs/get-audit-log-event-catalog.md): 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. - [List audit logs](https://docs.cotool.ai/api-reference/audit-logs/list-audit-logs.md): 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 ne… - [Get audit log entry](https://docs.cotool.ai/api-reference/audit-logs/get-audit-log-entry.md): Retrieve a single audit-log record by its unique identifier. - [Get current user](https://docs.cotool.ai/api-reference/users/get-current-user.md): Return the authenticated user's profile information. - [Get current user permissions and all available permissions](https://docs.cotool.ai/api-reference/users/get-current-user-permissions-and-all-available-permissions.md): Returns the current user's effective permissions and the list of all permission definitions available in the system. - [List users](https://docs.cotool.ai/api-reference/users/list-users.md): Retrieve all users within the current organization. - [Search users](https://docs.cotool.ai/api-reference/users/search-users.md): Search for users within the organization by email address. - [Update user](https://docs.cotool.ai/api-reference/users/update-user.md): Update a user's role assignment within your organization. - [Delete user](https://docs.cotool.ai/api-reference/users/delete-user.md): Delete a user by ID within your organization. - [Hunt overview](https://docs.cotool.ai/api-reference/hunt/hunt-overview.md): Landing dashboard: environment metric tiles, the intel -> exposure funnel, detection coverage distribution, and recent Threats / rule proposals / blocking gaps. - [List threat actors](https://docs.cotool.ai/api-reference/hunt/list-threat-actors.md): Actor grouping nodes for the current organization, used as Threat catalog filter options. - [List Threats](https://docs.cotool.ai/api-reference/hunt/list-threats.md): 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. - [Get Threat detail](https://docs.cotool.ai/api-reference/hunt/get-threat-detail.md): A Threat with its assessment runs (newest first), deliverables, and all linked Hunt Alert episodes. - [Get Threat Hunt Alert history](https://docs.cotool.ai/api-reference/hunt/get-threat-hunt-alert-history.md): Every Hunt Alert episode linked to this Threat, newest first. - [Resolve cited tool calls for an assessment run](https://docs.cotool.ai/api-reference/hunt/resolve-cited-tool-calls-for-an-assessment-run.md): Resolves the inline tool-use ids referenced by a run, its exposure story, deliverables, diff, or Hunt Alert payload into the underlying read-only tool calls (query/input and result). - [Dismiss a Threat](https://docs.cotool.ai/api-reference/hunt/dismiss-a-threat.md): 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. - [Restore a dismissed Threat](https://docs.cotool.ai/api-reference/hunt/restore-a-dismissed-threat.md): Clear an explicit dismissal, returning the Threat to its derived status. - [Reassess a Threat](https://docs.cotool.ai/api-reference/hunt/reassess-a-threat.md): Manually trigger a fresh Threat-scoped assessment (relevancy gate -> exposure). Enqueues the assessment job; the run streams in the Threat detail activity timeline. - [Dispose a gap via a threat finding](https://docs.cotool.ai/api-reference/hunt/dispose-a-gap-via-a-threat-finding.md): 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. - [Dispose an observability gap](https://docs.cotool.ai/api-reference/hunt/dispose-an-observability-gap.md): 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. - [Get Hunt Alert creation settings](https://docs.cotool.ai/api-reference/hunt/get-hunt-alert-creation-settings.md): Get the organization-wide minimum exposure band and compromise-signal override used to create or reopen Hunt Alerts. - [Update Hunt Alert creation settings](https://docs.cotool.ai/api-reference/hunt/update-hunt-alert-creation-settings.md): Update the organization-wide minimum exposure band and compromise-signal override used to create or reopen Hunt Alerts. - [List CLI integrations](https://docs.cotool.ai/api-reference/clis/list-cli-integrations.md): Return a grouped list of CLI integrations available to the organization. - [Disconnect CLI](https://docs.cotool.ai/api-reference/clis/disconnect-cli.md): Remove stored credentials for a CLI integration. - [Generate a SIEM query using AI](https://docs.cotool.ai/api-reference/detections/generate-a-siem-query-using-ai.md): Generates a SIEM query based on a natural language prompt using AI - [Generate a SIEM query asynchronously](https://docs.cotool.ai/api-reference/detections/generate-a-siem-query-asynchronously.md): Starts detection query generation in a background job and returns a job ID for polling. - [Get async SIEM query generation status](https://docs.cotool.ai/api-reference/detections/get-async-siem-query-generation-status.md): Returns the current status of a background detection query generation job. - [Generate a detection system prompt](https://docs.cotool.ai/api-reference/detections/generate-a-detection-system-prompt.md): Generates a system prompt for a detection based on category and user objective (without generating a query) - [Generate investigation plan](https://docs.cotool.ai/api-reference/detections/generate-investigation-plan.md): Generate an investigation plan and system prompt from a detection intent. - [Generate investigation plan asynchronously](https://docs.cotool.ai/api-reference/detections/generate-investigation-plan-asynchronously.md): Start investigation plan generation in a background job and return a job ID for streaming and polling. - [Get async investigation plan generation status](https://docs.cotool.ai/api-reference/detections/get-async-investigation-plan-generation-status.md): Return the current status of a background investigation plan generation job. - [List detection categories](https://docs.cotool.ai/api-reference/detections/list-detection-categories.md): Retrieve all available detection categories with their metadata. - [List detection suggestions](https://docs.cotool.ai/api-reference/detections/list-detection-suggestions.md): Retrieve all detection suggestions for the current organization. - [List dismissed detection suggestions](https://docs.cotool.ai/api-reference/detections/list-dismissed-detection-suggestions.md): Retrieve all dismissed (soft-deleted) detection suggestions for the current organization. - [Restore dismissed detection suggestion](https://docs.cotool.ai/api-reference/detections/restore-dismissed-detection-suggestion.md): Restore a previously dismissed detection suggestion. - [List detections](https://docs.cotool.ai/api-reference/detections/list-detections.md): Retrieve all detections for the current organization. - [Create detection](https://docs.cotool.ai/api-reference/detections/create-detection.md): Create a new detection. - [Get detections overview](https://docs.cotool.ai/api-reference/detections/get-detections-overview.md): Unified detection-efficacy view across Cotool detection agents, Cotool code detections, and the synced external rule inventory. External alerts are attributed through persisted rule links. Each item carries alert counts and dispositions over a rolling window. - [List detection hits](https://docs.cotool.ai/api-reference/detections/list-detection-hits.md): 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… - [Update detection hit status](https://docs.cotool.ai/api-reference/detections/update-detection-hit-status.md): Update a detection hit lifecycle status and append a typed status history entry. - [Get tool calls cited by a detection hit](https://docs.cotool.ai/api-reference/detections/get-tool-calls-cited-by-a-detection-hit.md): Resolve the toolUseIds referenced by a hit's verifierEvidence into the underlying tool-call snapshots (query, input, frontendOutput, status). Lets the hit drawer display the cited queries without surfacing the full run trajectory. - [Get detection](https://docs.cotool.ai/api-reference/detections/get-detection.md): Retrieve a specific detection by ID. - [Update detection](https://docs.cotool.ai/api-reference/detections/update-detection.md): Update an existing detection. - [Delete detection](https://docs.cotool.ai/api-reference/detections/delete-detection.md): Delete a detection (soft delete). - [List detection runs](https://docs.cotool.ai/api-reference/detections/list-detection-runs.md): Retrieve runs for a specific detection. Supports server-side pagination via `limit`/`offset` and a `filter` query parameter (`all`, `hits`, `clear`, `errors`) that mirrors the agent list view's definition of a hit (rows present in the `detection_hits` table). - [Get detection stats](https://docs.cotool.ai/api-reference/detections/get-detection-stats.md): Return rolling 7d/30d run, hit, and eval-score aggregates for a detection agent. Uses the same `detection_hits`-table aggregation as the agent list view so the KPI numbers shown on the detail page match the list page. - [Run detection](https://docs.cotool.ai/api-reference/detections/run-detection.md): Execute a detection ad-hoc. - [Accept detection suggestion](https://docs.cotool.ai/api-reference/detections/accept-detection-suggestion.md): Accept a detection suggestion, converting it to a regular detection. - [Get detection output configuration](https://docs.cotool.ai/api-reference/detections/get-detection-output-configuration.md): Retrieve output settings and available destinations for a detection. - [Update detection output configuration](https://docs.cotool.ai/api-reference/detections/update-detection-output-configuration.md): Update output settings for a detection (enable/disable, set destinations, set send mode). - [Get detection output defaults](https://docs.cotool.ai/api-reference/detections/get-detection-output-defaults.md): Retrieve organization-wide default output settings and available destinations for detection agents. - [Update detection output defaults](https://docs.cotool.ai/api-reference/detections/update-detection-output-defaults.md): Update organization-wide default output settings inherited by detection agents. - [List all output destinations](https://docs.cotool.ai/api-reference/detections/list-all-output-destinations.md): List all output destinations for the organization. - [Create output destination](https://docs.cotool.ai/api-reference/detections/create-output-destination.md): Create a new output destination (webhook, Teams, Slack, PagerDuty, Linear, or Tines) for the organization. - [Create output destination](https://docs.cotool.ai/api-reference/detections/create-output-destination-1.md): Create a new output destination (webhook, Teams, Slack, or PagerDuty) for the organization. - [Update output destination](https://docs.cotool.ai/api-reference/detections/update-output-destination.md): Update an existing output destination (webhook, Teams, Slack, PagerDuty, Linear, or Tines). - [Send a test payload to an output destination](https://docs.cotool.ai/api-reference/detections/send-a-test-payload-to-an-output-destination.md): 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. - [Send a test payload to an unsaved output destination](https://docs.cotool.ai/api-reference/detections/send-a-test-payload-to-an-unsaved-output-destination.md): 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. - [Toggle detection enabled status](https://docs.cotool.ai/api-reference/detections/toggle-detection-enabled-status.md): Enable or disable a detection's scheduled execution. - [Re-add a legacy Auto Detect detection](https://docs.cotool.ai/api-reference/detections/re-add-a-legacy-auto-detect-detection.md): Converts a frozen detection created by the retired Auto Detect feature into a regular user detection and schedules it to run weekly. - [List the Cotool detection library](https://docs.cotool.ai/api-reference/detections/list-the-cotool-detection-library.md): 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. - [Read one detection library entry](https://docs.cotool.ai/api-reference/detections/read-one-detection-library-entry.md): Returns the entry with its notebook source and the globally cached logic summary, for review before adding. Requires tool.read. - [Add a detection library entry](https://docs.cotool.ai/api-reference/detections/add-a-detection-library-entry.md): Creates an org-owned detection from the entry, publishes its notebook as version 1, and enables the entry's default schedule. - [List roles for the current organization](https://docs.cotool.ai/api-reference/roles/list-roles-for-the-current-organization.md): List all roles for the current organization - [Create a role](https://docs.cotool.ai/api-reference/roles/create-a-role.md): Create a new role for the current organization - [Get role by id](https://docs.cotool.ai/api-reference/roles/get-role-by-id.md): Get a specific role by its ID - [Update a role](https://docs.cotool.ai/api-reference/roles/update-a-role.md): Update an existing role for the current organization - [Delete a role](https://docs.cotool.ai/api-reference/roles/delete-a-role.md): Delete an existing role for the current organization - [Get permissions for a role](https://docs.cotool.ai/api-reference/roles/get-permissions-for-a-role.md): Get the permissions for a specific role - [Apply permission diff to a role](https://docs.cotool.ai/api-reference/roles/apply-permission-diff-to-a-role.md): Apply a permission diff to a specific role - [List threat intelligence items](https://docs.cotool.ai/api-reference/list-threat-intelligence-items.md): Retrieves a paginated list of threat intelligence items with support for filtering by severity, platform, status, source, and text search - [List flattened threat-intel indicators (IOCs)](https://docs.cotool.ai/api-reference/list-flattened-threat-intel-indicators-iocs.md): Flattens indicators from all in-scope intel items, resolves per-indicator hunt status, and supports server-side search, status, and type filtering with pagination. - [Get specific intel item](https://docs.cotool.ai/api-reference/get-specific-intel-item.md): Retrieves detailed information for a specific threat intelligence item by its ID - [Generate detection context](https://docs.cotool.ai/api-reference/generate-detection-context.md): Generates structured detection context and chat URL for authoring security detections based on a threat intelligence item - [Get intel feed statistics](https://docs.cotool.ai/api-reference/get-intel-feed-statistics.md): Retrieves aggregated statistics for the threat intelligence feed including severity breakdown, platform breakdown, and recent items - [List intel sources](https://docs.cotool.ai/api-reference/list-intel-sources.md): Lists built-in and custom intel sources for the current organization - [Create intel source](https://docs.cotool.ai/api-reference/create-intel-source.md): Creates a custom RSS, MISP, or TAXII intel source - [Update intel source](https://docs.cotool.ai/api-reference/update-intel-source.md): Updates a custom intel source or toggles a built-in source subscription - [Delete intel source](https://docs.cotool.ai/api-reference/delete-intel-source.md): Deletes a custom intel source and associated intel items - [Trigger intel source sync](https://docs.cotool.ai/api-reference/trigger-intel-source-sync.md): Enqueues an immediate sync job for a custom intel source - [Get threat intel notification settings](https://docs.cotool.ai/api-reference/intel/get-threat-intel-notification-settings.md): Retrieve organization-wide threat intel notification settings and available destinations. - [Update threat intel notification settings](https://docs.cotool.ai/api-reference/intel/update-threat-intel-notification-settings.md): Update organization-wide threat intel notification settings. - [Get MITRE ATT&CK matrix with detection coverage](https://docs.cotool.ai/api-reference/mitre-classification/get-mitre-att&ck-matrix-with-detection-coverage.md): Retrieve the MITRE ATT&CK framework matrix showing detection rule coverage as a heatmap - [Get MITRE technique details](https://docs.cotool.ai/api-reference/mitre-classification/get-mitre-technique-details.md): Retrieve detailed information about a specific MITRE ATT&CK technique including detection rules - [List Orca alert groups](https://docs.cotool.ai/api-reference/orca-alerts/list-orca-alert-groups.md): Retrieve a list of grouped Orca Security alerts sorted by relevance score (severity weight × alert count) - [Get alert group details](https://docs.cotool.ai/api-reference/orca-alerts/get-alert-group-details.md): Retrieve detailed information about a specific Orca Security alert group - [Get Orca configuration](https://docs.cotool.ai/api-reference/orca-alerts/get-orca-configuration.md): Retrieve the base URL configuration for the Orca Security integration - [List user organizations](https://docs.cotool.ai/api-reference/organizations/list-user-organizations.md): Retrieve all organizations that the current user has access to. - [Get organization-level activity metrics](https://docs.cotool.ai/api-reference/metrics/get-organization-level-activity-metrics.md): Returns summary counts and timeseries for agent runs, chats, and GitHub PR actions for the authenticated organization. - [Create Linear agent session for an agent](https://docs.cotool.ai/api-reference/linear-agent/create-linear-agent-session-for-an-agent.md): 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. - [List skills](https://docs.cotool.ai/api-reference/skills/list-skills.md): List all active skills in the organization. - [Create skill](https://docs.cotool.ai/api-reference/skills/create-skill.md): Create a reusable skill in the organization. - [Get skill](https://docs.cotool.ai/api-reference/skills/get-skill.md): Get one active skill by ID. - [Update skill](https://docs.cotool.ai/api-reference/skills/update-skill.md): Update an existing skill. - [Delete skill](https://docs.cotool.ai/api-reference/skills/delete-skill.md): Soft delete a skill. - [List agents using skill](https://docs.cotool.ai/api-reference/skills/list-agents-using-skill.md): List all agents currently using this skill. - [List skill versions](https://docs.cotool.ai/api-reference/skills/list-skill-versions.md): List all versions for a skill in descending order. - [Get skill version](https://docs.cotool.ai/api-reference/skills/get-skill-version.md): Get one specific skill version with references. - [Restore a skill version](https://docs.cotool.ai/api-reference/skills/restore-a-skill-version.md): Restore a previous skill snapshot as a new current version. - [Import skill](https://docs.cotool.ai/api-reference/skills/import-skill.md): Import a skill package payload and create the skill. - [Export skill](https://docs.cotool.ai/api-reference/skills/export-skill.md): Export a skill payload including current detail and version metadata. - [List MCP server resources](https://docs.cotool.ai/api-reference/tools/list-mcp-server-resources.md): Return a list of resources available on the specified MCP server. - [List tools](https://docs.cotool.ai/api-reference/tools/list-tools.md): Return a grouped list of tools available to the organization. - [Disconnect tool](https://docs.cotool.ai/api-reference/tools/disconnect-tool.md): Remove stored credentials for a given tool type, disconnecting it from the organization. - [Get raw tool output](https://docs.cotool.ai/api-reference/tools/get-raw-tool-output.md): Fetch raw data captured for a previous tool invocation specified by uuid. - [Get threat model](https://docs.cotool.ai/api-reference/threatmodel/get-threat-model.md): Get the current threat model for the organization. - [Update threat model](https://docs.cotool.ai/api-reference/threatmodel/update-threat-model.md): Save a user-edited threat model as a new version in the organization history. - [Get structured threat model board](https://docs.cotool.ai/api-reference/threatmodel/get-structured-threat-model-board.md): Get the structured per-surface board (lean generated layer + live source/detection overlay). - [Regenerate threat model](https://docs.cotool.ai/api-reference/threatmodel/regenerate-threat-model.md): Enqueue a threat model regeneration job using current environment data. - [List threat model version history](https://docs.cotool.ai/api-reference/threatmodel/list-threat-model-version-history.md): List the full threat model version history for the organization. - [Get threat model version](https://docs.cotool.ai/api-reference/threatmodel/get-threat-model-version.md): Get one threat model version from the organization history by ID. - [Cotool Release Notes](https://docs.cotool.ai/changelog.md): Product updates and release history ## OpenAPI Specs - [openapi](https://app.cotool.ai/api/docs/openapi.json) ## Optional - [Blog](https://cotool.ai/blog)