Citadel DocsAPI Reference
Explore Citadel's public API endpoints, request parameters, and response schemas.
Use the public API to integrate Citadel with scripts and developer tools. This reference documents the public contract; use the schema matching your installed version when building integrations.
Authentication and trying requests
Protected operations use an Authorization: Bearer <token> header. Depending on the
operation, use a user JWT or a Service Account token with the required access.
For an integration, prefer a dedicated Service Account
with narrowly scoped permissions. Service Accounts require the Custom Access
Control license capability. User JWTs remain subject to the operation's own
permissions and capability requirements. Keep tokens out of source files and logs.
This reference does not send API requests or store credentials. To try requests
against your own installation, set CITADEL_HTTP_OPENAPI_ENABLED=true in .env and recreate
Core with docker compose up -d server. Include all proxy, TLS, and Edge overlays
used by your installation.
Swagger UI is then available at /swagger/, with the public schema at
/openapi/public/v1.json.
The full schema used by Citadel's web UI is internal and is not the external contract. Read the release notes before upgrading an integration.
Verify an integration
Start with a read operation using a dedicated identity, as shown in Service Account API access. Verify both the resources it can read and an unrelated resource it should not access before adding mutation calls. Use the installed instance's public schema for request shapes and supported operations.
| Response | What to check |
|---|---|
| 401 Unauthorized | Token validity, expiration or revocation, enabled account, and Service Account license availability. |
| 403 Forbidden | Required Roles, resource access, operation capabilities, and license requirements. |
| 404 Not Found | Resource ID and visibility; inaccessible resources may be hidden. |
| 400 Bad Request | Request body and parameters against the matching public schema. |
| 409 Conflict | Current resource state or an operation already in progress; inspect it before retrying. |
For queued work, inspect the resulting run or operation until it completes. An accepted request does not prove that a build, backup, or deployment succeeded. After a timeout or interrupted connection, check the resource's history before repeating a mutation that may already have started.
Loading API reference…