Skip to main content
Everything you can do in the Cotool app is available over a JSON REST API at https://app.cotool.ai/api. If your organization signs in at a different host, use that host instead; the paths are the same.

​
Authentication

Create an API key at Settings → API keys. Creating keys requires the setting.apiKey.manage permission. The key is shown once; store it in your secrets manager. Send the key as a bearer token on every request:
An API key acts as the user who created it: same organization, same role, same permissions. Requests that the user could not perform in the app return 403. Keys cannot use admin-only capabilities or switch organizations, and a key stops working when it is revoked or when its user is deactivated. For integrations that run as a service rather than a person, create the key from a dedicated user whose role grants only the permissions the integration needs. See Roles and permissions.

​
Requests and responses

Request and response bodies are JSON. Send Content-Type: application/json on POST, PUT, and PATCH requests. Errors return a JSON body with an error message: List endpoints paginate with query parameters. Most use limit and offset; some, such as List agent runs, use page and pageSize. Each endpoint’s reference page lists its parameters and defaults.

​
Finding endpoints

The sidebar groups endpoints by product surface. Most integrations use a handful of them:
  • Agents run agents and read their results. Agent Triggers manage the schedules, webhooks, and integrations that start runs automatically.
  • Agent Runs, Alerts, and Output Destinations are the run history, the alerts agents raise, and the webhooks and integrations that runs push results to.
  • Detections and Hunt expose detection rules, hits, and Autonomous Hunt results for pipelines that pull findings into a SIEM or data lake.
  • Audit Logs exports the organization’s audit trail.

​
OpenAPI document

The reference is generated from the live specification at https://app.cotool.ai/api/docs/openapi.json. Use it to generate clients or import the API into tools such as Postman.