Authentication
How to authenticate with the Encelade API using API tokens.
Public v1 API requests require an API token passed via x-api-key or Authorization: Bearer YOUR_API_TOKEN.
Creating a token
Copy the token immediately
Your token is only displayed once. Store it securely — you cannot retrieve it later.
Using the token
Include the token in every request:
curl -X GET https://your-instance.com/api/public/v1/projects \
-H "x-api-key: YOUR_API_TOKEN"Scopes
Tokens are scoped to limit access. These scopes are used by the public REST API and MCP:
| Scope | Description |
|---|---|
project:read | List and view projects |
project:write | Update projects |
project:delete | Delete projects |
project:publish | Publish and unpublish projects (REST only) |
project:generate | Start a generation run |
project:ai-chat | Edit a project with AI |
project:export | Start and poll PDF/PPTX exports (REST only) |
session:read | Read generation runs |
session:write | Cancel generation runs |
webhook:read | List webhooks |
webhook:write | Create and delete webhooks |
theme:read | List custom themes (MCP only) |
theme:write | Create, update and delete custom themes (MCP only) |
MCP also accepts project:generate for get_generation_run and cancel_generation_run. REST polling and cancellation require session:read and session:write, respectively. The registered project:plan and media:search scopes have no public v1 endpoints.
Scopes do not override workspace roles, project permissions or plan limits. Webhook management requires a workspace admin's token.
A token created with no scopes selected gets every scope. OAuth tokens get
every scope except project:delete unless the client requests it, and never
get project:publish. Workspace roles, project permissions and plan limits
still apply.
Rate limiting
REST requests are rate-limited per token, with a default of 120 requests per minute. Some operations use separate buckets:
| Operation | Requests per minute |
|---|---|
| Start a generation run | 10 |
| Edit a project with AI | 10 |
| Cancel a generation run | 20 |
| Start a PDF or PPTX export (shared bucket) | 10 |
| Poll an export job | 120 |
Request-rate failures return 429 Too Many Requests with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Wait for Retry-After before retrying.
Concurrency limits are separate: exports allow 2 in-flight jobs per workspace, and generation has user and workspace caps on active runs. These refusals also return 429 but may not include rate-limit headers; inspect the error body and wait for an active job or run to finish.
Errors
All error responses follow a consistent format:
{
"error": "Description of what went wrong"
}Common status codes:
| Code | Meaning |
|---|---|
401 | Invalid or missing API token |
402 | Credits or a plan limit block the operation |
403 | Required scope, role or permission is missing |
429 | Request rate or concurrency limit exceeded |
503 | Token verification or another required service is temporarily unavailable |
Responses may also include code, details or limit information. Consult the endpoint reference for its full error contract. A token-verification 503 is retryable; it does not mean your token is invalid.
The API playground on the reference pages sends real requests. Use a test or development token when trying endpoints interactively.