Documentation Index
Fetch the complete documentation index at: https://cognisafeltd.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
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"
OpenAPI spec
The full OpenAPI 3.1 spec is available at:
You can import this into Postman, Insomnia, or any OpenAPI-compatible tool:
curl https://api.cognisafe.uk/openapi.json -o cognisafe-api.json
/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 |
POST /internal/log returns HTTP 429 Too Many Requests. Other endpoints are not rate-limited by tier.
All responses are JSON. Errors follow this shape:
{
"detail": "Human-readable error message"
}
{
"items": [...],
"total": 1234,
"page": 1,
"page_size": 50
}
