Skip to the page
KilbyDocs
Automate View as Markdown
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 roleForCanCannot
ViewerLooks, never changes. For dashboards, monitoring and read-only automation.Read services, deploys, builds, logs, metrics, databases, backups, domains and usageCreate, change or delete anything; See database passwords or change registry credentials and build variables; Change webhook endpoints or email notifications
DeveloperDeploys 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 passwordsChange webhook endpoints or email notifications
AdminEverything 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 notificationsNothing 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#

sh
export 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.

StatusCodeWhen
400bad_requestThe request could not be read.
401unauthorizedThere is no API key, or it is not valid or was revoked.
401key_expiredThe key's expiry date has passed. Create a new key.
403forbiddenThe key's role does not allow this, or the key's creator lost access to the workspace.
403two_factor_requiredThe workspace requires two-factor authentication and the person who created the key has no second factor on record yet.
404not_foundThe resource does not exist in this workspace.
409conflictThe request is fine, but the resource is not in a state where it can be done.
409not_connectedGitHub is not turned on for this Kilby, or its App is not registered yet.
422invalid_requestA field is missing or not valid, or a limit was reached. The message says which.
429rate_limitedToo many requests. Wait for the time in the Retry-After header.
500internalSomething failed on our side. Try again, and quote the X-Request-Id.
502github_unavailableGitHub could not be reached or answered something Kilby could not read. Try again in a moment.
503unavailableA 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#

EndpointWhat it doesNeeds
GET /api/v1/openapi.jsonDownload the OpenAPI descriptionno key

Services#

EndpointWhat it doesNeeds
GET /api/v1/servicesList servicesview
POST /api/v1/servicesCreate a servicedeploy
GET /api/v1/services/{id}Get a serviceview
PATCH /api/v1/services/{id}Change a servicedeploy
DELETE /api/v1/services/{id}Delete a servicedeploy
POST /api/v1/services/{id}/suspendSuspend a servicedeploy
POST /api/v1/services/{id}/resumeResume a servicedeploy
PUT /api/v1/services/{id}/maintenanceTurn maintenance mode on or offdeploy
GET /api/v1/services/{id}/logsRead logsview
GET /api/v1/services/{id}/metricsRead CPU and memoryview
GET /api/v1/services/{id}/metrics/requestsRead request metricsview
GET /api/v1/services/{id}/eventsList eventsview
GET /api/v1/services/{id}/disk/snapshotsList disk snapshotsdeploy
POST /api/v1/services/{id}/disk/snapshots/{snapshot_id}/restoreRestore a disk snapshotworkspace
POST /api/v1/images/checkCheck a container imagedeploy

Projects#

EndpointWhat it doesNeeds
GET /api/v1/projectsList projectsview
POST /api/v1/projectsCreate a projectdeploy
GET /api/v1/projects/{id}Get a projectview
PATCH /api/v1/projects/{id}Rename a projectdeploy
DELETE /api/v1/projects/{id}Delete a projectworkspace
GET /api/v1/projects/{id}/environmentsList the environments of a projectview
POST /api/v1/projects/{id}/environmentsCreate an environmentdeploy
GET /api/v1/projects/{id}/environments/{env}Get an environmentview
PATCH /api/v1/projects/{id}/environments/{env}Rename an environmentdeploy
DELETE /api/v1/projects/{id}/environments/{env}Delete an environmentworkspace

Deploys and builds#

EndpointWhat it doesNeeds
GET /api/v1/services/{id}/deploysList deploysview
POST /api/v1/services/{id}/deploysRedeploy a servicedeploy
GET /api/v1/services/{id}/deploys/{deploy}/rollback-previewPreview a rollbackdeploy
POST /api/v1/services/{id}/rollbackRoll back to an earlier deploydeploy
GET /api/v1/services/{id}/buildsList buildsview
POST /api/v1/services/{id}/buildsStart a builddeploy
GET /api/v1/services/{id}/builds/{build}Get a buildview
GET /api/v1/services/{id}/builds/{build}/logsRead a build's logview
POST /api/v1/services/{id}/builds/{build}/cancelCancel a builddeploy
POST /api/v1/services/{id}/builds/{build}/retryRetry a builddeploy

Environment#

