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:

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
}