# API keys and the API Everything you do in the dashboard to services, databases, domains and notifications you can do over a REST API. It is JSON over HTTPS, authenticated with an API key. - **Base URL**: `https://onkilby.com/api/v1` - **Reference**: [/api/docs](/api/docs), with every endpoint, example, error and permission, and code samples in several languages. It is public: you do not need an account to read it. - **OpenAPI 3.1**: [/api/v1/openapi.json](/api/v1/openapi.json). No key needed. Give it to a code generator, Postman or an AI agent. Each operation carries its required permission in `x-kilby-permission`. - **List prices as JSON**: `GET /api/v1/pricing`, no key needed. ## Create a key In the dashboard open **API keys** and create one. You need to be an Admin or the Owner of the workspace, and Kilby may ask you to sign in again. - **Name and description**: say where the key will be used. You see the name in the list, with when it was last used. - **Role**: Viewer, Developer or Admin (below). - **Expiry**: never, 30 days, 90 days, 1 year, or a date up to 10 years away. A key that expired answers `401 key_expired`. - Kilby shows the key **once**, in the same dialog, with commands for curl, the Kilby CLI and MCP that already contain it. It starts with `kby_`. Kilby stores only a hash of it, so it cannot show it again: if you lose it, make a new one. - A key belongs to one workspace. - Revoke a key and anything that uses it fails with `401` at once. - A key can never do more than the person who made it: it acts with the lower of its own role and its creator's current role in the workspace. If the creator is demoted or removed, so is the key. - Keys are created and revoked in the dashboard only, never through the API: a key that could create keys would outlive its own revocation. ## Roles of a key | Key role | For | Can | Cannot | |---|---|---|---| | **Viewer** | Looks, never changes. For dashboards, monitoring and read-only automation. | Read services, deploys, builds, logs, metrics, databases, backups, domains and usage | Create, change or delete anything; See database passwords or change registry credentials and build variables; Change webhook endpoints or email notifications | | **Developer** | Deploys and runs things. For CI, scripts, the kilby command line tool and AI agents. | Read services, deploys, builds, logs, metrics, databases, backups, domains and usage; Create, change, deploy, roll back, suspend and delete services and databases; Read and change registry credentials, build variables and database passwords | Change webhook endpoints or email notifications | | **Admin** | Everything a developer key can do, and webhooks and notifications. For automation that sets the workspace up. | Read services, deploys, builds, logs, metrics, databases, backups, domains and usage; Create, change, deploy, roll back, suspend and delete services and databases; Read and change registry credentials, build variables and database passwords; Manage webhook endpoints and email notifications | Nothing the API offers beyond the other two keys' limits. | The permissions behind these roles are the same as for a person: see [Workspaces, roles and 2FA](/docs/workspaces.md). No key role can add members, create keys, open a shell or change workspace settings. ## Make a request ```sh export KILBY_API_KEY="" curl -sS -H "Authorization: Bearer $KILBY_API_KEY" https://onkilby.com/api/v1/workspace curl -sS -H "Authorization: Bearer $KILBY_API_KEY" https://onkilby.com/api/v1/services ``` - Send the key as `Authorization: Bearer `. Send and expect `application/json`, except logs, which are plain text. - Every answer carries an `X-Request-Id` header. Quote it if you ask for help. - Each key may make 300 requests a minute. Beyond that, the answer is `429 rate_limited` with a `Retry-After` header: wait that many seconds. Repeated requests with keys that do not exist are slowed down too. - A workspace that required two-factor authentication before sign-in moved to Neuramorphic sign-in refuses a key whose creator has not signed in since (`two_factor_required`). - Creating a service or a database returns at once and the work continues in the background. Poll the resource until its `status` is `live`, `available` or `failed`. ### Errors Every error is JSON: `{"error": {"code": "...", "message": "..."}}`. The `code` is stable, and the `message` is written for people. | Status | Code | When | |---|---|---| | 400 | `bad_request` | The request could not be read. | | 401 | `unauthorized` | There is no API key, or it is not valid or was revoked. | | 401 | `key_expired` | The key's expiry date has passed. Create a new key. | | 403 | `forbidden` | The key's role does not allow this, or the key's creator lost access to the workspace. | | 403 | `two_factor_required` | The workspace requires two-factor authentication and the person who created the key has no second factor on record yet. | | 404 | `not_found` | The resource does not exist in this workspace. | | 409 | `conflict` | The request is fine, but the resource is not in a state where it can be done. | | 409 | `not_connected` | GitHub is not turned on for this Kilby, or its App is not registered yet. | | 422 | `invalid_request` | A field is missing or not valid, or a limit was reached. The message says which. | | 429 | `rate_limited` | Too many requests. Wait for the time in the Retry-After header. | | 500 | `internal` | Something failed on our side. Try again, and quote the X-Request-Id. | | 502 | `github_unavailable` | GitHub could not be reached or answered something Kilby could not read. Try again in a moment. | | 503 | `unavailable` | A part of Kilby this request needs is not available in this environment. | ## Every endpoint There are 153 endpoints. This list is made from the same catalog as the reference and the OpenAPI document. "Needs" is the permission a key's role must hold (`view`, `deploy`, `secrets`, `workspace`). #### Introduction | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/openapi.json` | Download the OpenAPI description | no key | #### Services | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/services` | List services | view | | `POST /api/v1/services` | Create a service | deploy | | `GET /api/v1/services/{id}` | Get a service | view | | `PATCH /api/v1/services/{id}` | Change a service | deploy | | `DELETE /api/v1/services/{id}` | Delete a service | deploy | | `POST /api/v1/services/{id}/suspend` | Suspend a service | deploy | | `POST /api/v1/services/{id}/resume` | Resume a service | deploy | | `PUT /api/v1/services/{id}/maintenance` | Turn maintenance mode on or off | deploy | | `GET /api/v1/services/{id}/logs` | Read logs | view | | `GET /api/v1/services/{id}/metrics` | Read CPU and memory | view | | `GET /api/v1/services/{id}/metrics/requests` | Read request metrics | view | | `GET /api/v1/services/{id}/events` | List events | view | | `GET /api/v1/services/{id}/disk/snapshots` | List disk snapshots | deploy | | `POST /api/v1/services/{id}/disk/snapshots/{snapshot_id}/restore` | Restore a disk snapshot | workspace | | `POST /api/v1/images/check` | Check a container image | deploy | #### Projects | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/projects` | List projects | view | | `POST /api/v1/projects` | Create a project | deploy | | `GET /api/v1/projects/{id}` | Get a project | view | | `PATCH /api/v1/projects/{id}` | Rename a project | deploy | | `DELETE /api/v1/projects/{id}` | Delete a project | workspace | | `GET /api/v1/projects/{id}/environments` | List the environments of a project | view | | `POST /api/v1/projects/{id}/environments` | Create an environment | deploy | | `GET /api/v1/projects/{id}/environments/{env}` | Get an environment | view | | `PATCH /api/v1/projects/{id}/environments/{env}` | Rename an environment | deploy | | `DELETE /api/v1/projects/{id}/environments/{env}` | Delete an environment | workspace | #### Deploys and builds | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/services/{id}/deploys` | List deploys | view | | `POST /api/v1/services/{id}/deploys` | Redeploy a service | deploy | | `GET /api/v1/services/{id}/deploys/{deploy}/rollback-preview` | Preview a rollback | deploy | | `POST /api/v1/services/{id}/rollback` | Roll back to an earlier deploy | deploy | | `GET /api/v1/services/{id}/builds` | List builds | view | | `POST /api/v1/services/{id}/builds` | Start a build | deploy | | `GET /api/v1/services/{id}/builds/{build}` | Get a build | view | | `GET /api/v1/services/{id}/builds/{build}/logs` | Read a build's log | view | | `POST /api/v1/services/{id}/builds/{build}/cancel` | Cancel a build | deploy | | `POST /api/v1/services/{id}/builds/{build}/retry` | Retry a build | deploy | #### Environment | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/services/{id}/build-env` | List build variables | view | | `PUT /api/v1/services/{id}/build-env` | Replace build variables | secrets | | `GET /api/v1/services/{id}/env` | List environment variables | view | | `PATCH /api/v1/services/{id}/env` | Change environment variables | secrets | | `PATCH /api/v1/services/{id}/build-env` | Change build variables | secrets | | `GET /api/v1/registry-credentials` | List registry credentials | view | | `POST /api/v1/registry-credentials` | Add registry credentials | secrets | | `PATCH /api/v1/registry-credentials/{id}` | Replace a token | secrets | | `DELETE /api/v1/registry-credentials/{id}` | Delete registry credentials | secrets | | `GET /api/v1/services/{id}/secret-files` | List secret files | view | | `PUT /api/v1/services/{id}/secret-files/{name}` | Add or replace a secret file | secrets | | `DELETE /api/v1/services/{id}/secret-files/{name}` | Delete a secret file | secrets | #### Environment groups | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/env-groups` | List environment groups | view | | `POST /api/v1/env-groups` | Create an environment group | secrets | | `GET /api/v1/env-groups/{id}` | Read an environment group | view | | `PATCH /api/v1/env-groups/{id}` | Change an environment group | secrets | | `DELETE /api/v1/env-groups/{id}` | Delete an environment group | deploy | | `GET /api/v1/services/{id}/env-groups` | List the groups a service uses | view | | `PUT /api/v1/services/{id}/env-groups` | Link groups to a service | deploy | | `GET /api/v1/services/{id}/env/effective` | List the effective environment | view | #### Databases | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/databases` | List databases | view | | `POST /api/v1/databases` | Create a database | deploy | | `PUT /api/v1/databases/{id}/autogrow` | Grow the disk automatically | deploy | | `GET /api/v1/databases/{id}` | Get a database | view | | `PATCH /api/v1/databases/{id}` | Update a database | deploy | | `DELETE /api/v1/databases/{id}` | Delete a database | deploy | | `GET /api/v1/databases/{id}/backups` | List backups | view | | `POST /api/v1/databases/{id}/backups` | Take a backup now | deploy | | `POST /api/v1/databases/{id}/restore` | Restore a database | deploy | | `GET /api/v1/databases/{id}/imports` | List imports | view | | `POST /api/v1/databases/{id}/imports` | Import from another Postgres | secrets | | `GET /api/v1/databases/{id}/imports/{import_id}` | Get an import | view | | `DELETE /api/v1/databases/{id}/import-source` | Forget the saved source | secrets | #### Key Value | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/key-values` | List Key Value instances | view | | `POST /api/v1/key-values` | Create a Key Value instance | deploy | | `GET /api/v1/key-values/{id}` | Get a Key Value instance | view | | `PATCH /api/v1/key-values/{id}` | Change the size or the eviction policy | deploy | | `DELETE /api/v1/key-values/{id}` | Delete a Key Value instance | deploy | | `GET /api/v1/key-values/{id}/connection` | Get the connection | secrets | #### Cron | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/services/{id}/runs` | List runs | view | | `POST /api/v1/services/{id}/runs` | Start a run now | deploy | #### Domains | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/services/{id}/domains` | List domains | view | | `POST /api/v1/services/{id}/domains` | Add a custom domain | deploy | | `POST /api/v1/domains/{id}/verify` | Check a domain's DNS now | deploy | | `PATCH /api/v1/domains/{id}` | Redirect a domain | deploy | | `PATCH /api/v1/services/{id}/primary-domain` | Choose the primary address | deploy | | `DELETE /api/v1/domains/{id}` | Remove a domain | deploy | #### Workspaces | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/workspace` | Get the workspace | view | | `GET /api/v1/workspace/network` | Get the outbound IP addresses | view | | `GET /api/v1/usage` | Read usage | view | | `GET /api/v1/notifications` | Get email notifications | view | | `PATCH /api/v1/notifications` | Change email notifications | workspace | #### GitHub and Git | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/git/installations` | List GitHub connections | view | | `GET /api/v1/git/repos` | List repositories | view | | `GET /api/v1/git/branches` | List branches | view | | `GET /api/v1/git/commit` | Get the latest commit of a branch | view | | `GET /api/v1/git/public/check` | Check a public repository | deploy | | `GET /api/v1/git/public/plan` | Analyse a public repository | deploy | | `GET /api/v1/git/plan` | Analyse a repository | deploy | #### Blueprints | Endpoint | What it does | Needs | |---|---|---| | `POST /api/v1/blueprints/plan` | Plan a blueprint | deploy | | `POST /api/v1/blueprints` | Create a blueprint | deploy | | `GET /api/v1/blueprints` | List blueprints | view | | `GET /api/v1/blueprints/{id}` | Read a blueprint | view | | `POST /api/v1/blueprints/{id}/sync` | Sync a blueprint now | deploy | | `POST /api/v1/blueprints/{id}/approve` | Approve a sync | deploy | | `GET /api/v1/blueprints/{id}/syncs` | List the syncs of a blueprint | view | #### Billing and pricing | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/pricing` | Read the price list | no key | | `GET /api/v1/billing` | Read the plan and the limits | view | | `GET /api/v1/billing/invoices` | List invoices | workspace | #### Kilby AI | Endpoint | What it does | Needs | |---|---|---| | `POST /api/v1/services/{id}/builds/{build}/analyze` | Explain a failed build | deploy | | `GET /api/v1/services/{id}/builds/{build}/analysis` | Read the analysis of a build | view | | `POST /api/v1/services/{id}/deploys/{deploy}/analyze` | Explain a failed deploy | deploy | | `GET /api/v1/services/{id}/deploys/{deploy}/analysis` | Read the analysis of a deploy | view | #### Templates | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/templates` | List templates | view | | `GET /api/v1/templates/{id}` | Get a template | view | | `POST /api/v1/templates/{id}/deploy` | Deploy a template | deploy | #### Webhooks | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/services/{id}/deploy-hook` | Get a deploy hook | view | | `POST /api/v1/services/{id}/deploy-hook` | Create a deploy hook | deploy | | `DELETE /api/v1/services/{id}/deploy-hook` | Revoke a deploy hook | deploy | | `POST /hooks/deploy/{token}` | Deploy with a deploy hook | no key | | `GET /api/v1/services/{id}/git-hook` | Get a build hook | view | | `POST /api/v1/services/{id}/git-hook` | Create a build hook | deploy | | `DELETE /api/v1/services/{id}/git-hook` | Revoke a build hook | deploy | | `POST /hooks/git/{token}` | Build the latest commit with a build hook | no key | | `GET /api/v1/webhooks` | List webhook endpoints | view | | `POST /api/v1/webhooks` | Add a webhook endpoint | workspace | | `GET /api/v1/webhooks/{id}` | Get a webhook endpoint | view | | `PATCH /api/v1/webhooks/{id}` | Change a webhook endpoint | workspace | | `DELETE /api/v1/webhooks/{id}` | Delete a webhook endpoint | workspace | | `POST /api/v1/webhooks/{id}/test` | Send a test event | workspace | | `POST /api/v1/webhooks/{id}/secret` | Roll the signing secret | workspace | | `GET /api/v1/webhooks/{id}/deliveries` | List deliveries | view | #### DNS AI | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/dns/zones` | List zones | view | | `POST /api/v1/dns/zones` | Create a zone | workspace | | `GET /api/v1/dns/zones/{id}` | Get a zone | view | | `POST /api/v1/dns/zones/{id}/verify` | Check the ownership record | workspace | | `DELETE /api/v1/dns/zones/{id}` | Delete a zone | workspace | | `PUT /api/v1/dns/zones/{id}/records` | Create or replace a record set | workspace | | `DELETE /api/v1/dns/zones/{id}/records/{type}/{name}` | Delete a record set | workspace | | `POST /api/v1/dns/zones/{id}/capture` | Capture today's records | workspace | | `POST /api/v1/domains/{id}/configure-dns` | Configure a custom domain from its zone | workspace | #### Log streams | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/log-streams` | List log streams | view | | `POST /api/v1/log-streams` | Add a log stream | workspace | | `GET /api/v1/log-streams/{id}` | Read a log stream | view | | `PATCH /api/v1/log-streams/{id}` | Change a log stream | workspace | | `DELETE /api/v1/log-streams/{id}` | Delete a log stream | workspace | | `POST /api/v1/log-streams/{id}/test` | Send a test line | workspace | #### Pull request previews | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/services/{id}/previews` | Get a service's previews | view | | `PATCH /api/v1/services/{id}/previews` | Change a service's preview settings | secrets | | `DELETE /api/v1/previews/{id}` | Remove a preview | deploy | #### Slack | Endpoint | What it does | Needs | |---|---|---| | `GET /api/v1/slack-destinations` | List Slack destinations | view | | `POST /api/v1/slack-destinations` | Connect a Slack channel | workspace | | `GET /api/v1/slack-destinations/{id}` | Get a Slack destination | view | | `PATCH /api/v1/slack-destinations/{id}` | Change a Slack destination | workspace | | `DELETE /api/v1/slack-destinations/{id}` | Delete a Slack destination | workspace | | `POST /api/v1/slack-destinations/{id}/test` | Send a test message | workspace | | `GET /api/v1/slack-destinations/{id}/deliveries` | List deliveries to a Slack destination | view | ## Related - [Use Kilby from an AI agent](/docs/agents.md): which key an agent should get, and the safety model. - [Workspaces, roles and 2FA](/docs/workspaces.md): the permissions behind the roles. - [Webhooks and notifications](/docs/webhooks.md): events pushed to you. - [CLI](/docs/cli.md): the `kilby` command uses the same API.