EndpointWhat it doesNeeds
GET /api/v1/services/{id}/build-envList build variablesview
PUT /api/v1/services/{id}/build-envReplace build variablessecrets
GET /api/v1/services/{id}/envList environment variablesview
PATCH /api/v1/services/{id}/envChange environment variablessecrets
PATCH /api/v1/services/{id}/build-envChange build variablessecrets
GET /api/v1/registry-credentialsList registry credentialsview
POST /api/v1/registry-credentialsAdd registry credentialssecrets
PATCH /api/v1/registry-credentials/{id}Replace a tokensecrets
DELETE /api/v1/registry-credentials/{id}Delete registry credentialssecrets
GET /api/v1/services/{id}/secret-filesList secret filesview
PUT /api/v1/services/{id}/secret-files/{name}Add or replace a secret filesecrets
DELETE /api/v1/services/{id}/secret-files/{name}Delete a secret filesecrets

Environment groups#

EndpointWhat it doesNeeds
GET /api/v1/env-groupsList environment groupsview
POST /api/v1/env-groupsCreate an environment groupsecrets
GET /api/v1/env-groups/{id}Read an environment groupview
PATCH /api/v1/env-groups/{id}Change an environment groupsecrets
DELETE /api/v1/env-groups/{id}Delete an environment groupdeploy
GET /api/v1/services/{id}/env-groupsList the groups a service usesview
PUT /api/v1/services/{id}/env-groupsLink groups to a servicedeploy
GET /api/v1/services/{id}/env/effectiveList the effective environmentview

Databases#

EndpointWhat it doesNeeds
GET /api/v1/databasesList databasesview
POST /api/v1/databasesCreate a databasedeploy
PUT /api/v1/databases/{id}/autogrowGrow the disk automaticallydeploy
GET /api/v1/databases/{id}Get a databaseview
PATCH /api/v1/databases/{id}Update a databasedeploy
DELETE /api/v1/databases/{id}Delete a databasedeploy
GET /api/v1/databases/{id}/backupsList backupsview
POST /api/v1/databases/{id}/backupsTake a backup nowdeploy
POST /api/v1/databases/{id}/restoreRestore a databasedeploy
GET /api/v1/databases/{id}/importsList importsview
POST /api/v1/databases/{id}/importsImport from another Postgressecrets
GET /api/v1/databases/{id}/imports/{import_id}Get an importview
DELETE /api/v1/databases/{id}/import-sourceForget the saved sourcesecrets

Key Value#

EndpointWhat it doesNeeds
GET /api/v1/key-valuesList Key Value instancesview
POST /api/v1/key-valuesCreate a Key Value instancedeploy
GET /api/v1/key-values/{id}Get a Key Value instanceview
PATCH /api/v1/key-values/{id}Change the size or the eviction policydeploy
DELETE /api/v1/key-values/{id}Delete a Key Value instancedeploy
GET /api/v1/key-values/{id}/connectionGet the connectionsecrets

Cron#

EndpointWhat it doesNeeds
GET /api/v1/services/{id}/runsList runsview
POST /api/v1/services/{id}/runsStart a run nowdeploy

Domains#

EndpointWhat it doesNeeds
GET /api/v1/services/{id}/domainsList domainsview
POST /api/v1/services/{id}/domainsAdd a custom domaindeploy
POST /api/v1/domains/{id}/verifyCheck a domain's DNS nowdeploy
PATCH /api/v1/domains/{id}Redirect a domaindeploy
PATCH /api/v1/services/{id}/primary-domainChoose the primary addressdeploy
DELETE /api/v1/domains/{id}Remove a domaindeploy

Workspaces#

EndpointWhat it doesNeeds
GET /api/v1/workspaceGet the workspaceview
GET /api/v1/workspace/networkGet the outbound IP addressesview
GET /api/v1/usageRead usageview
GET /api/v1/notificationsGet email notificationsview
PATCH /api/v1/notificationsChange email notificationsworkspace

GitHub and Git#

EndpointWhat it doesNeeds
GET /api/v1/git/installationsList GitHub connectionsview
GET /api/v1/git/reposList repositoriesview
GET /api/v1/git/branchesList branchesview
GET /api/v1/git/commitGet the latest commit of a branchview
GET /api/v1/git/public/checkCheck a public repositorydeploy
GET /api/v1/git/public/planAnalyse a public repositorydeploy
GET /api/v1/git/planAnalyse a repositorydeploy

Blueprints#

EndpointWhat it doesNeeds
POST /api/v1/blueprints/planPlan a blueprintdeploy
POST /api/v1/blueprintsCreate a blueprintdeploy
GET /api/v1/blueprintsList blueprintsview
GET /api/v1/blueprints/{id}Read a blueprintview
POST /api/v1/blueprints/{id}/syncSync a blueprint nowdeploy
POST /api/v1/blueprints/{id}/approveApprove a syncdeploy
GET /api/v1/blueprints/{id}/syncsList the syncs of a blueprintview

