Reference
API reference
Everything the console and the CLI do, they do through this API. It is a plain JSON HTTP interface authenticated with a bearer token.
Base URL
https://console.codaracloud.comAuthenticating
Send an API token as a bearer token on every request. Create one from Settings → API tokens or with codaracloud token create — see Getting access.
bash
$ curl -H "Authorization: Bearer cdr_live_xxxxxxxx" \ https://console.codaracloud.com/v1/appsA token only reaches what its scopes allow. A request outside them returns 403 naming the scope that was required.
Authentication exceptions are narrow
The health check and interactive sign-in routes are public. GitHub webhooks and builder callbacks use their own service authentication. Resource-management routes require a browser session or bearer token.
Conventions
This page is a practical index
The tables below cover the endpoints most operators use; they are not an exhaustive schema listing. The generated
openapi.json in the platform API package is the authoritative machine-readable contract.Scoping
Most resources live inside a client, project and environment. Identify them with query parameters:
bash
$ curl -H "Authorization: Bearer $CODARA_TOKEN" \ "https://console.codaracloud.com/v1/apps?client_slug=my-workspace&project_slug=website&environment_slug=production"On read endpoints, omitted scope falls back to your default workspace and the production environment. When a name is ambiguous across projects, the API returns 409 and asks you to specify.
Creating a resource will not guess the project
POST
A project is normally one product with its own repository, so creating a new project is usually the right answer rather than reusing an existing one.
/v1/apps and POST /v1/jobs resolve project_slug only when the client owns exactly one project. With more than one, the request is refused with workspace_required and the message lists the candidates — it will not pick one for you. With none, you get no_workspace and are told to create one first.A project is normally one product with its own repository, so creating a new project is usually the right answer rather than reusing an existing one.
Use the slug field, not the display name
Resources may carry both a physical
slug and a friendlier display value. Always address resources by the slug field returned by the API.List responses
Most collection endpoints return an envelope with a cursor for pagination:
json
{ "items": [ … ], "next_cursor": null}Not every list endpoint uses this shape — a few return a differently named array — so read the field you actually get rather than assuming.
Errors
Errors are JSON with a machine-readable code and a human message:
json
{ "error": "not_found", "message": "app 'my-api' not found"}| Status | Means |
|---|---|
| 400 | Invalid request. Usually bad_request. |
| 401 | Missing, invalid or expired credential. |
| 403 | Authenticated, but the token lacks the required scope. |
| 404 | No such resource in the scope you asked for. |
| 402 | Not allowed by the plan: plan_limit_exceeded (names the limit, with allowed and current values), plan_feature_unavailable, or subscription_not_active. |
| 409 | Conflict — a name already in use, an ambiguous lookup, or a precondition not met. |
| 503 | A dependency was temporarily unavailable. Retry. |
Identity
| Endpoint | Purpose | |
|---|---|---|
| GET | /v1/me | The current user and the workspaces they can see. |
| GET | /v1/tokens | List API tokens. |
| POST | /v1/tokens | Create a token. The secret is returned once. |
| DELETE | /v1/tokens/{id} | Revoke a token. |
Apps
| Endpoint | Purpose | |
|---|---|---|
| GET | /v1/apps | List apps. |
| POST | /v1/apps | Create an app. Pass the client, project and environment explicitly whenever the name would otherwise be ambiguous. |
| GET | /v1/apps/{name} | App detail. |
| PATCH | /v1/apps/{name} | Update runtime, source or policy. |
| DELETE | /v1/apps/{name} | Delete an app. |
| PUT | /v1/apps/{name}/image | Point at a new image reference. |
| PUT | /v1/apps/{name}/autosleep | Configure automatic sleeping. |
| GET | /v1/apps/{name}/connections | Databases, private apps and buckets connected to the app. |
Creating an app does not build it
POST
/v1/apps leaves a repo-backed app pointing at a placeholder image. Follow it with a build request or the app will never start.Builds and deploys
| Endpoint | Purpose | |
|---|---|---|
| POST | /v1/apps/{name}/builds | Trigger a build. This is the endpoint that starts a release. |
| GET | /v1/apps/{name}/deploys | Deploy history. |
| GET | /v1/apps/{name}/deploys/{deploy_id} | One deploy in detail. |
| GET | /v1/apps/{name}/deploys/{deploy_id}/logs | Build output. Empty after 24 hours. |
| POST | /v1/apps/{name}/deploys/{deploy_id}/cancel | Cancel before promotion. |
| POST | /v1/apps/{name}/deploys/{deploy_id}/rollback | Re-release this deploy’s image. Only the app’s 10 most recent successful deploys can be restored, while their image exists. |
| POST | /v1/apps/{name}/deploys/{deploy_id}/promote-to-environment | Promote into another environment. |
Use /builds to start a release
Trigger source builds through
/v1/apps/{name}/builds. There is no public POST /v1/apps/{name}/deploys route in the production contract.Configuration
| Endpoint | Purpose | |
|---|---|---|
| GET | /v1/apps/{name}/env | List variables. Values are masked. |
| PATCH | /v1/apps/{name}/env | Bulk set and unset in one request, with { set, unset }. |
| GET | /v1/apps/{name}/env/{key} | Reveal one value. Requires env:reveal. Audit-logged. |
bash
$ curl -X PATCH \ -H "Authorization: Bearer $CODARA_TOKEN" \ -H "content-type: application/json" \ -d '{"set":{"LOG_LEVEL":"debug"},"unset":["OLD_KEY"]}' \ https://console.codaracloud.com/v1/apps/my-api/envDatabases, storage and jobs
| Endpoint | Purpose | |
|---|---|---|
| GET | /v1/databases | List databases. |
| POST | /v1/databases | Provision a database. |
| GET | /v1/databases/{name}/connection | Connection details. |
| GET | /v1/databases/{name}/backups | List backups. |
| POST | /v1/databases/{name}/backup | Back up now. PostgreSQL and dedicated Redis only. |
| GET | /v1/buckets | List object storage buckets. |
| POST | /v1/buckets | Create an object-storage bucket. No self-serve plan includes buckets; they need a separate agreement. |
| GET | /v1/jobs | List jobs. |
| POST | /v1/jobs | Create a one-shot or scheduled job. |
| PATCH | /v1/jobs/{name} | Change a scheduled job’s OCI image and/or suspend future runs. |
| GET | /v1/apps/{name}/volumes | Volumes attached to an app. |
Database metrics need two scopes
Reading
/v1/databases/{name}/metrics requires a database read scope and metrics:read.Domains, logs, metrics and cost
| Endpoint | Purpose | |
|---|---|---|
| GET | /v1/apps/{name}/domains | Hostnames with live DNS and certificate status. |
| POST | /v1/apps/{name}/domains | Attach a hostname. |
| DELETE | /v1/apps/{name}/domains/{host} | Detach a hostname. |
| GET | /v1/apps/{name}/logs | Runtime log tail. |
| GET | /v1/apps/{name}/metrics | CPU, memory, replicas and restarts. |
| GET | /v1/cost/summary | Operator-only live OpenCost cluster and workspace roll-up. |
| GET | /v1/cost/clients/{slug} | Operator-only workspace OpenCost allocation. |
| GET | /v1/cost/clients/{slug}/invoices | Operator-only internal monthly cost ledger. |
Domain status is worth polling
POST to attach a domain reports success optimistically while DNS and the certificate are still provisioning. The truthful readiness signal is the status field on GET
/v1/apps/{name}/domains.Clients and projects
| Endpoint | Purpose | |
|---|---|---|
| GET | /v1/clients | List clients. |
| POST | /v1/clients | Create an empty workspace. Projects are created separately. |
| PATCH | /v1/clients/{client} | Update a client. |
| GET | /v1/clients/{client}/deletion-preflight | Workspace deletion checklist: every project's blockers plus workspace-level retained storage, each with its remedy. |
| DELETE | /v1/clients/{client} | Delete an empty workspace (cascades its projects and environments). 409 with the checklist while anything remains — never cascades data. |
| GET | /v1/clients/{slug}/projects | List projects. |
| POST | /v1/clients/{slug}/projects | Create a project. |
| GET | /v1/clients/{slug}/projects/{project}/environments | List environments. |
| GET | /v1/clients/{slug}/projects/{project}/deletion-preflight | Deletion checklist: every app (with volume data), database, job, bucket and retained storage still blocking the delete, each with its remedy. |
| GET | /v1/clients/{slug}/projects/{project}/environments/{env}/deletion-preflight | Same checklist for one environment, plus its default-env and preview-source gates. |
| DELETE | /v1/clients/{slug}/projects/{project} | Delete an empty project (cascades its environments). 409 with the checklist while anything remains — never cascades data. |
| GET | /v1/clients/{client}/quotas | Operator-only internal spend cap and enforcement mode. |
Avoid the client-level environment routes
Older endpoints of the form
/v1/clients/{slug}/environments still exist but assume a project named default and behave incorrectly otherwise. Use the project-scoped routes above.What is not in the API
A few things are deliberately outside the public contract and should not be called directly: the OAuth sign-in redirects, the GitHub webhook, and the internal callbacks the build system uses.
Last updated