> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Authenticate, understand responses, and find the endpoints for common integrations

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](https://app.cotool.ai/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:

```bash theme={null}
curl "https://app.cotool.ai/api/agents" \
  -H "Authorization: Bearer $COTOOL_API_KEY"
```

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](/settings/roles-permissions-overview).

## 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:

| Status | Meaning                                              | Body                                                                                |
| ------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `400`  | Invalid input                                        | `{ "error": "Validation failed", "issues": [...] }` with one entry per failed field |
| `401`  | Missing, invalid, expired, or revoked API key        | `{ "error": "Unauthorized" }`                                                       |
| `403`  | The key's role lacks a required permission           | `{ "error": "...", "missingPerms": [...] }`                                         |
| `404`  | Resource not found, or the endpoint has been removed | `{ "error": "..." }`                                                                |
| `410`  | The endpoint passed its published sunset date        | `{ "error": "..." }` naming the replacement                                         |

List endpoints paginate with query parameters. Most use `limit` and `offset`; some, such as [List agent runs](/api-reference/agent-runs/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`](https://app.cotool.ai/api/docs/openapi.json). Use it to generate clients or import the API into tools such as Postman.