Billing and pricing#

EndpointWhat it doesNeeds
GET /api/v1/pricingRead the price listno key
GET /api/v1/billingRead the plan and the limitsview
GET /api/v1/billing/invoicesList invoicesworkspace

Kilby AI#

EndpointWhat it doesNeeds
POST /api/v1/services/{id}/builds/{build}/analyzeExplain a failed builddeploy
GET /api/v1/services/{id}/builds/{build}/analysisRead the analysis of a buildview
POST /api/v1/services/{id}/deploys/{deploy}/analyzeExplain a failed deploydeploy
GET /api/v1/services/{id}/deploys/{deploy}/analysisRead the analysis of a deployview

Templates#

EndpointWhat it doesNeeds
GET /api/v1/templatesList templatesview
GET /api/v1/templates/{id}Get a templateview
POST /api/v1/templates/{id}/deployDeploy a templatedeploy

Webhooks#

EndpointWhat it doesNeeds
GET /api/v1/services/{id}/deploy-hookGet a deploy hookview
POST /api/v1/services/{id}/deploy-hookCreate a deploy hookdeploy
DELETE /api/v1/services/{id}/deploy-hookRevoke a deploy hookdeploy
POST /hooks/deploy/{token}Deploy with a deploy hookno key
GET /api/v1/services/{id}/git-hookGet a build hookview
POST /api/v1/services/{id}/git-hookCreate a build hookdeploy
DELETE /api/v1/services/{id}/git-hookRevoke a build hookdeploy
POST /hooks/git/{token}Build the latest commit with a build hookno key
GET /api/v1/webhooksList webhook endpointsview
POST /api/v1/webhooksAdd a webhook endpointworkspace
GET /api/v1/webhooks/{id}Get a webhook endpointview
PATCH /api/v1/webhooks/{id}Change a webhook endpointworkspace
DELETE /api/v1/webhooks/{id}Delete a webhook endpointworkspace
POST /api/v1/webhooks/{id}/testSend a test eventworkspace
POST /api/v1/webhooks/{id}/secretRoll the signing secretworkspace
GET /api/v1/webhooks/{id}/deliveriesList deliveriesview

DNS AI#

EndpointWhat it doesNeeds
GET /api/v1/dns/zonesList zonesview
POST /api/v1/dns/zonesCreate a zoneworkspace
GET /api/v1/dns/zones/{id}Get a zoneview
POST /api/v1/dns/zones/{id}/verifyCheck the ownership recordworkspace
DELETE /api/v1/dns/zones/{id}Delete a zoneworkspace
PUT /api/v1/dns/zones/{id}/recordsCreate or replace a record setworkspace
DELETE /api/v1/dns/zones/{id}/records/{type}/{name}Delete a record setworkspace
POST /api/v1/dns/zones/{id}/captureCapture today's recordsworkspace
POST /api/v1/domains/{id}/configure-dnsConfigure a custom domain from its zoneworkspace

Log streams#

EndpointWhat it doesNeeds
GET /api/v1/log-streamsList log streamsview
POST /api/v1/log-streamsAdd a log streamworkspace
GET /api/v1/log-streams/{id}Read a log streamview
PATCH /api/v1/log-streams/{id}Change a log streamworkspace
DELETE /api/v1/log-streams/{id}Delete a log streamworkspace
POST /api/v1/log-streams/{id}/testSend a test lineworkspace

Pull request previews#

EndpointWhat it doesNeeds
GET /api/v1/services/{id}/previewsGet a service's previewsview
PATCH /api/v1/services/{id}/previewsChange a service's preview settingssecrets
DELETE /api/v1/previews/{id}Remove a previewdeploy

Slack#

EndpointWhat it doesNeeds
GET /api/v1/slack-destinationsList Slack destinationsview
POST /api/v1/slack-destinationsConnect a Slack channelworkspace
GET /api/v1/slack-destinations/{id}Get a Slack destinationview
PATCH /api/v1/slack-destinations/{id}Change a Slack destinationworkspace
DELETE /api/v1/slack-destinations/{id}Delete a Slack destinationworkspace
POST /api/v1/slack-destinations/{id}/testSend a test messageworkspace
GET /api/v1/slack-destinations/{id}/deliveriesList deliveries to a Slack destinationview