REST API
Clearplane exposes its public management API below https://<management-host>/api/. The generated OpenAPI 3.1 contract is available to users with Settings.Read at:
GET https://<management-host>/api/openapi
The contract is generated from the running controllers and shared JSON configuration. It is the source of truth for paths, methods, request and response shapes, nullability, and enum values. Schema descriptions state conditional requirements that cannot be expressed as a single required-property list; the API applies those rules with FluentValidation and returns 400 for violations.
Authentication and permissions
Sign in with a cookie jar, then reuse that jar for API requests:
base='https://clearplane.example.com/api'
curl --fail-with-body \
--cookie-jar clearplane.cookies \
--header 'Content-Type: application/json' \
--data '{"userName":"Administrator","password":"replace-me"}' \
"$base/authentication/sign-in"
curl --fail-with-body \
--cookie clearplane.cookies \
"$base/openapi"
The sign-in response's nextStep is SessionCreated when authentication is complete. MultiFactorChallengeRequired means the client must complete the authentication/multi-factor-challenge operation described by the contract before using protected operations.
For POST, PUT, PATCH, or DELETE with the session cookie, also send the browser-session CSRF header:
X-Clearplane-CSRF: Clearplane.Browser
Each operation enforces its own permission. A missing or invalid session returns 401; an authenticated account without the required permission returns 403. Every protected OpenAPI operation declares the clearplaneSession security scheme and its exact permission in x-clearplane-permissions; unsafe operations also declare clearplaneCsrf. The OpenAPI document itself requires Settings.Read.
JSON and updates
- Property names use camel case.
- Route
pathvalues are complete route patterns on every surface./apimatches only that literal path, while/api/{**catch-all}matches/api,/api/orders, and everything below it. Docker labels use the same value underclearplane.proxy.pathorclearplane.redirect.path; Clearplane does not rewrite it. - Optional
stripPrefixandpathRewritevalues treat an empty or whitespace-only string as unset, matching blank label and UI values. - Durations use integer fields whose names state the unit, such as
activityTimeoutSeconds,windowSeconds,durationSeconds,preflightMaximumAgeSeconds, anddefaultTimeToLiveSeconds. The API does not expose the internalTimeSpanproperty names without a unit. - Enum values use the canonical member names listed by the contract, such as
MaxMindorDetection. Input matching is case-insensitive, but numeric enum backing values are rejected. Redirect status codes are the one exception:redirectStatusCodeandstatusCodecarry the HTTP numbers301,302,307or308, like the redirect labels. - The live hubs at
/api/ws/logsand/api/ws/background-jobssend the same field and enum names as the REST responses. - Treat
PUTrequest models as complete replacements. Read the current resource first and preserve fields that should not change. - Resources that own a child list are saved with it in one transaction: access-control policies and aliases carry
entries, header policies carryentries, and upstream clusters carrydestinations. Each child is matched by itsid. A child without anidis created, a listed child is updated, and an existing child left out of the list is deleted, so aPUTwithout the list removes every child. On upstream clusters, adding or changing a destination also requiresUpstreamDestinations.Writeand removing one requiresUpstreamDestinations.Manage. The nested/entriesand/destinationsendpoints remain for single-child changes. - Authentication-policy passwords and JWT signing-key material are write-only and are returned as empty strings. Each returned signing key carries an
id. On update, leave an existing credential's password blank to preserve it (credentials are matched by username), and send a signing key'sidwith blank material to keep that key; keys left out of the list are removed. A blank value cannot create a new credential or key, change its identity or kind, or survive an authentication-type change; supply new material in those cases. - Setting responses distinguish saved and effective values and report their effective source where applicable. The configuration catalog states whether a change is immediate, validated, staged until Edge apply, or restart-required.
Automatic-apply settings are read with GET /api/edge/automatic-apply under Settings.Read and changed with PUT /api/edge/automatic-apply under Settings.Write. Operational Edge statistics remain under Services.Read and do not expose configuration settings; GET /api/edge/cache-statistics returns only the cache part of them under Cache.Read.
For example, a rate-limit request uses a numeric seconds field:
{
"name": "login-burst",
"windowSeconds": 60,
"requestLimit": 20
}
Core converts windowSeconds: 60 to its typed duration and persists that duration in the Window database field. Responses convert it back to windowSeconds: 60; clients never need to know the database representation.
Lists and search
A collection GET, such as GET /api/proxy-routes, returns a plain JSON array of every item visible in the current scope, ordered by the resource's natural order. It takes no paging parameters. The one exception is GET /api/background-jobs/{id}/runs, which returns the newest runs first and accepts take (default 50, at most 500).
For paged tables, POST <collection>/search accepts:
{
"skip": 0,
"take": 25,
"search": "shop",
"sort": [{ "field": "name", "descending": false }]
}
take is at most 500. The response is { "items": [...], "totalCount": 42 }, where totalCount counts every match before paging. Unknown sort fields are ignored.
Logs and WAF detections are read newest first with a cursor instead. GET /api/logs/browse and GET /api/waf-detections/browse accept take (at most 500) and the nextCursor from the previous response; /count returns the exact total for the same filters. Route and cluster filters are numeric IDs: logs accept proxyRouteId, upstreamClusterId, type (Request, Application or Discovery), level (Trace, Debug, Information, Warning, Error or Critical, returning that level and above), statusCode (404 or a class such as 4xx) and minimumDurationMilliseconds; detections accept proxyRouteId. Log entries report occurredAt, proxyRouteId, redirectRouteId, upstreamClusterId and durationMilliseconds, and detections report proxyRouteId.
Errors
Every error from an API operation, and every request to an unknown /api path, returns application/problem+json (RFC 9457) with status, title, detail, a stable code and, when available, traceId. errors keys are the camel-case JSON paths of the rejected fields, such as name or passwordPolicy.requiredLength. Show detail to people and branch on code in automation:
| Code | Status | Meaning |
|---|---|---|
validation-failed |
400 |
The body failed validation; errors maps each field to its messages. A password that breaks the password policy is reported under the request's password field: errors.temporaryPassword when creating a user or resetting a password, and errors.newPassword for PUT /api/me/password. |
invalid-request |
400 |
The request is well-formed but not allowed in its current form. |
invalid-api-schema |
400 |
An uploaded OpenAPI document, protobuf descriptor set or GraphQL schema was rejected; errors.content or errors.endpointPaths lists each problem. |
unauthorized, forbidden |
401, 403 |
The session is missing or lacks the required permission. |
locked-out |
423 |
Too many failed multi-factor attempts locked the account. Wait for the lockout to end. |
not-found |
404 |
The resource does not exist. |
already-exists |
409 |
A resource with the same name or identity exists. |
in-use |
409 |
The resource is still referenced and cannot be removed. |
stale |
409 |
The resource changed after it was read. Read it again and retry. |
busy |
409 |
Another request is changing the same configuration. Retry. |
source-managed |
409 |
A container label or environment variable owns the resource or setting. |
route-scope |
409 |
The change is not allowed in a selected route context. Switch to All routes. |
route-unavailable |
409 |
The selected route no longer exists. |
self-mutation, last-administrator, minimum-role |
409 |
A user change would alter your own account, remove the last administrator or drop below the minimum role. |
protected-role, role-assigned |
409 |
A role change would alter a protected role or delete a role that users still hold. |
system-role, unknown-permission, permission-selection, role-not-found |
400 |
A user or role request names a system role, an unknown permission, an invalid permission selection or a missing role. |
already-enrolled, not-enrolled |
409 |
Multi-factor authentication is already set up, or is not set up yet. |
password-change-required, multi-factor-authentication-required |
409 |
Change the password first, or multi-factor authentication is required and cannot be removed. |
conflict |
409 |
Any other conflict with the current state. |
unavailable |
503, 504 |
A dependency such as Edge or Clearplane Cloud did not answer. |
internal-error |
500 |
An unexpected error occurred; traceId identifies it in the logs. |
Sign-in and session rejections return an empty 401 or 403 on purpose, so the response reveals nothing about the account. Edge can also answer before a request reaches the API: rate limits (429), access-control and WAF blocks (403) and unavailable upstreams use Edge's error pages, not problem details.
Configuration ownership
The API updates the same saved value that the UI edits. Resolution remains environment variable → validated Clearplane container label → saved UI value → built-in default.
A runtime label on a Clearplane-owned container overrides the matching saved field. The UI presents that field as read-only, and the API response reports the effective source. Removing the label reveals the saved UI value again.
Resources discovered from application-container labels are container-managed. Change their labels instead of trying to mutate the generated route or inline policies through the API; conflicting mutations return 409. UI/API-created resources remain editable through the API subject to permissions and normal reference checks.
Use the Docker label reference for label parsing and ownership rules, and the environment variable reference for bootstrap and secret handling.