API overview - Cognisafe

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:

curl https://api.cognisafe.uk/api/requests \
  -H "X-Cognisafe-Key: csk_your_key_here"

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

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:

{
  "detail": "Human-readable error message"
}

Successful list responses:

{
  "items": [...],
  "total": 1234,
  "page": 1,
  "page_size": 50
}

​Base URL

​Authentication

​OpenAPI spec

​Endpoint groups

​/internal/log

​/api/requests

​/api/safety-scores

​/api/billing

​/webhook/stripe

​Rate limits

​Response format