API overview
Everything in the UI is available via the REST API. JSON requests + responses, page-number pagination, deterministic error shapes, per-route RBAC enforcement. 250+ endpoints under /api/v1.
Base URL
The same host as the UI, under /api/v1. Example: https://cap.example.com/api/v1. Everything that follows uses relative paths rooted there.
Versioning
- Major version in the path (
/api/v1). A v2 would live at/api/v2alongside v1 during a transition window. - No breaking changes within a major. Additive changes only: new endpoints, new optional request fields, new response fields.
- When a breaking change is necessary, v2 opens for a deprecation window of ≥ 12 months, with
Deprecation+Sunsetheaders on v1 responses.
Tenancy in the URL
Every project-scoped resource is under /projects/:projectId/...:
/api/v1/projects/{projectId}/certificates
/api/v1/projects/{projectId}/acme-accounts
/api/v1/projects/{projectId}/certificates/{id}/distributions
Org-scoped resources don't carry the project prefix:
/api/v1/users
/api/v1/audit-logs
/api/v1/ca-providers
There is no cross-project read endpoint. If you need cross-project data, iterate GET /projects and fan out.
Content type
- Request: send JSON bodies with
Content-Type: application/json. Every request body is capped at 1 MiB; a larger body fails with400(the handler cannot read it). A proposed change too large to queue for approval is refused with413. - Response:
application/json, UTF-8 — certificate downloads included: the PEM / PFX / DER material comes back as fields of a JSON object (cert_pem,fullchain_pem,pfx_base64, …), not as a file. - Exceptions: the CSV exports (
/certificates/export, and the audit-log export withformat=csv) returntext/csvas an attachment.
Pagination
All list endpoints use offset (page-number) pagination:
GET /api/v1/projects/{projectId}/certificates?page=1&page_size=20
# →
{
"certificates": [ ... ], // the key is named after the resource
"total": 137,
"page": 1,
"page_size": 20
}
page defaults to 1; page_size defaults to 20 and is clamped to a maximum of 100 (a larger value is silently reduced, not rejected). Because this is offset paging, rows inserted or deleted between requests can shift the window — a row may be seen twice or skipped. Sort explicitly and, for exports, prefer the dedicated export endpoints over walking pages.
A few feeds are cursor-paged instead — the certificate timeline takes an opaque cursor plus limit (default 50, max 100), and job-log tailing (/jobs/{id}/logs/since) takes after_id plus limit. Don't parse or manipulate a cursor.
Filtering & sorting
Per-endpoint query params. The pattern:
GET /api/v1/projects/{projectId}/certificates
?status=active
&expires_in_days=30 # or &expiring_within=30 — capped at a third of each certificate's lifetime
&issuer_type=acme
&search=example.com
&sort_by=expires_at
&sort_desc=false
Common to every paginated list: search (free text, surrounding spaces and NUL bytes dropped, cut to its first 200 characters — never refused for its length), sort_by (each endpoint accepts only its own allow-listed fields) and sort_desc=true. Filters take a single value — there are no comma-separated OR lists. Per-field knobs are documented in the in-app API docs and on each feature page linked from the full reference.
Error shape
error is a flat string, not a nested object. The default shape is:
HTTP 400 Bad Request
Content-Type: application/json
{ "error": "domain not under the selected zone" }
A few responses add structured context alongside it. A policy violation on certificate creation:
HTTP 422 Unprocessable Entity
{
"error": "policy_violation",
"message": "key type ECDSA-P256 is not allowed by this project's policy",
"violations": [ { "rule": "allowed_key_types", ... } ]
}
And a blocked delete:
HTTP 409 Conflict
{
"error": "cannot delete: resource is referenced by other resources",
"code": "DEPENDENCY_CONFLICT",
"references": [ ... ],
"suggestion": "..."
}
A licence cap refusal on certificate creation / import is 403 with {"error": "certificate_limit_reached", "limit": …, "current": …}. Renewals and reissues are never refused by the cap. Creating a distribution target beyond the Free plan's one-target cap is 403 with {"error": "target_limit_reached", "message": …, "limit": …, "current": …}.
A delete whose dependency check could not finish in time is refused with 503, "code": "DEPENDENCY_CHECK_UNAVAILABLE" and Retry-After — nothing was deleted; send it again.
There is no request_id field in error bodies, and no details array — write clients against the status code plus the error string, and treat violations / references / code as extras present only on those paths. The sign-in routes (/auth/login, /auth/refresh, /auth/otp/verify) name their reason in error_type instead (SIGN_IN_METHOD_UNAVAILABLE, LDAP_BUSY, TOKEN_REUSE).
Common status codes
| Code | Meaning in this API |
|---|---|
| 200 | OK — GET / PATCH / DELETE success (a DELETE returns a small JSON message, not an empty body). |
| 201 | Created — POST that created a resource. |
| 202 | Accepted — the action became an approval request (approval_request in the body) instead of running. |
| 400 | Client error — malformed JSON, bad enum. A path or query that is not valid UTF-8 (for example %ff) is refused with code: INVALID_QUERY_ENCODING; a query part that does not decode at all (100%) is ignored, as before. |
| 401 | No auth / expired auth. |
| 403 | Authenticated but role insufficient, CSRF check failed, or a licence cap is reached (certificates, or the Free plan's one target). code: ACCESS_DENIED marks a refusal for a missing role — a user limited to granted resources gets it for a resource it sees without the needed role (Resource grants). |
| 404 | Resource not found (or not visible to your tenant, or — for a user limited to granted resources — not granted to you). |
| 409 | Conflict — duplicate, state precondition failed, delete blocked by dependents. |
| 413 | A proposed change too large to queue for approval (a request body over 1 MiB fails with 400 instead). |
| 422 | Unprocessable — policy violation, validation failure. |
| 429 | Rate-limited; the response carries Retry-After. |
| 503 | Service unavailable — returned by /readyz while a dependency is down, by /auth/login when the directory is busy (LDAP_BUSY, with Retry-After), by /auth/refresh when the session could not be checked (the session is kept; try again), and by the discovery reads with code: DISCOVERY_VISIBILITY_UNAVAILABLE when what a user limited to granted discovery sources may see could not be worked out (Resource grants), and by a delete with code: DEPENDENCY_CHECK_UNAVAILABLE (with Retry-After) when what depends on the resource could not be checked in time. |
Idempotency
There is no Idempotency-Key header — the server ignores it. Retrying a POST can create a second resource, so a client that retries on a network error should first look the resource up (e.g. list certificates by name) before re-sending a create. Some operations are deduplicated server-side anyway: repeating a bulk action over the same selection while the first is still running returns the running one, and a second open approval request for the same resource and operation, or a second rollback while one is running, is refused rather than duplicated.
Rate limits
- Login: 10 attempts per IP per minute → 429, and 5 per minute per username. Refresh: 10 per minute per refresh token (600 per IP). OTP verify: 10 per minute per waiting sign-in (300 per IP). Initial
/setup: 5 per minute. - Per-route quotas (built in, fixed): e.g. certificate create / import 10 per minute per project, distribution execute + rollback 5 per minute per project (shared), dry-run 5, discovery scan 10, module browse 60, credential / secret-store tests 20, job retry 20, password change 5 per user, two-factor disable + recovery-code regeneration 10 per user (shared), approval actions 10 per user, audit-chain verify 1 per minute. The per-route values are listed in the full reference. A refused request gets
429withRetry-After. - CA-imposed limits: cert issuance respects the CA's weekly quotas (zone page surfaces them). Not the same as CertAutoPilot's own rate limit.
Request correlation
- Every response carries
X-Request-ID. Log it; it's the key into the server logs and the audit entry for that request. - Clients can set their own request ID by sending
X-Request-ID— the server echoes it.
Client libraries
Official client: none (yet), and no OpenAPI document is served — there is no /api/v1/openapi.json. Everything is plain JSON, so any curl / ky / requests / go http.Client works; the in-app API Docs page is the authoritative endpoint reference.
See also
Video tutorial
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →