On this page
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, 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. 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. No key role can add members, create keys, open a shell or change workspace settings.
Make a request#
shexport KILBY_API_KEY="<your 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 <key>. 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 |