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

# API overview

> The Cognisafe REST API.

## Base URL

| Environment     | Base URL                                            |
| --------------- | --------------------------------------------------- |
| Cloud (managed) | `https://api.cognisafe.uk`                          |
| Self-hosted     | Your API service URL (e.g. `http://localhost:8000`) |

## Authentication

All API requests require an API key passed in the `X-Cognisafe-Key` header:

```bash theme={null}
curl https://api.cognisafe.uk/api/requests \
  -H "X-Cognisafe-Key: csk_your_key_here"
```

See [Authentication](/api-reference/authentication) for full details.

## OpenAPI spec

The full OpenAPI 3.1 spec is available at:

```
GET /openapi.json
```

You can import this into Postman, Insomnia, or any OpenAPI-compatible tool:

```bash theme={null}
curl https://api.cognisafe.uk/openapi.json -o cognisafe-api.json
```

Interactive docs (Swagger UI) are available at `/docs` on any self-hosted instance.

## Endpoint groups

### `/internal/log`

Used by the SDK and proxy to ship request/response payloads. Not intended for direct use by application code.

| Method | Path            | Description                                                     |
| ------ | --------------- | --------------------------------------------------------------- |
| `POST` | `/internal/log` | Log an LLM request. Returns 429 if over the tier request limit. |

### `/api/requests`

Query logged LLM requests for a project.

| Method | Path                 | Description                                                                 |
| ------ | -------------------- | --------------------------------------------------------------------------- |
| `GET`  | `/api/requests`      | List requests. Supports filtering by `project_id`, `model`, `start`, `end`. |
| `GET`  | `/api/requests/{id}` | Get a single request with full body and safety scores.                      |

### `/api/safety-scores`

Query safety scoring results.

| Method | Path                         | Description                                                      |
| ------ | ---------------------------- | ---------------------------------------------------------------- |
| `GET`  | `/api/safety-scores`         | List scores. Filter by `request_id`, `scorer_name`, `min_score`. |
| `GET`  | `/api/safety-scores/summary` | Aggregate score counts by scorer for a project and time range.   |

### `/api/billing`

Subscription and usage data.

| Method | Path                        | Description                                                                  |
| ------ | --------------------------- | ---------------------------------------------------------------------------- |
| `GET`  | `/api/billing/subscription` | Get the current subscription tier and usage for a project.                   |
| `POST` | `/api/billing/checkout`     | Create a Stripe checkout session to upgrade or subscribe.                    |
| `POST` | `/api/billing/portal`       | Create a Stripe customer portal session for self-service billing management. |

### `/webhook/stripe`

Stripe webhook endpoint. Cognisafe verifies the `Stripe-Signature` header using `STRIPE_WEBHOOK_SECRET`. Do not call this endpoint directly.

## Rate limits

API rate limiting is applied at the project level based on subscription tier:

| Tier       | Request limit / month |
| ---------- | --------------------- |
| Free       | 10,000                |
| Pro        | 500,000               |
| Team       | 5,000,000             |
| Enterprise | Unlimited             |

When the limit is exceeded, `POST /internal/log` returns `HTTP 429 Too Many Requests`. Other endpoints are not rate-limited by tier.

## Response format

All responses are JSON. Errors follow this shape:

```json theme={null}
{
  "detail": "Human-readable error message"
}
```

Successful list responses:

```json theme={null}
{
  "items": [...],
  "total": 1234,
  "page": 1,
  "page_size": 50
}
```