REST API Overview
The HTTP API behind the web app, the SDK and BotCI.
The REST API is what the web app, the SDK and BotCI call. You can call it directly from any language.
Base URL
https://api.botmanifold.comThe full, interactive schema is served by the API itself at
/docs (Swagger UI) and /openapi.json. Treat that as the
source of truth; this section covers the endpoints most integrations use.
Authentication
Create an API key under Settings → API keys and send it as a Bearer token:
Authorization: Bearer bm_your_api_keyKeys start with bm_ and are shown once when created. Browser sessions use JWTs obtained by
signing in (GitHub, Google or username and password); programmatic access should use API keys.
Errors
Errors are JSON with a detail message and a standard HTTP status:
{ "detail": "API key or authentication required" }| Code | Meaning |
|---|---|
| 400 | Invalid input (for example an unknown scenario or a policy_url that is not allowed) |
| 401 | Missing or invalid credentials |
| 403 | Not allowed |
| 404 | Not found |
| 413 | Upload too large (the policy ZIP limit is 100 MB) |
| 429 | Rate limited |
| 5xx | Server error; retry with backoff |
Rate limits
Limits are per client and enforced per API instance. Examples: submissions (POST /verify,
POST /submissions) 10 per minute, authentication 5 per minute, MCP evaluation reads 60 per
minute. A 429 response means wait and retry; BotCI and the SDK back off automatically.
Quick reference
| Method | Endpoint | Description |
|---|---|---|
POST | /verify | Submit a policy (ZIP upload or policy_url) for verification |
GET | /verify/{job_id} | Poll the job; returns the report when finished |
GET | /submissions, /submissions/{id} | List and read submissions |
GET | /submissions/{id}/events | Server-sent events for status changes |
GET | /scenarios, /scenarios/{id} | Browse scenarios |
GET | /api/datasets, /api/datasets/{id} | Your datasets |
POST | /api-keys | Create an API key |
POST | /api/mcp/evaluations | Submit a checkpoint for evaluation (used by BotCI and the MCP server) |
See Endpoints for requests and responses.