KilbyAPI reference Docs OpenAPI Sign inCreate an account

Kilby API reference

Deploy and run services, cron jobs and Postgres databases with 153 endpoints over HTTPS and JSON. Everything the dashboard does, your code can do.

Get started Download OpenAPI

Overview

The base address of the API is:

https://onkilby.com/api/v1

Requests and responses are JSON. Timestamps are RFC 3339. Ids are UUIDs. A key works inside one workspace, so a request never needs to say which.

Prefer a client over raw HTTP? The OpenAPI document describes every endpoint on this page, with schemas, permissions and code samples: feed it to a code generator, to Postman or Insomnia, or to an AI agent that should operate Kilby. The kilby command line tool and its MCP server (kilby mcp) are built on this API.

Authentication

Every request carries an API key in the Authorization header. Create a key under API keys in the dashboard; it is shown once, so store it right away.

Authorization: Bearer kby_…

Keep keys out of source code, URLs and logs. Send them only over HTTPS, and revoke a key you think was exposed: it stops working at once. A key that has an expiry date stops working on that date and answers 401 with the code key_expired.

Check that a key works by asking for its workspace:

curl "https://onkilby.com/api/v1/workspace" \
  -H "Authorization: Bearer $KILBY_API_KEY"

Roles and permissions

A key has a role: viewer, developer or admin. It acts with the lower of its own role and the current role in the workspace of the person who created it, so removing someone, or demoting them, limits the keys they made. Every endpoint below shows the permission it needs.

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

64 of 153 endpoints

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

128 of 153 endpoints

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

153 of 153 endpoints

PermissionWhat it allowsViewerDeveloperAdmin
viewRead services, deploys, builds, logs, metrics, databases, backups, domains and usage●●●
deployCreate, change, deploy, roll back, suspend and delete services and databases–●●
secretsRead and change registry credentials, build variables and database passwords–●●
workspaceManage webhook endpoints and email notifications––●

Members, API keys and workspace settings are managed in the dashboard only. A key that could create keys or members would outlive its own revocation.

Errors

Errors use the matching HTTP status and always have this shape. Branch on code; show message to people, and do not match on its wording.

{"error": {"code": "invalid_request", "message": "Port must be a number between 1 and 65535."}}
  • 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.

Successful requests answer 200 (read or change), 201 (created), 202 (accepted: Kilby is doing it and the answer shows where things stand) or 204 (done, nothing to return). Poll the resource to follow work in progress.

Request IDs

Every response from /api/v1, including errors, has an X-Request-Id header such as req_9f2c41d07a6b3e58. Log it with your own request, and quote it if you ask for help. Kilby logs it too, with every unexpected error.

Rate limits

A key may make 300 requests a minute. Past that, requests answer 429 with the code rate_limited and a Retry-After header in seconds. Requests with an unknown, revoked or expired key are limited to 30 per 10 minutes per address. Request bodies can be up to 512 KB.

Some endpoints that start something costly have limits of their own:

  • Builds started by hand: 30 per hour per workspace.
  • Deploy hooks created: 20 per hour; calling a deploy hook: 10 per minute per hook and 60 per minute per address.
  • Webhook endpoints created: 20 per hour; test events: 10 per minute per endpoint.
  • Custom domains added: 30 per hour; checking a domain's DNS: 6 per minute per domain.

Pagination

Most lists return everything there is: the workspace is small by design. Three are limited, and say how to get more:

  • List builds returns 20 builds by default (up to 100 with limit). The answer's next_before is the value to send as before for the next page; it is null on the last.
  • Read a build's log returns lines after a sequence number (after) and tells you where to continue (next_after).
  • Deploys and runs show the last 50, deliveries the last 100.

Idempotency

Kilby does not support idempotency keys. Retrying a request that changes something does it again, with two exceptions that make retries safe: resources that have a unique name (services, databases, registry credentials, domains) answer 409 when the name exists, so if a create times out, retry it and treat 409 as "already there" by reading the resource. Reads, PATCH, PUT and DELETE can be repeated without harm. Things that start work, such as a redeploy or a backup, run again each time.

Versioning

The version is in the path: /api/v1. Within a version, Kilby adds things without notice: new endpoints, new fields in responses and new values of fields such as status. Write clients that ignore fields they do not know. Requests are stricter: a body with a field Kilby does not know is refused with 422, so a typo cannot silently do nothing.

A change that could break a client would ship as a new version beside this one, announced in the changelog.

GET/api/v1/openapi.json #

Download the OpenAPI description

No API key

The whole API as an OpenAPI 3.1 document, generated from the same catalog as this reference. It needs no API key and can be cached.

Use it to generate a client in any language, to import the API into Postman or Insomnia, or to give an AI agent or code generator an accurate map of Kilby. Every operation carries its required permission in x-kilby-permission and ready-to-run samples in x-codeSamples.

Response

200
The OpenAPI document.

Returns an object.

Errors

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/openapi.json
curl "https://onkilby.com/api/v1/openapi.json"
{
  "openapi": "3.1.0",
  "info": {"title": "Kilby API", "version": "1"},
  "paths": {}
}
Runs in your browser against this server.

Services

A service is anything Kilby runs for you: a web service with a public address, a private service that only your other services can reach, a background worker or a cron job. They all share one set of endpoints; type says which kind you are dealing with.

GET/api/v1/services #

List services

view Any key

Every web service, private service, background worker and cron job of the workspace, newest first. Databases are listed by List databases.

Response

200
The services.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services
curl "https://onkilby.com/api/v1/services" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "services": [
    {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "my-api",
      "type": "web",
      "image": "ghcr.io/acme/api:1.4",
      "port": 8080,
      "plan": "starter",
      "status": "live",
      "status_message": "",
      "suspended": false,
      "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai",
      "internal_address": "my-api:8080",
      "created_at": "2026-11-12T22:40:11Z",
      "updated_at": "2026-11-13T14:05:00Z",
      "registry_credential_id": null,
      "health_check_path": "/healthz",
      "instances": 2,
      "autoscaling": {"min": 2, "max": 4, "target_cpu_percent": 70},
      "disk": null,
      "instances_running": 2,
      "instances_desired": 2,
      "pre_deploy_command": "",
      "pre_deploy_timeout_seconds": 600,
      "source": null,
      "environment": {
        "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
        "name": "Production",
        "default": true,
        "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
      },
      "auto_concurrency": true,
      "render_compat": false,
      "stop_first": false,
      "read_only_root": false,
      "maintenance": false,
      "maintenance_message": "",
      "primary_domain": "my-api-x7k2.apps.kilby.neuramorphic.ai",
      "primary_domain_choice": null
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services #

Create a service

deploy Developer key or higher

Creates a service and starts its first deploy. The answer is the service, with status pending or building: poll Get a service until status is live (or scheduled for a cron job) or failed.

Run an image with image, or build a repository with source; send one of them. A cron job needs a schedule instead of a port. Workers and cron jobs take no port.

The workspace has limits on the number of services, on CPU and memory in total, and on disk. A request that would exceed them answers 422 and says which limit.

Request body

  • namestringrequired
    Unique in the workspace. It becomes the service's internal host name, and part of its public address.

    3 to 40 characters: lowercase letters, digits and hyphens, starting with a letter. Not starting with db-.

  • typestring
    What kind of service to create.

    One of web, private, worker, cron. Default web.

  • imagestring
    The container image to run, for example ghcr.io/acme/api:1.4. It must come from a registry on the internet. Required unless you send source.

    a registry reference, tag or digest.

  • commandstring
    Replaces the image's own start command.

    up to 2,000 characters.

  • schedulestring
    Five cron fields, in UTC. Required for a cron job, not allowed otherwise.
  • portinteger
    The port the service listens on. Required for web and private services.

    1 to 65535.

  • planstring
    The instance type: starter is 0.5 CPU and 512 MB, standard is 1 CPU and 2 GB, pro is 2 CPU and 4 GB.

    One of starter, standard, pro. Default starter.

  • envobject of string
    Environment variables, name to value. Values are stored encrypted.

    up to 100 variables, values up to 8 KB.

  • Build the service from a Git repository instead of running an image: kind git needs the GitHub App connected, kind public_git builds a public repository from its archive and needs only that deploying from Git is on; see GitHub and Git.
  • kindstringrequired
    git for a repository the GitHub connection can read, public_git for a public repository built from its archive (no GitHub connection).

    One of git, public_git.

  • urlurl
    kind public_git: the https address of the repository, on one of the hosts this Kilby allows. Required for public_git.
  • refstring
    kind public_git: the branch, tag or commit to build.

    Default the repository's default branch.

  • auto_checkboolean
    kind public_git: check for new commits every 15 minutes and build them. Off by default; a workspace can turn it on for a few services.

    Default false.

  • installation_idinteger
    kind git: the GitHub connection of this workspace that can read the repository.
  • repostring
    kind git: owner/name.
  • branchstring
    The branch to build and to follow.

    Default the repository's default branch.

  • root_dirstring
    The folder to build, for a monorepo. Empty is the repository root.
  • dockerfile_pathstring
    A Dockerfile to use, relative to root_dir. Empty: Kilby uses the Dockerfile it finds, or writes one.
  • build_planobject
    The build plan the detector proposed, to build exactly what was shown. Leave it out to let Kilby detect it.
  • auto_deployboolean
    Build and deploy on a push to the branch that changes a file in the service's folder (root_dir; the whole repository when it is empty).

    Default true.

  • build_envobject of string
    Variables available while building (not at runtime). Their values are stored encrypted and never returned.
  • environmentstring
    Where to list the service: an environment id, project/environment by names, or an environment name when only one has it. Leave it out for the default one, Production of the Default project. See Projects.
  • registry_credential_iduuid or null
    Credentials to pull a private image with, from POST /registry-credentials. null, or an empty string, means a public image.
  • health_check_pathstring
    An HTTP path the service must answer with 2xx or 3xx before a deploy goes live. Web and private services only. Empty: the port only has to accept connections.

    starts with /, up to 200 characters.

  • instancesinteger
    A fixed number of instances. Send either instances or autoscaling, not both.

    Default 1.

    1 to 10.

  • Follow CPU use between a minimum and a maximum. Not for cron jobs.
  • minintegerrequired
    At least this many instances.

    1 to 10.

  • maxintegerrequired
    At most this many instances.

    2 to 10, at least min.

  • target_cpu_percentintegerrequired
    Add instances above this average CPU use, remove them below it.

    10 to 95.

  • A persistent disk for web, private and worker services. A service with a disk runs exactly one instance, and a disk cannot be removed again.
  • mount_pathstringrequired
    Where it appears inside the container, for example /data.
  • size_gbintegerrequired
    Size in GB. It can grow, once every 6 hours, but not shrink.

    1 to 50.

  • pre_deploy_commandstring or null
    A command that runs once before every deploy, with the new image and the new environment, in a one-off container of the same instance type. Kilby waits for it to exit with code 0 before the new version starts: if it fails or runs out of time the deploy fails and the running version is not changed. Usually database migrations. It runs with /bin/sh -c, so the image needs a shell, and it may run more than once for the same version (a retry after a restart of Kilby or a redeploy; a rollback does not run it), so it must be safe to repeat. Not for cron jobs. null, or an empty string, means none.

    up to 2,000 characters.

  • pre_deploy_timeout_secondsinteger or null
    The most time the pre-deploy command may take, counted from the start of its container, so including starting a machine and pulling the image. It is stopped at the limit and the deploy fails. null means the default.

    Default 600.

    10 to 1800.

Response

201
The new service. For a service built from Git, source.latest_build holds the first build.

Returns a Service object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 422invalid_request

    A field is not valid, a limit of the workspace would be exceeded, or the name is taken.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/services
curl -X POST "https://onkilby.com/api/v1/services" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-api",
  "type": "web",
  "image": "ghcr.io/acme/api:1.4",
  "port": 8080,
  "plan": "starter",
  "env": {"LOG_LEVEL": "info"}
}'
{
  "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "name": "my-api",
  "type": "web",
  "image": "ghcr.io/acme/api:1.4",
  "port": 8080,
  "plan": "starter",
  "status": "deploying",
  "status_message": "",
  "suspended": false,
  "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai",
  "internal_address": "my-api:8080",
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "registry_credential_id": null,
  "health_check_path": "",
  "instances": 1,
  "autoscaling": null,
  "disk": null,
  "instances_running": 0,
  "instances_desired": 1,
  "pre_deploy_command": "",
  "pre_deploy_timeout_seconds": 600,
  "source": null,
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "auto_concurrency": true,
  "render_compat": false,
  "stop_first": false,
  "read_only_root": false,
  "maintenance": false,
  "maintenance_message": "",
  "primary_domain": "my-api-x7k2.apps.kilby.neuramorphic.ai",
  "primary_domain_choice": null
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id} #

Get a service

view Any key

One service with its status, address and how it runs.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The service.

Returns a Service object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "name": "my-api",
  "type": "web",
  "image": "ghcr.io/acme/api:1.4",
  "port": 8080,
  "plan": "starter",
  "status": "live",
  "status_message": "",
  "suspended": false,
  "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai",
  "internal_address": "my-api:8080",
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "registry_credential_id": null,
  "health_check_path": "/healthz",
  "instances": 2,
  "autoscaling": {"min": 2, "max": 4, "target_cpu_percent": 70},
  "disk": null,
  "instances_running": 2,
  "instances_desired": 2,
  "pre_deploy_command": "",
  "pre_deploy_timeout_seconds": 600,
  "source": null,
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "auto_concurrency": true,
  "render_compat": false,
  "stop_first": false,
  "read_only_root": false,
  "maintenance": false,
  "maintenance_message": "",
  "primary_domain": "my-api-x7k2.apps.kilby.neuramorphic.ai",
  "primary_domain_choice": null
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/services/{id} #

Change a service

deploy Developer key or higher

Send only what changes: everything you leave out stays as it is. A change that affects the running service starts a new deploy: without a disk the old version serves until the new one is ready, with a disk the service is down for a short time.

env is the exception: when it is present it replaces all variables, so send the ones you keep as well. Leave it out to keep the current variables.

The type of a service cannot change. Fields that do not apply to it, such as port on a worker, are refused.

A service built from Git is changed with source, which is a request of its own: every field of it is optional, and saving does not deploy, a build does (rebuild: true). Applying one of the fixes of a failed build is exactly this request with the fix's field and value. Send source.version, the value from Get a service, to refuse the change with 409 when somebody else edited the source settings after you read them. Kilby re-checks every value whatever the client was shown, so a fix can never apply something you did not send.

Path parameters

  • iduuidrequired
    The service's id.

Request body

  • imagestring
    A new image or tag to deploy.
  • commandstring
    Replaces the start command. An empty string goes back to the image's own.
  • schedulestring
    A new schedule, for a cron job.
  • portinteger
    A new port.

    1 to 65535.

  • planstring
    A different instance type.

    One of starter, standard, pro.

  • envobject of string
    All environment variables. They replace the current ones as a whole.
  • auto_concurrencyboolean
    Whether Kilby sets WEB_CONCURRENCY from the instance type (its CPU rounded up, at least 1), unless you define it yourself. Only for web and private services; the answer's auto_concurrency says where it stands. It is on for services created after this setting existed and off for older ones until you turn it on. The value changes with the instance type at the next deploy.
  • render_compatboolean
    Whether Kilby also sets Render's variables (RENDER=true, RENDER_EXTERNAL_HOSTNAME, RENDER_GIT_COMMIT and the others it can fill truthfully) with this service's values, for code written for Render. A variable you define yourself always wins. It changes at the next deploy.
  • stop_firstboolean
    Only for background workers and private services: stop the old instance before starting the new one on every deploy, for a program that must run as a single copy (a queue consumer, a scheduler). The two never overlap, but nothing runs between the old one stopping and the new one starting, and if the new version fails to start the service stays down until you roll back or deploy again. Off by default. Saving starts a deploy, which is the first to work this way.
  • read_only_rootboolean
    Whether the service's container runs with a read-only root filesystem: it can write only in /tmp (an empty folder of up to 1 GB, emptied when an instance restarts) and on its disk. Off by default; images that write next to their code fail to start with it. It changes at the next deploy, which this change starts.
  • For a service built from Git: change where and how it builds. Send it on its own, not together with the runtime settings above.
  • versionstring
    The source.version you read. If the settings changed since, the answer is 409 and nothing is written.
  • branchstring
    The branch to build and follow. Kilby checks it can read it.
  • root_dirstring
    The folder to build. Kilby reads the new folder again and takes its plan; commands in the same request win over it.
  • dockerfile_pathstring
    A Dockerfile, relative to root_dir. An empty string goes back to the default.
  • install_commandstring
  • build_commandstring
    An empty string clears it.
  • start_commandstring
  • portinteger
    A number, or a number written as a string. A service built from Git has one port.
  • health_pathstring
    The health check path, as for health_check_path.
  • auto_deployboolean
    Build and deploy on a push that changes a file in the service's folder. Not for a public_git service: it has no push webhook.
  • auto_checkboolean
    public_git only: check for new commits every 15 minutes.
  • build_planBuildPlan
    A whole plan, as returned by GET /git/plan or GET /git/public/plan.
  • root_dirstringrequired
    The folder that is built. Empty is the repository root.
  • strategystringrequired
    Whether Kilby builds your Dockerfile or writes one.

    One of dockerfile, generated.

  • runtimestringrequired

    One of node, python, go, static, docker.

  • frameworkstringrequired
    For example next, vite, express, fastapi or flask. Empty when none was recognised.
  • dockerfile_pathstringrequired
    Only for strategy dockerfile, relative to root_dir.
  • install_commandstringrequired
  • build_commandstringrequired
  • start_commandstringrequired
  • portintegerrequired
    0 for a worker.
  • health_pathstringrequired
    Empty when there is no good guess.
  • plan_idstringrequired
    The instance type Kilby suggests.

    One of starter, standard, pro.

  • envarray of objectrequired
    Variables the code reads, found in files such as .env.example.
  • notesarray of stringrequired
    What was found and why, in plain sentences.
  • warningsarray of stringrequired
    What might go wrong.
  • candidatesarray of objectrequired
    Other buildable folders, in a monorepo.
  • kindstring
    A suggestion for the service type.

    One of web, worker.

  • versionstring
    The runtime version the image uses.
  • package_managerstring
    For example npm, pnpm, pip or uv.
  • output_dirstring
    The folder that holds the build output.
  • root_routeboolean
    The code routes /, and no health route was found: the dashboard offers / as the health check. Only present when true.
  • build_envobject of string or null
    Build variables to set. They merge into the current ones, and null removes one. Needs the secrets permission.
  • planstring
    The instance type from the next deploy. A service that was never built cannot change it.

    One of starter, standard, pro.

  • rebuildboolean
    Build the latest commit once the changes are saved. Can be sent alone. Only for services built from Git.
  • environmentstring
    Move the service to this environment: an id, project/environment by names, or a name only one environment has. Moving only changes where the service is listed: nothing restarts and nothing deploys. Send it on its own, not together with the settings above.
  • registry_credential_iduuid or null
    Credentials to pull a private image with, from POST /registry-credentials. null, or an empty string, means a public image.
  • health_check_pathstring
    An HTTP path the service must answer with 2xx or 3xx before a deploy goes live. Web and private services only. Empty: the port only has to accept connections.

    starts with /, up to 200 characters.

  • instancesinteger
    A fixed number of instances. Send either instances or autoscaling, not both.

    Default 1.

    1 to 10.

  • Follow CPU use between a minimum and a maximum. Not for cron jobs.
  • minintegerrequired
    At least this many instances.

    1 to 10.

  • maxintegerrequired
    At most this many instances.

    2 to 10, at least min.

  • target_cpu_percentintegerrequired
    Add instances above this average CPU use, remove them below it.

    10 to 95.

  • A persistent disk for web, private and worker services. A service with a disk runs exactly one instance, and a disk cannot be removed again.
  • mount_pathstringrequired
    Where it appears inside the container, for example /data.
  • size_gbintegerrequired
    Size in GB. It can grow, once every 6 hours, but not shrink.

    1 to 50.

  • pre_deploy_commandstring or null
    A command that runs once before every deploy, with the new image and the new environment, in a one-off container of the same instance type. Kilby waits for it to exit with code 0 before the new version starts: if it fails or runs out of time the deploy fails and the running version is not changed. Usually database migrations. It runs with /bin/sh -c, so the image needs a shell, and it may run more than once for the same version (a retry after a restart of Kilby or a redeploy; a rollback does not run it), so it must be safe to repeat. Not for cron jobs. null, or an empty string, means none.

    up to 2,000 characters.

  • pre_deploy_timeout_secondsinteger or null
    The most time the pre-deploy command may take, counted from the start of its container, so including starting a machine and pulling the image. It is stopped at the limit and the deploy fails. null means the default.

    Default 600.

    10 to 1800.

Response

200
The service after the change.

Returns a Service object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The service is built from Git and its first build has not finished yet, or source.version is out of date.

  • 422invalid_request

    A field is not valid, or the change would exceed a limit of the workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 502github_unavailable

    Kilby could not read the repository from GitHub to check the new source settings.

PATCHhttps://onkilby.com/api/v1/services/{id}
curl -X PATCH "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "ghcr.io/acme/api:1.5"}'
{
  "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "name": "my-api",
  "type": "web",
  "image": "ghcr.io/acme/api:1.4",
  "port": 8080,
  "plan": "starter",
  "status": "deploying",
  "status_message": "",
  "suspended": false,
  "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai",
  "internal_address": "my-api:8080",
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "registry_credential_id": null,
  "health_check_path": "/healthz",
  "instances": 2,
  "autoscaling": {"min": 2, "max": 4, "target_cpu_percent": 70},
  "disk": null,
  "instances_running": 1,
  "instances_desired": 2,
  "pre_deploy_command": "",
  "pre_deploy_timeout_seconds": 600,
  "source": null,
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "auto_concurrency": true,
  "render_compat": false,
  "stop_first": false,
  "read_only_root": false,
  "maintenance": false,
  "maintenance_message": "",
  "primary_domain": "my-api-x7k2.apps.kilby.neuramorphic.ai",
  "primary_domain_choice": null
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/services/{id} #

Delete a service

deploy Developer key or higher

Deletes the service, its deploys and its disk. This cannot be undone. The service is removed in the background: it answers 202 and the service is gone from the list within a minute.

Path parameters

  • iduuidrequired
    The service's id.

Response

202
The service is being deleted.
  • iduuidrequired
  • statusstringrequired
    Always deleting.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The service is already being deleted.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/services/{id}
curl -X DELETE "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea", "status": "deleting"}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/suspend #

Suspend a service

deploy Developer key or higher

Stops the service and keeps its settings, address and disk. A suspended service costs nothing to run. Cron jobs stop running on their schedule.

Path parameters

  • iduuidrequired
    The service's id.

Response

202
The service, with suspended true.

Returns a Service object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The service is already suspended or is being deleted.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/services/{id}/suspend
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/suspend" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "name": "my-api",
  "type": "web",
  "image": "ghcr.io/acme/api:1.4",
  "port": 8080,
  "plan": "starter",
  "status": "suspended",
  "status_message": "",
  "suspended": false,
  "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai",
  "internal_address": "my-api:8080",
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "registry_credential_id": null,
  "health_check_path": "/healthz",
  "instances": 2,
  "autoscaling": {"min": 2, "max": 4, "target_cpu_percent": 70},
  "disk": null,
  "instances_running": 2,
  "instances_desired": 2,
  "pre_deploy_command": "",
  "pre_deploy_timeout_seconds": 600,
  "source": null,
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "auto_concurrency": true,
  "render_compat": false,
  "stop_first": false,
  "read_only_root": false,
  "maintenance": false,
  "maintenance_message": "",
  "primary_domain": "my-api-x7k2.apps.kilby.neuramorphic.ai",
  "primary_domain_choice": null
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/resume #

Resume a service

deploy Developer key or higher

Starts a suspended service again, with its current settings: a change made while it was suspended applies now. Its pre-deploy command is not run when the image and the command are those of the last deploy whose command succeeded or was skipped (the deploy says so); otherwise it runs as for any deploy. A service that Kilby's administrators suspended cannot be resumed this way.

Path parameters

  • iduuidrequired
    The service's id.

Response

202
The service, deploying again.

Returns a Service object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The service is not suspended.

  • 422invalid_request

    Resuming would exceed a limit of the workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/services/{id}/resume
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/resume" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "name": "my-api",
  "type": "web",
  "image": "ghcr.io/acme/api:1.4",
  "port": 8080,
  "plan": "starter",
  "status": "deploying",
  "status_message": "",
  "suspended": false,
  "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai",
  "internal_address": "my-api:8080",
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "registry_credential_id": null,
  "health_check_path": "/healthz",
  "instances": 2,
  "autoscaling": {"min": 2, "max": 4, "target_cpu_percent": 70},
  "disk": null,
  "instances_running": 0,
  "instances_desired": 2,
  "pre_deploy_command": "",
  "pre_deploy_timeout_seconds": 600,
  "source": null,
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "auto_concurrency": true,
  "render_compat": false,
  "stop_first": false,
  "read_only_root": false,
  "maintenance": false,
  "maintenance_message": "",
  "primary_domain": "my-api-x7k2.apps.kilby.neuramorphic.ai",
  "primary_domain_choice": null
}
Runs in your browser against your workspace with a key you paste.
PUT/api/v1/services/{id}/maintenance #

Turn maintenance mode on or off

deploy Developer key or higher

While maintenance mode is on, visitors of the web service get a Kilby page that says it is under maintenance (status 503, with Retry-After), on its address and on its custom domains. The instances keep running, nothing is deployed or restarted, and turning it off serves the service again within seconds. The page shows your message as plain text and says nothing about who you are or what runs. Send the same request again to change the message; message left out keeps the stored one, which is kept while maintenance mode is off.

Only web services have a public address, so only they have maintenance mode. It needs the platform to show pages of its own and answers 503 otherwise, saving nothing.

Path parameters

  • iduuidrequired
    The service's id.

Request body

  • enabledbooleanrequired
    true turns maintenance mode on, false turns it off.
  • messagestring
    What the page tells visitors. Plain text; line breaks are kept.

    up to 280 characters.

Response

200
The service, with maintenance and maintenance_message as they are now.

Returns a Service object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The service is not a web service, or it is being deleted.

  • 422invalid_request

    enabled is missing, or the message is longer than 280 characters or has control characters.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 503unavailable

    The platform does not show pages of its own yet, so there is nothing to turn on.

PUThttps://onkilby.com/api/v1/services/{id}/maintenance
curl -X PUT "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/maintenance" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "message": "We are upgrading the database. Back at 14:00 UTC."
}'
{
  "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "name": "my-api",
  "type": "web",
  "image": "ghcr.io/acme/api:1.4",
  "port": 8080,
  "plan": "starter",
  "status": "live",
  "status_message": "",
  "suspended": false,
  "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai",
  "internal_address": "my-api:8080",
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "registry_credential_id": null,
  "health_check_path": "/healthz",
  "instances": 2,
  "autoscaling": {"min": 2, "max": 4, "target_cpu_percent": 70},
  "disk": null,
  "instances_running": 2,
  "instances_desired": 2,
  "pre_deploy_command": "",
  "pre_deploy_timeout_seconds": 600,
  "source": null,
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "auto_concurrency": true,
  "render_compat": false,
  "stop_first": false,
  "read_only_root": false,
  "maintenance": true,
  "maintenance_message": "We are upgrading the database. Back at 14:00 UTC.",
  "primary_domain": "my-api-x7k2.apps.kilby.neuramorphic.ai",
  "primary_domain_choice": null
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/logs #

Read logs

view Any key

Reads a service's log in one of two ways.

Live. Without any of since, until, q, level, limit, cursor, order or format, it returns the most recent lines of the service's running instances as plain text, oldest first (200 with text/plain). This is a snapshot, not a stream: call it again to see newer lines. tail says how many.

Stored. With any of those parameters it reads what Kilby kept, including what instances that crashed or were replaced printed. The answer is JSON as shown here, or plain text with format=text (the next cursor is then in the Kilby-Next-Cursor header). Logs are kept for a number of days, 7 unless the platform says otherwise; a service that prints more than a few hundred lines a second is capped and the stored log says how many lines were left out. One request reads a bounded amount: when partial is true the search stopped before the end of the range, so narrow the time range or continue with next_cursor. Use absolute times to page: a relative since moves between requests. It needs log storage to be on, and answers 503 otherwise.

Path parameters

  • iduuidrequired
    The service's id.

Query parameters

  • tailinteger
    Live only: how many lines to return.

    Default 200.

    1 to 2000.

  • sincestring
    Stored: start of the range, inclusive. A time like 2026-11-14T10:00:00Z, or how long ago: 15m, 1h, 24h, 7d.

    Default 1h before until.

  • untilstring
    Stored: end of the range, exclusive. A time or how long ago.

    Default now.

  • qstring
    Stored: only lines that contain this text, ignoring case. A plain substring, not a pattern.

    up to 200 characters.

  • levelstring
    Stored: only lines of these levels, comma separated: error, warn, info, debug. The level is guessed from the text of each line (a level field of a JSON line, level=, or words such as ERROR and WARN).
  • limitinteger
    Stored: how many lines to return.

    Default 200.

    1 to 1000.

  • orderstring
    Stored: desc returns the newest lines first, asc the oldest first.

    One of desc, asc. Default desc.

  • cursorstring
    Stored: next_cursor of the previous answer to the same request, to read the next page.
  • formatstring
    Stored: json, or text for plain lines like 2026-11-14T10:00:00.123Z [x2k4p] message.

    One of json, text. Default json.

Response

200
Stored logs: a page of lines. Without the stored parameters the answer is the live text described above.
  • linesarray of LogLinerequired
    In the order asked for.
  • timedatetimerequired
    When the container printed it.
  • instancestring
    The short name of the instance that printed it. Empty for a line Kilby wrote.
  • messagestringrequired
    The text, up to 16 KB; a longer line is cut and says so.
  • levelstringrequired
    error, warn, info or debug, guessed from the text.

    One of error, warn, info, debug.

  • kilbyboolean
    true for a line Kilby wrote itself, such as how many lines were not stored.
  • next_cursorstringrequired
    Pass it as cursor for the next page. Empty when the range holds nothing more.
  • partialbooleanrequired
    true when the search stopped at its limit before the end of the range.
  • notestringrequired
    Says what happened when partial is true. Empty otherwise.
  • orderstringrequired
    desc or asc.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    A time, level, limit or cursor is not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 503unavailable

    Live logs are not available in this environment, or stored logs were asked for and log storage is off.

GEThttps://onkilby.com/api/v1/services/{id}/logs
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/logs?tail=100" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "lines": [
    {
      "time": "2026-11-13T14:09:03.412Z",
      "instance": "x2k4p",
      "message": "panic: runtime error: invalid memory address or nil pointer dereference",
      "level": "error"
    },
    {
      "time": "2026-11-13T14:09:01.120Z",
      "instance": "x2k4p",
      "message": "GET /v1/chat 200 412ms",
      "level": "info"
    }
  ],
  "next_cursor": "1.q3k9Xw2b.MTc5NDYzNTc0MTEyMDAwMDAwMC80Mi8w",
  "partial": false,
  "note": "",
  "order": "desc"
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/metrics #

Read CPU and memory

view Any key

CPU and memory the service used against its limit, in steps of 1 minute (1h) up to 30 minutes (7d). CPU is in cores, memory in MB. metrics_available is false, and the figures are null, until Kilby has measured the service.

Cron jobs have no live metrics; their run time is in Read usage.

Path parameters

  • iduuidrequired
    The service's id.

Query parameters

  • rangestring
    How far back to look.

    One of 1h, 6h, 24h, 7d. Default 1h.

Response

200
The measurements.
  • rangestringrequired
  • fromdatetimerequired
  • todatetimerequired
  • step_secondsintegerrequired
    The time each point averages.
  • metrics_availablebooleanrequired
    false when nothing has been measured yet.
  • pointsarray of MetricPointrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    range is not one of the four values, or the service is a cron job.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/metrics
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics?range=24h" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "range": "24h",
  "from": "2026-11-12T14:10:00Z",
  "to": "2026-11-13T14:10:00Z",
  "step_seconds": 300,
  "metrics_available": true,
  "points": [
    {
      "time": "2026-11-13T14:05:00Z",
      "instances": 2,
      "cpu_used": 0.042,
      "cpu_peak": 0.11,
      "cpu_limit": 0.5,
      "memory_used_mb": 182,
      "memory_peak_mb": 190,
      "memory_limit_mb": 512
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/metrics/requests #

Read request metrics

view Any key

What a web service served: requests per second, responses by status class, the share of 5xx responses and latency percentiles. Kilby reads the counts from the proxy that serves your service, every 30 seconds. Up to 6h the points are minutes (1h) or 5 minutes; 24h and longer come from hourly totals kept for 30 days, so a point is an hour (24h, 7d) or 6 hours (30d).

Latency is how long the service took to answer, from the moment the proxy sent the request to it. Percentiles are estimated from the proxy's latency buckets, by interpolation inside the bucket. They are null when too few requests were served to say anything: fewer than min_samples for p50 and p95, fewer than min_samples_p99 for p99. error_rate is the share of responses that were 5xx, between 0 and 1; it is null without requests. A point has requests_per_second: null when Kilby could not have counted yet, which is not the same as zero requests.

available is false, and there are no points, when request metrics are not turned on in this environment. state says whether the proxy is being read: ok, starting or unavailable.

Only web services receive requests through Kilby's proxy: other kinds answer 422. The numbers are the service's own; paths, hosts, addresses and headers are never recorded.

Path parameters

  • iduuidrequired
    The service's id.

Query parameters

  • rangestring
    How far back to look.

    One of 1h, 6h, 24h, 7d, 30d. Default 1h.

Response

200
The request metrics.
  • rangestringrequired
  • fromdatetimerequired
  • todatetimerequired
  • step_secondsintegerrequired
    What one point adds up.
  • statestringrequired
    Whether Kilby is reading the proxy.

    One of ok, starting, unavailable, off.

  • availablebooleanrequired
    false when request metrics are not turned on in this environment.
  • summaryobject or nullrequired
    The whole range in a few numbers. null when not available.
  • requestsintegerrequired
    Responses in the range.
  • statusobjectrequired
    Responses per class.
  • error_ratenumber or nullrequired
    5xx divided by all responses, 0 to 1. null without requests.
  • requests_per_second_averagenumberrequired
  • requests_per_second_peaknumberrequired
    The busiest point, averaged over its step.
  • latency_msobjectrequired
    Percentiles of the whole range, in milliseconds.
  • pointsarray of RequestPointrequired
  • timedatetimerequired
    The start of the step.
  • requestsintegerrequired
    Responses in the step, all classes.
  • requests_per_secondnumber or nullrequired
    Average over the step. null where Kilby could not have counted yet, which is not zero.
  • statusobjectrequired
    Responses per status class.
  • error_ratenumber or nullrequired
    5xx divided by all responses, 0 to 1. null without requests.
  • latency_msobjectrequired
    Latency percentiles of the step, in milliseconds. null where too few requests were served.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    range is not one of the five values, or the service is not a web service.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/metrics/requests
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics/requests?range=24h" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "range": "1h",
  "from": "2026-11-14T09:14:00Z",
  "to": "2026-11-14T10:14:00Z",
  "step_seconds": 60,
  "state": "ok",
  "available": true,
  "summary": {
    "requests": 1840,
    "status": {"1xx": 0, "2xx": 1790, "3xx": 12, "4xx": 30, "5xx": 8},
    "error_rate": 0.004348,
    "requests_per_second_average": 0.5111,
    "requests_per_second_peak": 0.9,
    "latency_ms": {
      "p50": 38.2,
      "p95": 142.5,
      "p99": 610.0,
      "samples": 1840,
      "min_samples": 20,
      "min_samples_p99": 100
    }
  },
  "points": [
    {
      "time": "2026-11-14T10:13:00Z",
      "requests": 54,
      "requests_per_second": 0.9,
      "status": {"1xx": 0, "2xx": 52, "3xx": 0, "4xx": 1, "5xx": 1},
      "error_rate": 0.018519,
      "latency_ms": {
        "p50": 35.0,
        "p95": 150.0,
        "p99": 480.0,
        "samples": 54,
        "min_samples": 20,
        "min_samples_p99": 100
      }
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/events #

List events

view Any key

What happened to the service in the last 1h, 6h, 24h or 7d, newest first: the events the Metrics tab marks on its charts. They are deploys (started, live, failed, crashed, rolled back), restarts of a container of a running service, changes of the instance count, the instance type or the disk, suspend and resume, changes of settings and environment variables, custom domains, and the maintenance windows of the status page that touch the service.

Every event has a kind, which is what kind filters by (deploy, failure, scale, state, config or maintenance), and a more exact type. by says who did it: a person, the hook (a deploy hook), the system (Kilby), or unknown for a person whose account is gone. The two moments of a deploy, its start and its outcome, are two events with their own times.

Only what Kilby recorded is listed. It does not record the steps of the autoscaler, and the list never fills such a gap in. A restart (restarted, in the failure group) is a container of a running service that died and was started again. Kilby looks for them about once a minute and writes at most one such event per service per minute: its title says why the container died only when the cluster said so (it ran out of memory, or its health check failed), and detail gives the exit code, how long the instance had run and how many restarts the event covers. at is when the instance stopped. A service that restarted is still live: its status is not changed by it. Changes made before Kilby began to note what a settings change touched read Settings changed. Variable names appear in an event, never their values.

Up to 200 events are kept per range: when there are more, the newest are returned and truncated is true. The same events are on the Metrics tab of the service, next to its charts.

Path parameters

  • iduuidrequired
    The service's id.

Query parameters

  • rangestring
    How far back to look. The same ranges as the metrics.

    One of 1h, 6h, 24h, 7d. Default 1h.

  • kindstring
    Only events of these kinds. Repeat it or separate the kinds with commas.

    One of deploy, failure, scale, state, config, maintenance.

  • limitinteger
    How many events to return.

    Default 100.

    1 to 200.

Response

200
The events.
  • rangestringrequired
  • fromdatetimerequired
  • todatetimerequired
  • truncatedbooleanrequired
    true when the range holds more events than were returned: the oldest are left out.
  • eventsarray of objectrequired
    Newest first.
  • idstringrequired
    Stays the same every time the event is read.
  • typestringrequired
    What happened, exactly.

    One of deploy_started, deploy_live, deploy_failed, crashed, restarted, rolled_back, scaled, resized, disk_changed, suspended, resumed, created, env_changed, settings_changed, domain_changed, maintenance.

  • kindstringrequired
    The group of the type.

    One of deploy, failure, scale, state, config, maintenance.

  • titlestringrequired
    A short sentence.
  • detailstringrequired
    More about it: the image, how long it took, what changed. Empty when there is nothing to add.
  • atdatetimerequired
    When it happened.
  • byobjectrequired
    Who did it.
  • urlstringrequired
    The page in the dashboard that tells more.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    range is not one of the four values, kind is not a kind, or limit is not a number from 1 to 200.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/events
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events?kind=failure%2Cscale&limit=100&range=24h" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "range": "24h",
  "from": "2026-11-13T14:10:00Z",
  "to": "2026-11-14T14:10:00Z",
  "truncated": false,
  "events": [
    {
      "id": "d-5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d-live",
      "type": "deploy_live",
      "kind": "deploy",
      "title": "Deploy live",
      "detail": "took 1m 12s · api:1.4",
      "at": "2026-11-14T13:41:12Z",
      "by": {"kind": "system", "name": "Kilby"},
      "url": "https://kilby.example.com/dashboard/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events#d-5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d"
    },
    {
      "id": "d-5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d-start",
      "type": "deploy_started",
      "kind": "deploy",
      "title": "Deploy started",
      "detail": "After a settings change · api:1.4",
      "at": "2026-11-14T13:40:00Z",
      "by": {"kind": "person", "name": "Ada Lovelace"},
      "url": "https://kilby.example.com/dashboard/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events#d-5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d"
    },
    {
      "id": "e-4812",
      "type": "scaled",
      "kind": "scale",
      "title": "Instance count changed",
      "detail": "Instances: 1 → 2",
      "at": "2026-11-14T13:40:00Z",
      "by": {"kind": "person", "name": "Ada Lovelace"},
      "url": "https://kilby.example.com/dashboard/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/disk/snapshots #

List disk snapshots

deploy Developer key or higher

Snapshots of the service's disk, newest first, and the disks restored from them. Kilby snapshots every disk once a day and keeps the snapshots for retention_days. A snapshot is a copy of the whole disk, taken while the service runs, so it is crash-consistent: like the disk after a power cut.

Needs a key with the Developer role or higher; a Viewer key is refused. When snapshots are not switched on for this platform, enabled is false and the lists are empty.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The snapshots.
  • enabledbooleanrequired
    false when this platform does not take snapshots yet.
  • retention_daysintegerrequired
    How long a daily snapshot is kept.
  • weekly_keptintegerrequired
    How many weekly snapshots are kept besides the daily ones; 0 for none.
  • next_snapshot_atdatetime or nullrequired
    When the schedule starts its next snapshot. Snapshots start within the hour after.
  • disk_createdbooleanrequired
    false until the service has started once and its disk exists.
  • snapshotsarray of DiskSnapshotrequired
  • idstringrequired
    The snapshot's id, such as snap-0a1b2c3d4e5f67890. Use it to restore.
  • created_atdatetimerequired
    When the snapshot started. It shows the disk as it was then.
  • size_gbintegerrequired
    The size of the disk, in GB.
  • statusstringrequired
    Only a completed snapshot can be restored.

    One of completed, in_progress, failed.

  • progress_percentintegerrequired
    How far an in-progress snapshot is.
  • typestringrequired
    daily and weekly snapshots are taken by the schedule and deleted when they expire; manual ones are never deleted by it.

    One of daily, weekly, manual.

  • expires_atdatetime or nullrequired
    When the schedule deletes it. null for a manual snapshot.
  • restored_disksarray of RestoredDiskrequired
    Disks restored from this service's snapshots.
  • iduuidrequired
  • namestringrequired
    The name of the disk in the workspace.
  • statusstringrequired
    ready once the disk can be mounted.

    One of starting, creating, ready, failed, deleting.

  • messagestringrequired
    Why a restore failed. Empty otherwise.
  • size_gbintegerrequired
  • snapshot_idstringrequired
    The snapshot it was made from.
  • snapshot_created_atdatetimerequired
    The moment the disk shows.
  • created_atdatetimerequired
    When the restore was asked for.
  • serviceobject or nullrequired
    The service that uses the disk; null while it is free.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The service has no disk.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 503unavailable

    The snapshots could not be read right now.

GEThttps://onkilby.com/api/v1/services/{id}/disk/snapshots
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "enabled": true,
  "retention_days": 7,
  "weekly_kept": 0,
  "next_snapshot_at": "2026-11-14T03:00:00Z",
  "disk_created": true,
  "snapshots": [
    {
      "id": "snap-0a1b2c3d4e5f67890",
      "created_at": "2026-11-13T03:12:00Z",
      "size_gb": 10,
      "status": "completed",
      "progress_percent": 100,
      "type": "daily",
      "expires_at": "2026-11-20T03:12:00Z"
    }
  ],
  "restored_disks": []
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/disk/snapshots/{snapshot_id}/restore #

Restore a disk snapshot

workspace Admin key

Makes a new disk from a completed snapshot. The service keeps running on its own disk, which is not changed. The new disk is in the same zone, the same size and encrypted; it appears in restored_disks of List disk snapshots and is ready within a minute or two.

A restored disk is mounted on a new service, which you start from it in the dashboard (the disk's row has a Start a service button). Until then it counts toward the workspace's disk limit.

Needs a key with the Admin role or higher. Calling it again for a snapshot that is being restored returns the restore in progress instead of starting another.

Path parameters

  • iduuidrequired
    The service's id.
  • snapshot_idstringrequired
    A snapshot's id, from List snapshots.

Request body The body is optional.

  • namestring
    The new disk's name. Defaults to the service's name, restored, and the snapshot's date.

    3 to 50 characters; not ending in -disk or starting with db-.

Response

202
The restore, in progress.
  • restored_diskRestoredDiskrequired
  • iduuidrequired
  • namestringrequired
    The name of the disk in the workspace.
  • statusstringrequired
    ready once the disk can be mounted.

    One of starting, creating, ready, failed, deleting.

  • messagestringrequired
    Why a restore failed. Empty otherwise.
  • size_gbintegerrequired
  • snapshot_idstringrequired
    The snapshot it was made from.
  • snapshot_created_atdatetimerequired
    The moment the disk shows.
  • created_atdatetimerequired
    When the restore was asked for.
  • serviceobject or nullrequired
    The service that uses the disk; null while it is free.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No snapshot with that id belongs to this service's disk.

  • 409conflict

    Snapshots are not switched on, the service has no disk, the snapshot is not finished, or the name is taken.

  • 422invalid_request

    The name is not valid, or the new disk would exceed the workspace's disk limit.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 503unavailable

    The snapshots could not be read right now.

POSThttps://onkilby.com/api/v1/services/{id}/disk/snapshots/{snapshot_id}/restore
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots/snap-0a1b2c3d4e5f67890/restore" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-api-before-migration"}'
{
  "restored_disk": {
    "id": "6a8d3f20-91c4-4e1b-8b57-0d2e4c9a1f33",
    "name": "my-api-restored-20261113",
    "status": "creating",
    "message": "",
    "size_gb": 10,
    "snapshot_id": "snap-0a1b2c3d4e5f67890",
    "snapshot_created_at": "2026-11-13T03:12:00Z",
    "created_at": "2026-11-13T14:05:00Z",
    "service": null
  }
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/images/check #

Check a container image

deploy Developer key or higher

Asks the image's registry whether the image exists, before you create or change a service with it. It is the check the dashboard runs while you type an image, and the one Create a service and Update a service run when they save: an image that is certainly not usable is refused with the same message.

Kilby asks for the manifest of the tag or digest on Docker Hub, GHCR, Quay, GitLab, Amazon ECR Public, Google's registries or any registry with the standard API, and reads which platforms the image was built for. Kilby's nodes run linux/amd64, so an image without that build is reported as no_amd64.

state says what was found. ok means the image is there. not_found, bad_credentials and no_amd64 are definite: a deploy of this image would fail, and creating a service with it is refused. needs_credentials and unknown are information: Kilby could not tell (the registry asks for a login, did not answer, or is limiting requests such as Docker Hub's for anonymous clients), and nothing is refused, because the deploy reports what happens.

A private image cannot be told apart from one that does not exist when no credentials are given: both answer not_found. Send registry_credential_id to check with saved credentials of this workspace; they are used for this request only and are never returned. Kilby only contacts registries on the public internet. Answers are reused for 60 seconds. The check is rate limited per person and per workspace.

Request body

  • imagestringrequired
    The image reference, as in image of a service.

    a registry reference, tag or digest.

  • registry_credential_iduuid or null
    Saved registry credentials of this workspace to check a private image with, from POST /registry-credentials. They must be for the registry the image comes from. null, or leaving it out, checks as an anonymous client.

Response

200
What the registry said. blocking is true when saving a service with this image would be refused.
  • statestringrequired
    What was found.

    One of ok, not_found, needs_credentials, bad_credentials, no_amd64, unknown.

  • messagestringrequired
    One or two sentences for people, with what to do. It may change; branch on state.
  • blockingbooleanrequired
    true for not_found, bad_credentials and no_amd64.
  • imagestringrequired
    The reference with the defaults spelled out: Docker Hub shorthand, library/, and latest when you gave no tag.
  • registrystringrequired
    The registry the image comes from.
  • digeststring
    The manifest the tag points to now. Only present when the image was found.
  • size_bytesinteger
    The compressed size of the layers for linux/amd64. Only present when it could be read.
  • platformsarray of stringrequired
    The platforms the image was built for, such as linux/amd64 and linux/arm64. Empty when the image was not found or they could not be read.
  • portsarray of integerrequired
    The TCP ports the image declares (the EXPOSE lines of its Dockerfile), sorted. Empty when it declares none, or when its config could not be read.
  • portinteger
    The port Kilby fills into the form: only present when the image declares exactly one. A port below 1024 is fine for an image.
  • port_notestring
    One sentence about what was found out about the port: one declared, several, or none. Absent when the config could not be read. It may change.
  • checked_atdatetimerequired
    When the registry was asked (an answer from the 60 second cache keeps its time).

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The registry credentials do not exist in this workspace.

  • 422invalid_request

    The image is not a valid reference, or the registry is not allowed for services.

  • 429rate_limited

    More than 40 checks a minute for one person, or 120 for the workspace.

POSThttps://onkilby.com/api/v1/images/check
curl -X POST "https://onkilby.com/api/v1/images/check" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "ghcr.io/acme/api:1.4"}'
{
  "state": "ok",
  "message": "Found · sha256:1a2b3c4d5e6f · Compatible with Kilby (linux/amd64) · 52 MB",
  "blocking": false,
  "image": "ghcr.io/acme/api:1.4",
  "registry": "ghcr.io",
  "digest": "sha256:1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809",
  "size_bytes": 52428800,
  "platforms": ["linux/amd64", "linux/arm64"],
  "ports": [8000],
  "port": 8000,
  "port_note": "The image declares port 8000, so Kilby filled it in.",
  "checked_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.

Projects

A project groups environments, such as Production and Staging, and every service, cron job, database and Key Value instance is in exactly one environment. This is organization, not isolation: all of them share the workspace's limits, members, roles, network and namespace, an API key sees every project, and moving a resource to another environment restarts nothing. A resource that was never placed is in the Default project, in Production, which Kilby creates the first time something needs it. Name an environment by its id, as project/environment (case does not matter), or by its name when only one environment has it.

GET/api/v1/projects #

List projects

view Any key

The workspace's projects with their environments and how many resources each holds. The first call in a workspace creates the Default project, in Production, if nothing needed it before: it is where everything that was never placed is. Projects organize the workspace and isolate nothing: a key sees all of them.

Response

200
The projects, the Default one first.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/projects
curl "https://onkilby.com/api/v1/projects" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "projects": [
    {
      "id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12",
      "name": "Checkout app",
      "default": false,
      "environments": [
        {
          "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
          "name": "Production",
          "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Checkout app"},
          "default": false,
          "position": 0,
          "counts": {"services": 2, "cron_jobs": 1, "databases": 1, "key_values": 0},
          "created_at": "2026-11-12T22:40:11Z",
          "updated_at": "2026-11-12T22:40:11Z"
        },
        {
          "id": "d41f8b60-2e7a-4c93-a5b8-0f6e3d9c2a71",
          "name": "Staging",
          "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Checkout app"},
          "default": false,
          "position": 1,
          "counts": {"services": 1, "cron_jobs": 0, "databases": 0, "key_values": 0},
          "created_at": "2026-11-13T09:12:30Z",
          "updated_at": "2026-11-13T09:12:30Z"
        }
      ],
      "counts": {"services": 3, "cron_jobs": 1, "databases": 1, "key_values": 0},
      "created_at": "2026-11-12T22:40:11Z",
      "updated_at": "2026-11-12T22:40:11Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/projects #

Create a project

deploy Developer key or higher

Creates a project with its first environment, Production. Add the others with Create an environment. A workspace can have up to 20 projects, the Default one included.

Request body

  • namestringrequired
    Unique in the workspace, without regard to capitals.

    1 to 40 characters, no slash.

Response

201
The project, with its Production environment.

Returns a Project object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 409conflict

    The workspace already has a project with that name.

  • 422invalid_request

    The name is not valid, or the workspace has reached its limit of projects.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/projects
curl -X POST "https://onkilby.com/api/v1/projects" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Checkout app"}'
{
  "id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12",
  "name": "Checkout app",
  "default": false,
  "environments": [
    {
      "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
      "name": "Production",
      "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Checkout app"},
      "default": false,
      "position": 0,
      "counts": {"services": 0, "cron_jobs": 0, "databases": 0, "key_values": 0},
      "created_at": "2026-11-12T22:40:11Z",
      "updated_at": "2026-11-12T22:40:11Z"
    }
  ],
  "counts": {"services": 0, "cron_jobs": 0, "databases": 0, "key_values": 0},
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-12T22:40:11Z"
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/projects/{id} #

Get a project

view Any key

One project with its environments and what each holds, by name and id.

Path parameters

  • iduuidrequired
    The project's id.

Response

200
The project.

Returns a Project object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such project in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/projects/{id}
curl "https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12",
  "name": "Checkout app",
  "default": false,
  "environments": [
    {
      "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
      "name": "Production",
      "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Checkout app"},
      "default": false,
      "position": 0,
      "counts": {"services": 2, "cron_jobs": 1, "databases": 1, "key_values": 0},
      "resources": [
        {
          "type": "web",
          "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
          "name": "my-api"
        },
        {
          "type": "database",
          "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
          "name": "main"
        }
      ],
      "created_at": "2026-11-12T22:40:11Z",
      "updated_at": "2026-11-12T22:40:11Z"
    }
  ],
  "counts": {"services": 2, "cron_jobs": 1, "databases": 1, "key_values": 0},
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-12T22:40:11Z"
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/projects/{id} #

Rename a project

deploy Developer key or higher

Renames the project, the Default one included. Nothing that runs is touched.

Path parameters

  • iduuidrequired
    The project's id.

Request body

  • namestringrequired
    The new name.

    1 to 40 characters, no slash.

Response

200
The project.

Returns a Project object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such project in this workspace.

  • 409conflict

    Another project has that name.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/projects/{id}
curl -X PATCH "https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Checkout"}'
{
  "id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12",
  "name": "Checkout app",
  "default": false,
  "environments": [
    {
      "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
      "name": "Production",
      "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Checkout app"},
      "default": false,
      "position": 0,
      "counts": {"services": 2, "cron_jobs": 1, "databases": 1, "key_values": 0},
      "resources": [
        {
          "type": "web",
          "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
          "name": "my-api"
        },
        {
          "type": "database",
          "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
          "name": "main"
        }
      ],
      "created_at": "2026-11-12T22:40:11Z",
      "updated_at": "2026-11-12T22:40:11Z"
    }
  ],
  "counts": {"services": 2, "cron_jobs": 1, "databases": 1, "key_values": 0},
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-12T22:40:11Z"
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/projects/{id} #

Delete a project

workspace Admin key

Deletes a project and its environments. While it holds resources the call is refused with 409 and the message names them: send move_to to move them to another environment first, in the same call. Moving changes where they are listed and restarts nothing. The Default project cannot be deleted. Needs an admin key.

Path parameters

  • iduuidrequired
    The project's id.

Query parameters

  • move_tostring
    Where the resources go, when there are any: an environment id, project/environment or a name only one environment has. It cannot be in the project being deleted.

Response

200
What was deleted and how many resources moved.
  • deletedstringrequired
    The project's name.
  • movedintegerrequired
    How many resources were moved.
  • moved_tostring
    Where they went, as project / environment.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such project in this workspace.

  • 409conflict

    It still holds resources and move_to was not sent, or it is the Default project.

  • 422invalid_request

    move_to names no environment, or one inside the project.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/projects/{id}
curl -X DELETE "https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12?move_to=Default%2FProduction" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "deleted": "Checkout app",
  "moved": 4,
  "moved_to": "Default / Production"
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/projects/{id}/environments #

List the environments of a project

view Any key

The project's environments in order, with how many resources each holds.

Path parameters

  • iduuidrequired
    The project's id.

Response

200
The environments.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such project in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/projects/{id}/environments
curl "https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "environments": [
    {
      "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
      "name": "Production",
      "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Checkout app"},
      "default": false,
      "position": 0,
      "counts": {"services": 2, "cron_jobs": 1, "databases": 1, "key_values": 0},
      "created_at": "2026-11-12T22:40:11Z",
      "updated_at": "2026-11-12T22:40:11Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/projects/{id}/environments #

Create an environment

deploy Developer key or higher

Adds an environment at the end of the project, for example Staging or Preview. A project can have up to 10.

Path parameters

  • iduuidrequired
    The project's id.

Request body

  • namestringrequired
    Unique in the project, without regard to capitals.

    1 to 40 characters, no slash.

Response

201
The environment.

Returns a ProjectEnvironment object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such project in this workspace.

  • 409conflict

    The project already has an environment with that name.

  • 422invalid_request

    The name is not valid, or the project has reached its limit of environments.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/projects/{id}/environments
curl -X POST "https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging"}'
{
  "id": "d41f8b60-2e7a-4c93-a5b8-0f6e3d9c2a71",
  "name": "Staging",
  "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Checkout app"},
  "default": false,
  "position": 1,
  "counts": {"services": 0, "cron_jobs": 0, "databases": 0, "key_values": 0},
  "created_at": "2026-11-13T09:12:30Z",
  "updated_at": "2026-11-13T09:12:30Z"
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/projects/{id}/environments/{env} #

Get an environment

view Any key

One environment with the resources it holds.

Path parameters

  • iduuidrequired
    The project's id.
  • envuuidrequired
    The environment's id.

Response

200
The environment.

Returns a ProjectEnvironment object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such project or environment in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/projects/{id}/environments/{env}
curl "https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
  "name": "Production",
  "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Checkout app"},
  "default": false,
  "position": 0,
  "counts": {"services": 2, "cron_jobs": 0, "databases": 1, "key_values": 0},
  "resources": [
    {
      "type": "web",
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "my-api"
    },
    {
      "type": "worker",
      "id": "9b0e4c71-3d2a-4f58-8a61-c7d1e2f30b94",
      "name": "queue-worker"
    },
    {
      "type": "database",
      "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
      "name": "main"
    }
  ],
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-12T22:40:11Z"
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/projects/{id}/environments/{env} #

Rename an environment

deploy Developer key or higher

Renames the environment, the default one included. Nothing that runs is touched.

Path parameters

  • iduuidrequired
    The project's id.
  • envuuidrequired
    The environment's id.

Request body

  • namestringrequired
    The new name.

    1 to 40 characters, no slash.

Response

200
The environment.

Returns a ProjectEnvironment object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such project or environment in this workspace.

  • 409conflict

    Another environment of the project has that name.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/projects/{id}/environments/{env}
curl -X PATCH "https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Prod"}'
{
  "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
  "name": "Production",
  "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Checkout app"},
  "default": false,
  "position": 0,
  "counts": {"services": 2, "cron_jobs": 0, "databases": 1, "key_values": 0},
  "resources": [
    {
      "type": "web",
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "my-api"
    },
    {
      "type": "worker",
      "id": "9b0e4c71-3d2a-4f58-8a61-c7d1e2f30b94",
      "name": "queue-worker"
    },
    {
      "type": "database",
      "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
      "name": "main"
    }
  ],
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-12T22:40:11Z"
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/projects/{id}/environments/{env} #

Delete an environment

workspace Admin key

Deletes an environment. While it holds resources the call is refused with 409 and the message names them: send move_to to move them first, in the same call. Moving restarts nothing. The default environment, and the last environment of a project, cannot be deleted. Needs an admin key.

Path parameters

  • iduuidrequired
    The project's id.
  • envuuidrequired
    The environment's id.

Query parameters

  • move_tostring
    Where the resources go, when there are any: an environment id, project/environment or a name only one environment has. It cannot be in the project being deleted.

Response

200
What was deleted and how many resources moved.
  • deletedstringrequired
    project / environment.
  • movedintegerrequired
    How many resources were moved.
  • moved_tostring
    Where they went.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such project or environment in this workspace.

  • 409conflict

    It still holds resources and move_to was not sent, it is the default environment, or it is the last one of its project.

  • 422invalid_request

    move_to names no environment, or the one being deleted.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/projects/{id}/environments/{env}
curl -X DELETE "https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053?move_to=Default%2FProduction" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "deleted": "Checkout app / Staging",
  "moved": 1,
  "moved_to": "Checkout app / Production"
}
Runs in your browser against your workspace with a key you paste.

Deploys and builds

Every change to a service is a deploy. A service built from a Git repository also has builds: Kilby clones the repository, builds an image outside your cluster, and deploys it. Deploys and builds are both listed newest first.

GET/api/v1/services/{id}/deploys #

List deploys

view Any key

The last 50 deploys of the service, newest first. Each has a title for a list: the first line of the commit for a deploy from Git, the image tag, what a settings change changed, "Manual redeploy by ...", "Rollback to ...". A deploy is queued, then deploying, then live or failed; a deploy that a newer one replaced before it finished is superseded.

When the service has a pre-deploy command, each deploy carries its run in pre_deploy: the command, its status, its exit code and the last lines it printed. A deploy whose command failed or timed out is failed with message saying so, and the version that was running is unchanged.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The deploys.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/deploys
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "deploys": [
    {
      "id": "5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d",
      "image": "ghcr.io/acme/api:1.4",
      "trigger": "update",
      "status": "live",
      "message": "",
      "created_at": "2026-11-13T14:00:00Z",
      "finished_at": "2026-11-13T14:01:12Z",
      "title": "Instance type: Starter to Standard",
      "pre_deploy": {
        "command": "python manage.py migrate",
        "status": "succeeded",
        "message": "",
        "started_at": "2026-11-13T14:00:03Z",
        "finished_at": "2026-11-13T14:00:21Z",
        "exit_code": 0,
        "output": "Applying orders.0007_add_index... OK"
      }
    },
    {
      "id": "8a0f6c2d-1b4e-4d97-a3c5-6e7f8091a2b3",
      "image": "ghcr.io/acme/api:1.3",
      "trigger": "create",
      "status": "superseded",
      "message": "",
      "created_at": "2026-11-12T22:40:11Z",
      "finished_at": "2026-11-12T22:41:30Z",
      "title": "1.3",
      "pre_deploy": null
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/deploys #

Redeploy a service

deploy Developer key or higher

Deploys the service again with its current settings and image. Use it to pick up a new image behind the same tag, or to restart instances. The answer is the service, deploying; follow the new deploy in List deploys.

If the service has a pre-deploy command it runs again first. Send skip_pre_deploy: true to deploy this one time without it; the choice is recorded in the audit trail.

To deploy a different image or settings, use Change a service. To deploy from CI without an API key, see Deploy hooks.

Path parameters

  • iduuidrequired
    The service's id.

Request body

  • skip_pre_deployboolean
    Deploy without running the pre-deploy command, this time only.

    Default false.

Response

202
The service, deploying.

Returns a Service object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The service is suspended or being deleted, or a service built from Git has no build yet.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/services/{id}/deploys
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"skip_pre_deploy": true}'
{
  "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "name": "my-api",
  "type": "web",
  "image": "ghcr.io/acme/api:1.4",
  "port": 8080,
  "plan": "starter",
  "status": "deploying",
  "status_message": "",
  "suspended": false,
  "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai",
  "internal_address": "my-api:8080",
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "registry_credential_id": null,
  "health_check_path": "/healthz",
  "instances": 2,
  "autoscaling": {"min": 2, "max": 4, "target_cpu_percent": 70},
  "disk": null,
  "instances_running": 1,
  "instances_desired": 2,
  "pre_deploy_command": "",
  "pre_deploy_timeout_seconds": 600,
  "source": null,
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "auto_concurrency": true,
  "render_compat": false,
  "stop_first": false,
  "read_only_root": false,
  "maintenance": false,
  "maintenance_message": "",
  "primary_domain": "my-api-x7k2.apps.kilby.neuramorphic.ai",
  "primary_domain_choice": null
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/deploys/{deploy}/rollback-preview #

Preview a rollback

deploy Developer key or higher

What rolling back to this deploy would change, without changing anything: every setting with its current and its restored value, and the environment variables that would be added, removed or changed. Values of variables are never in the answer, only their names and the kind of change.

environment.restore_default says whether the variables are restored when restore_env is left out of the rollback: it is true when the deploy recorded its variables and they differ from the ones saved now. generation is the version of the service the preview was made from. notes are the sentences the dashboard shows next to the preview, such as what a service with a disk costs in downtime. The preview is for deploys that went live; for any other can_roll_back is false and blocked_reason says why.

Path parameters

  • iduuidrequired
    The service's id.
  • deployuuidrequired
    The deploy to go back to, from List deploys.

Response

200
What would change.

Returns a RollbackPreview object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The service has no such deploy.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/deploys/{deploy}/rollback-preview
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d/rollback-preview" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "deploy": {
    "id": "5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d",
    "image": "ghcr.io/acme/api:1.4",
    "trigger": "update",
    "status": "live",
    "created_at": "2026-11-12T22:40:11Z",
    "finished_at": "2026-11-12T22:41:30Z"
  },
  "can_roll_back": true,
  "generation": 7,
  "settings": [
    {
      "field": "image",
      "label": "Image",
      "current": "ghcr.io/acme/api:1.5",
      "after": "ghcr.io/acme/api:1.4",
      "changes": true,
      "kept": false
    },
    {
      "field": "command",
      "label": "Start command",
      "current": "The image's default",
      "after": "The image's default",
      "changes": false,
      "kept": false
    },
    {
      "field": "port",
      "label": "Port",
      "current": "8080",
      "after": "8080",
      "changes": false,
      "kept": false
    },
    {
      "field": "plan",
      "label": "Instance type",
      "current": "Starter — 0.5 CPU, 512 MB",
      "after": "Starter — 0.5 CPU, 512 MB",
      "changes": false,
      "kept": false
    },
    {
      "field": "health",
      "label": "Health check path",
      "current": "/healthz",
      "after": "/healthz",
      "changes": false,
      "kept": false
    },
    {
      "field": "instances",
      "label": "Instances",
      "current": "1",
      "after": "1",
      "changes": false,
      "kept": true,
      "note": "A rollback keeps the number of instances."
    }
  ],
  "environment": {
    "recorded": true,
    "readable": true,
    "restore_default": true,
    "added": ["LEGACY_MODE"],
    "removed": ["NEW_FEATURE_FLAG"],
    "changed": ["APP_VERSION"],
    "unchanged": 4,
    "if_restored": "The service's saved variables become the ones this deploy ran with. They stay that way: any later deploy, whether a redeploy, a call to the deploy hook or a settings change, uses them. Nothing goes back to the newer values unless you save them again on the Environment tab.",
    "if_kept": "The variables saved now stay as they are, and the earlier version runs with them."
  },
  "strategy": "rolling_update",
  "notes": [
    "Kilby deploys this image as a new deploy and restarts the service on it, one instance at a time. An instance of the earlier version has to pass its health check before an instance of the current one is stopped.",
    "The deploy hook keeps working. A deploy it starts later brings the image it names, and runs it with the variables saved at that time: the ones this rollback leaves on the service.",
    "The newer deploys stay in the deploy history.",
    "If the rollback would take the workspace over one of its limits, or the image cannot be used, nothing changes and Kilby says why."
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/rollback #

Roll back to an earlier deploy

deploy Developer key or higher

Deploys what an earlier successful deploy ran: its image, start command, port, schedule, instance type and health check path, with trigger rollback. The number of instances and the disk are kept. With restore_env the service's environment variables become the ones that deploy ran with, in the same new deploy: the restored variables are the service's saved variables from then on, so a later redeploy, a call to a deploy hook or a change of settings uses them too, and nothing goes back to the newer values.

restore_env defaults to true when the deploy recorded its variables (see environment in Preview a rollback) and to false when it did not. If the recorded variables cannot be read, nothing changes at all and the answer is a 422. Only the most recent deploys of a service keep their variables, so an old deploy may not have recorded them.

Take the id from List deploys; it must be a deploy that reached live. Look at what would change first with Preview a rollback.

Path parameters

  • iduuidrequired
    The service's id.

Request body

  • deploy_iduuidrequired
    The deploy to restore.
  • restore_envboolean
    Restore the environment variables of that deploy. false keeps the variables saved now.

    Default true if the deploy recorded its variables, else false.

Response

202
The new deploy, which restores the earlier one.

Returns a DeployRecord object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The service has no such deploy.

  • 409conflict

    The deploy never went live, or the service is suspended.

  • 422invalid_request

    deploy_id is not an id, restore_env is true but the deploy did not record its variables or they cannot be read, or the rollback would exceed a limit of the workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/services/{id}/rollback
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/rollback" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deploy_id": "5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d"}'
{
  "id": "8a0f6c2d-1b4e-4d97-a3c5-6e7f8091a2b3",
  "image": "ghcr.io/acme/api:1.4",
  "trigger": "rollback",
  "status": "queued",
  "message": "",
  "rollback_of": "5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d",
  "created_at": "2026-11-13T14:05:00Z",
  "finished_at": null,
  "title": "Rollback to 1.4",
  "environment_restored": true
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/builds #

List builds

view Any key

The builds of a service built from Git, newest first. Page through them with before: send the next_before of the previous answer. next_before is null on the last page.

Path parameters

  • iduuidrequired
    The service's id.

Query parameters

  • limitinteger
    How many builds to return.

    Default 20.

    1 to 100.

  • beforeinteger
    Only builds with a number lower than this. Use the next_before of the previous page.

Response

200
A page of builds.
  • buildsarray of Buildrequired
  • next_beforeinteger or nullrequired
    The value to send as before for the next page. null on the last page.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    The service does not run an image built from Git.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/builds
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds?limit=20" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "builds": [
    {
      "id": "5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24",
      "number": 4,
      "trigger": "push",
      "status": "succeeded",
      "stage": "live",
      "commit": {
        "sha": "9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0",
        "message": "Add the /v1/chat route",
        "author": "Ada Lovelace",
        "branch": "main"
      },
      "stages": [
        {
          "name": "clone",
          "status": "succeeded",
          "started_at": "2026-11-13T14:00:02Z",
          "finished_at": "2026-11-13T14:00:05Z"
        },
        {
          "name": "detect",
          "status": "succeeded",
          "started_at": "2026-11-13T14:00:05Z",
          "finished_at": "2026-11-13T14:00:06Z"
        },
        {
          "name": "build",
          "status": "succeeded",
          "started_at": "2026-11-13T14:00:06Z",
          "finished_at": "2026-11-13T14:02:31Z"
        },
        {
          "name": "push",
          "status": "succeeded",
          "started_at": "2026-11-13T14:02:31Z",
          "finished_at": "2026-11-13T14:02:48Z",
          "note": "84 MB"
        },
        {
          "name": "release",
          "status": "succeeded",
          "started_at": "2026-11-13T14:02:48Z",
          "finished_at": "2026-11-13T14:02:49Z"
        },
        {
          "name": "health",
          "status": "succeeded",
          "started_at": "2026-11-13T14:02:49Z",
          "finished_at": "2026-11-13T14:03:11Z"
        },
        {
          "name": "live",
          "status": "succeeded",
          "started_at": "2026-11-13T14:03:11Z",
          "finished_at": "2026-11-13T14:03:11Z"
        }
      ],
      "diagnosis": null,
      "image_digest": "sha256:4b1f9c0e7d2a8356bc41e9d0f7a6c3258e1d4b97a0c6f3e5d28b71a94c60e3fd",
      "created_by": "Ada Lovelace",
      "created_at": "2026-11-13T14:00:01Z",
      "started_at": "2026-11-13T14:00:02Z",
      "finished_at": "2026-11-13T14:03:11Z"
    }
  ],
  "next_before": null
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/builds #

Start a build

deploy Developer key or higher

Builds the latest commit of the service's branch, or the commit you name. When it succeeds Kilby deploys the image, with trigger git. A workspace can start 30 builds by hand per hour; builds started by pushes are not counted.

Path parameters

  • iduuidrequired
    The service's id.

Request body The body is optional.

  • shastring
    A commit to build, as a full or abbreviated commit id. Leave it out for the latest commit of the branch.

Response

202
The queued build.

Returns a Build object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The service is suspended, or a build is already running for it.

  • 422invalid_request

    The service is not built from Git, or sha is not a commit id.

  • 429rate_limited

    More than 30 builds were started by hand in the last hour.

  • 502github_unavailable

    Kilby could not read the latest commit from GitHub.

  • 503unavailable

    Deploying from Git is not turned on.

POSThttps://onkilby.com/api/v1/services/{id}/builds
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sha": "9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0"}'
{
  "id": "5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24",
  "number": 4,
  "trigger": "manual",
  "status": "queued",
  "stage": "clone",
  "commit": {
    "sha": "9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0",
    "message": "Add the /v1/chat route",
    "author": "Ada Lovelace",
    "branch": "main"
  },
  "stages": [
    {
      "name": "clone",
      "status": "succeeded",
      "started_at": "2026-11-13T14:00:02Z",
      "finished_at": "2026-11-13T14:00:05Z"
    },
    {
      "name": "detect",
      "status": "succeeded",
      "started_at": "2026-11-13T14:00:05Z",
      "finished_at": "2026-11-13T14:00:06Z"
    },
    {
      "name": "build",
      "status": "succeeded",
      "started_at": "2026-11-13T14:00:06Z",
      "finished_at": "2026-11-13T14:02:31Z"
    },
    {
      "name": "push",
      "status": "succeeded",
      "started_at": "2026-11-13T14:02:31Z",
      "finished_at": "2026-11-13T14:02:48Z",
      "note": "84 MB"
    },
    {
      "name": "release",
      "status": "succeeded",
      "started_at": "2026-11-13T14:02:48Z",
      "finished_at": "2026-11-13T14:02:49Z"
    },
    {
      "name": "health",
      "status": "succeeded",
      "started_at": "2026-11-13T14:02:49Z",
      "finished_at": "2026-11-13T14:03:11Z"
    },
    {
      "name": "live",
      "status": "succeeded",
      "started_at": "2026-11-13T14:03:11Z",
      "finished_at": "2026-11-13T14:03:11Z"
    }
  ],
  "diagnosis": null,
  "image_digest": "sha256:4b1f9c0e7d2a8356bc41e9d0f7a6c3258e1d4b97a0c6f3e5d28b71a94c60e3fd",
  "created_by": "Ada Lovelace",
  "created_at": "2026-11-13T14:00:01Z",
  "started_at": "2026-11-13T14:00:02Z",
  "finished_at": "2026-11-13T14:03:11Z"
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/builds/{build} #

Get a build

view Any key

One build with its stages. A build goes through clone, detect, build, push, release, health and live; each stage has its own status and times. A failed build has an error, and often a diagnosis that says what to change and offers fixes.

Path parameters

  • iduuidrequired
    The service's id.
  • buildstringrequired
    A build's id, or its number within the service (1, 2, 3).

Response

200
The build.

Returns a Build object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/builds/{build}
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24",
  "number": 5,
  "trigger": "push",
  "status": "failed",
  "stage": "build",
  "commit": {
    "sha": "e4a7c1d93b0f4286a5d1c7e90b3f8a24d6c5b1e7",
    "message": "Update the Dockerfile",
    "author": "Ada Lovelace",
    "branch": "main"
  },
  "stages": [
    {
      "name": "clone",
      "status": "succeeded",
      "started_at": "2026-11-13T15:10:02Z",
      "finished_at": "2026-11-13T15:10:05Z"
    },
    {
      "name": "detect",
      "status": "succeeded",
      "started_at": "2026-11-13T15:10:05Z",
      "finished_at": "2026-11-13T15:10:06Z"
    },
    {
      "name": "build",
      "status": "failed",
      "started_at": "2026-11-13T15:10:06Z",
      "finished_at": "2026-11-13T15:10:19Z"
    }
  ],
  "error": "The build failed.",
  "diagnosis": {
    "code": "no_dockerfile",
    "title": "There is no Dockerfile at Dockerfile.prod.",
    "detail": "Kilby looked for Dockerfile.prod in the root of the repository and did not find it.",
    "fixes": [
      {
        "label": "Use the Dockerfile at docker/Dockerfile",
        "field": "dockerfile_path",
        "value": "docker/Dockerfile"
      }
    ]
  },
  "created_at": "2026-11-13T15:10:01Z",
  "started_at": "2026-11-13T15:10:02Z",
  "finished_at": "2026-11-13T15:10:19Z"
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/builds/{build}/logs #

Read a build's log

view Any key

The log lines after a sequence number, as JSON. To follow a running build, call it again with after set to the next_after of the previous answer, until done is true. done becomes true once the build has ended and no line is left.

Path parameters

  • iduuidrequired
    The service's id.
  • buildstringrequired
    A build's id, or its number within the service (1, 2, 3).

Query parameters

  • afterinteger
    Only lines with a higher seq. 0 starts from the beginning.

    Default 0.

  • limitinteger
    The most lines to return.

    Default 500.

    1 to 2000.

Response

200
A page of log lines.
  • next_afterintegerrequired
    Send this as after to continue.
  • donebooleanrequired
    true when the build ended and there is nothing more to read.
  • statusstringrequired
    The build's status.
  • stagestringrequired
    The build's stage.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/builds/{build}/logs
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/logs?after=0" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "lines": [
    {
      "seq": 1,
      "at": "2026-11-13T14:00:02Z",
      "stage": "clone",
      "level": "info",
      "text": "Cloning acme/express-api at 9c1d3fe"
    },
    {
      "seq": 2,
      "at": "2026-11-13T14:00:05Z",
      "stage": "detect",
      "level": "info",
      "text": "Found a Node.js project (Express)"
    }
  ],
  "next_after": 2,
  "done": false,
  "status": "running",
  "stage": "detect"
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/builds/{build}/cancel #

Cancel a build

deploy Developer key or higher

Stops a queued or running build. A build whose image is already being released cannot be canceled: roll back instead.

Path parameters

  • iduuidrequired
    The service's id.
  • buildstringrequired
    A build's id, or its number within the service (1, 2, 3).

Response

202
The build, being canceled.

Returns a Build object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The build has finished, or its image is already being deployed.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/services/{id}/builds/{build}/cancel
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/cancel" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24",
  "number": 4,
  "trigger": "push",
  "status": "running",
  "stage": "build",
  "commit": {
    "sha": "9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0",
    "message": "Add the /v1/chat route",
    "author": "Ada Lovelace",
    "branch": "main"
  },
  "stages": [
    {
      "name": "clone",
      "status": "succeeded",
      "started_at": "2026-11-13T14:00:02Z",
      "finished_at": "2026-11-13T14:00:05Z"
    },
    {
      "name": "detect",
      "status": "succeeded",
      "started_at": "2026-11-13T14:00:05Z",
      "finished_at": "2026-11-13T14:00:06Z"
    },
    {
      "name": "build",
      "status": "succeeded",
      "started_at": "2026-11-13T14:00:06Z",
      "finished_at": "2026-11-13T14:02:31Z"
    },
    {
      "name": "push",
      "status": "succeeded",
      "started_at": "2026-11-13T14:02:31Z",
      "finished_at": "2026-11-13T14:02:48Z",
      "note": "84 MB"
    },
    {
      "name": "release",
      "status": "succeeded",
      "started_at": "2026-11-13T14:02:48Z",
      "finished_at": "2026-11-13T14:02:49Z"
    },
    {
      "name": "health",
      "status": "succeeded",
      "started_at": "2026-11-13T14:02:49Z",
      "finished_at": "2026-11-13T14:03:11Z"
    },
    {
      "name": "live",
      "status": "succeeded",
      "started_at": "2026-11-13T14:03:11Z",
      "finished_at": "2026-11-13T14:03:11Z"
    }
  ],
  "diagnosis": null,
  "image_digest": "sha256:4b1f9c0e7d2a8356bc41e9d0f7a6c3258e1d4b97a0c6f3e5d28b71a94c60e3fd",
  "created_by": "Ada Lovelace",
  "created_at": "2026-11-13T14:00:01Z",
  "started_at": "2026-11-13T14:00:02Z",
  "finished_at": "2026-11-13T14:03:11Z"
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/builds/{build}/retry #

Retry a build

deploy Developer key or higher

Builds the same commit again, as a new build with trigger rebuild. Use it after you fixed a setting, or when the failure was not about the code.

Path parameters

  • iduuidrequired
    The service's id.
  • buildstringrequired
    A build's id, or its number within the service (1, 2, 3).

Response

202
The new build.

Returns a Build object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The build is still in progress, or the service is suspended.

  • 429rate_limited

    More than 30 builds were started by hand in the last hour.

POSThttps://onkilby.com/api/v1/services/{id}/builds/{build}/retry
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/retry" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24",
  "number": 4,
  "trigger": "rebuild",
  "status": "queued",
  "stage": "clone",
  "commit": {
    "sha": "9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0",
    "message": "Add the /v1/chat route",
    "author": "Ada Lovelace",
    "branch": "main"
  },
  "stages": [
    {
      "name": "clone",
      "status": "succeeded",
      "started_at": "2026-11-13T14:00:02Z",
      "finished_at": "2026-11-13T14:00:05Z"
    },
    {
      "name": "detect",
      "status": "succeeded",
      "started_at": "2026-11-13T14:00:05Z",
      "finished_at": "2026-11-13T14:00:06Z"
    },
    {
      "name": "build",
      "status": "succeeded",
      "started_at": "2026-11-13T14:00:06Z",
      "finished_at": "2026-11-13T14:02:31Z"
    },
    {
      "name": "push",
      "status": "succeeded",
      "started_at": "2026-11-13T14:02:31Z",
      "finished_at": "2026-11-13T14:02:48Z",
      "note": "84 MB"
    },
    {
      "name": "release",
      "status": "succeeded",
      "started_at": "2026-11-13T14:02:48Z",
      "finished_at": "2026-11-13T14:02:49Z"
    },
    {
      "name": "health",
      "status": "succeeded",
      "started_at": "2026-11-13T14:02:49Z",
      "finished_at": "2026-11-13T14:03:11Z"
    },
    {
      "name": "live",
      "status": "succeeded",
      "started_at": "2026-11-13T14:03:11Z",
      "finished_at": "2026-11-13T14:03:11Z"
    }
  ],
  "diagnosis": null,
  "image_digest": "sha256:4b1f9c0e7d2a8356bc41e9d0f7a6c3258e1d4b97a0c6f3e5d28b71a94c60e3fd",
  "created_by": "Ada Lovelace",
  "created_at": "2026-11-13T14:00:01Z",
  "started_at": "2026-11-13T14:00:02Z",
  "finished_at": "2026-11-13T14:03:11Z"
}
Runs in your browser against your workspace with a key you paste.

Environment

The variables a service build can use, and the credentials Kilby uses to pull private images. Runtime variables are part of the service: send env when you create or change one. Secret files, the plaintext files a service reads at /etc/secrets, have their own endpoints here.

GET/api/v1/services/{id}/build-env #

List build variables

view Any key

The names of the variables a service built from Git can use while it builds, never their values. Build variables are separate from runtime variables (env): they exist only during the build, for example a token for a private package registry, and they never reach a build started by a pull request from a fork.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The names, sorted.
  • namesarray of stringrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    The service is not built from Git.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/build-env
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"names": ["NEXT_PUBLIC_API_URL", "NPM_TOKEN"]}
Runs in your browser against your workspace with a key you paste.
PUT/api/v1/services/{id}/build-env #

Replace build variables

secrets Developer key or higher

Replaces all build variables with the ones you send; an empty env removes them all. Values are stored encrypted and never returned. The change applies from the next build.

Path parameters

  • iduuidrequired
    The service's id.

Request body

  • envobject of stringrequired
    Name to value.

    up to 20 variables, values up to 4,096 characters, names of letters, digits and underscores.

Response

200
The names that are set now.
  • namesarray of stringrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    The service is not built from Git, or a name or value is not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

PUThttps://onkilby.com/api/v1/services/{id}/build-env
curl -X PUT "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "env": {
    "NEXT_PUBLIC_API_URL": "https://api.example.com",
    "NPM_TOKEN": "npm_xxxxxxxx"
  }
}'
{"names": ["NEXT_PUBLIC_API_URL", "NPM_TOKEN"]}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/env #

List environment variables

view Any key

The names of the service's environment variables, never their values. A read-only key can call it, as a viewer sees the names in the dashboard.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The names, sorted. Empty when there are none.
  • namesarray of stringrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/env
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"names": ["DATABASE_URL", "LOG_LEVEL"]}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/services/{id}/env #

Change environment variables

secrets Developer key or higher

Sets and removes some variables and leaves the rest alone (to replace them all, use env in Change a service). The change is atomic: every part of the request applies or none does, and requests sent at the same time all take effect. A running service restarts with the new values, as when you save the Environment tab, and restarted says so; a suspended service, or a Git service that has no image yet, only saves them. A request that changes nothing writes nothing and restarts nothing. Values are stored encrypted and never returned.

Path parameters

  • iduuidrequired
    The service's id.

Request body Both fields are optional; `{}` changes nothing. Unknown fields, `null`, a value that is not a string and a name in both lists are refused.

  • setobject of string
    Name to value.

    names of letters, digits and underscores up to 128 characters, values up to 8 KB, up to 100 variables and 512 KB per service.

  • unsetarray of string
    Names to remove.

Response

200
The names now set, and what changed.
  • namesarray of stringrequired
  • addedarray of stringrequired
  • changedarray of stringrequired
  • removedarray of stringrequired
  • restartedbooleanrequired
    Whether the service restarts to use the new values.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The service is being deleted.

  • 413too_large

    The request is larger than 512 KB.

  • 422invalid_request

    A name or value is not valid, or the body has fields it should not.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/services/{id}/env
curl -X PATCH "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"set": {"LOG_LEVEL": "debug"}, "unset": ["OLD_FLAG"]}'
{
  "names": ["DATABASE_URL", "LOG_LEVEL"],
  "added": [],
  "changed": ["LOG_LEVEL"],
  "removed": ["OLD_FLAG"],
  "restarted": true
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/services/{id}/build-env #

Change build variables

secrets Developer key or higher

Like Change environment variables, for the variables a service built from Git can use while it builds. It applies from the next build and restarts nothing.

Path parameters

  • iduuidrequired
    The service's id.

Request body Both fields are optional; `{}` changes nothing.

  • setobject of string
    Name to value.

    up to 20 variables in all, values up to 4,096 characters.

  • unsetarray of string
    Names to remove.

Response

200
The names now set, and what changed. restarted is always false.
  • namesarray of stringrequired
  • addedarray of stringrequired
  • changedarray of stringrequired
  • removedarray of stringrequired
  • restartedbooleanrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    The service is not built from Git, or a name or value is not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/services/{id}/build-env
curl -X PATCH "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"set": {"NPM_TOKEN": "npm_xxxxxxxx"}}'
{
  "names": ["NPM_TOKEN"],
  "added": ["NPM_TOKEN"],
  "changed": [],
  "removed": [],
  "restarted": false
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/registry-credentials #

List registry credentials

view Any key

The credentials Kilby uses to pull private images, and the services that use each. Passwords and tokens are never returned.

Response

200
The credentials.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/registry-credentials
curl "https://onkilby.com/api/v1/registry-credentials" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "registry_credentials": [
    {
      "id": "9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12",
      "name": "github-acme",
      "registry": "ghcr.io",
      "username": "octocat",
      "used_by": [
        {"id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea", "name": "my-api"}
      ],
      "created_at": "2026-11-13T10:02:41Z",
      "updated_at": "2026-11-13T10:02:41Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/registry-credentials #

Add registry credentials

secrets Developer key or higher

Stores credentials for a private registry, encrypted. Then name them in registry_credential_id when you create or change a service. Amazon ECR is not supported yet because its login tokens expire every 12 hours; GHCR, Docker Hub, GitLab and Quay work.

Request body

  • namestringrequired
    A name for you to recognise them by. Unique in the workspace.

    up to 60 characters.

  • registrystringrequired
    The registry host.

    a host such as ghcr.io, docker.io or registry.gitlab.com.

  • usernamestringrequired
    The registry user name.

    up to 255 characters, no colon.

  • passwordstringrequired
    The password or access token. It needs permission to read packages only.

    up to 8 KB.

Response

201
The credentials, without the password.

Returns a RegistryCredential object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 409conflict

    The workspace already has credentials with that name.

  • 422invalid_request

    A field is not valid, or the registry is not allowed.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/registry-credentials
curl -X POST "https://onkilby.com/api/v1/registry-credentials" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "github-acme",
  "registry": "ghcr.io",
  "username": "octocat",
  "password": "ghp_xxxxxxxxxxxxxxxx"
}'
{
  "id": "9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12",
  "name": "github-acme",
  "registry": "ghcr.io",
  "username": "octocat",
  "used_by": [],
  "created_at": "2026-11-13T10:02:41Z",
  "updated_at": "2026-11-13T10:02:41Z"
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/registry-credentials/{id} #

Replace a token

secrets Developer key or higher

Replaces the password or token, and the user name if you send one. Use it when a token expires: services pull with the new one from their next pull.

Path parameters

  • iduuidrequired
    The registry credentials' id.

Request body

  • usernamestring
    A new user name. Leave it out to keep the current one.
  • passwordstringrequired
    The new password or token.

    up to 8 KB.

Response

200
The credentials.

Returns a RegistryCredential object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    The password is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/registry-credentials/{id}
curl -X PATCH "https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password": "ghp_yyyyyyyyyyyyyyyy"}'
{
  "id": "9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12",
  "name": "github-acme",
  "registry": "ghcr.io",
  "username": "octocat",
  "used_by": [
    {"id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea", "name": "my-api"}
  ],
  "created_at": "2026-11-13T10:02:41Z",
  "updated_at": "2026-11-13T10:02:41Z"
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/registry-credentials/{id} #

Delete registry credentials

secrets Developer key or higher

Deletes credentials that no service uses.

Path parameters

  • iduuidrequired
    The registry credentials' id.

Response

204
Deleted. There is no body.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    A service still uses them. The message names the services.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/registry-credentials/{id}
curl -X DELETE "https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12" \
  -H "Authorization: Bearer $KILBY_API_KEY"
No response body.
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/secret-files #

List secret files

view Any key

The names, sizes and dates of the service's secret files and the limits that apply, never any content. A read-only key can call it, as a viewer sees the names in the dashboard. A service finds each file at /etc/secrets/<name> (path), read-only. The files are not in the app's working directory.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The files, by name. Empty when there are none.
  • filesarray of objectrequired
    Each has name, path, size (bytes), created_at and updated_at.
  • directorystringrequired
    Where a service finds its files.
  • limitsobjectrequired
    max_file_bytes, files_per_service, bytes_per_service, files_per_workspace and bytes_per_workspace.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/secret-files
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "files": [
    {
      "name": ".env",
      "path": "/etc/secrets/.env",
      "size": 142,
      "created_at": "2026-11-13T14:05:00Z",
      "updated_at": "2026-11-13T14:05:00Z"
    }
  ],
  "directory": "/etc/secrets",
  "limits": {
    "max_file_bytes": 131072,
    "files_per_service": 10,
    "bytes_per_service": 786432,
    "files_per_workspace": 100,
    "bytes_per_workspace": 8388608
  }
}
Runs in your browser against your workspace with a key you paste.
PUT/api/v1/services/{id}/secret-files/{name} #

Add or replace a secret file

secrets Developer key or higher

Stores the file, encrypted, and makes it available to the service at /etc/secrets/<name>, read-only. It creates the file or replaces its content. A running service restarts with the new file, as when you save the Environment tab, and restarted says so: a service without a disk gets a rolling deploy, a service with a disk is down for a short time because its old instance stops first, and a suspended service, or a cron job, takes the file the next time it starts or runs. Sending the same content again writes nothing and restarts nothing. The content is text: it must be valid UTF-8 and have no NUL byte (encode a binary file, for example in base64, and decode it when the service starts). Files are readable by root and, on a service without a disk, by the group every process of the service is in. The content is never returned.

Path parameters

  • iduuidrequired
    The service's id.
  • namestringrequired
    The file's name: a plain file name, not a path.

    letters, digits, dots, underscores and hyphens, 128 characters at most, not made of dots only and not starting with two dots.

Request body

  • contentstringrequired
    The text of the file. Line breaks are kept as sent.

    1 byte to 128 KB; up to 10 files and 768 KB per service by default.

  • namestring
    Optional. When it is sent it must be the name in the path.

Response

201
The file was created.
  • fileobjectrequired
    name, path, size, created_at and updated_at.
  • createdbooleanrequired
    true.
  • changedbooleanrequired
    true.
  • restartedbooleanrequired
    Whether the service restarts to use the file.
200
The file existed. changed is false when the content was the same.
  • fileobjectrequired
  • createdbooleanrequired
    false.
  • changedbooleanrequired
  • restartedbooleanrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The service is being deleted.

  • 413too_large

    The request is larger than 512 KB.

  • 422invalid_request

    The name or content is not valid, the file is larger than allowed, or the service or the workspace would have more files, or more bytes in all, than the limits allow.

  • 429rate_limited

    Too many changes to secret files in this workspace in a minute (60 by default).

PUThttps://onkilby.com/api/v1/services/{id}/secret-files/{name}
curl -X PUT "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "DATABASE_URL=postgres://app:example@db-main-rw:5432/app\nLOG_LEVEL=info\n"
}'
{
  "file": {
    "name": ".env",
    "path": "/etc/secrets/.env",
    "size": 142,
    "created_at": "2026-11-13T14:05:00Z",
    "updated_at": "2026-11-13T14:05:00Z"
  },
  "created": true,
  "changed": true,
  "restarted": true
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/services/{id}/secret-files/{name} #

Delete a secret file

secrets Developer key or higher

Removes the file, and the content with it. A running service restarts without it, exactly like Add or replace a secret file. Deleting the service deletes all its files.

Path parameters

  • iduuidrequired
    The service's id.
  • namestringrequired
    The file's name: a plain file name, not a path.

    letters, digits, dots, underscores and hyphens, 128 characters at most, not made of dots only and not starting with two dots.

Response

200
The name that was removed.
  • removedstringrequired
    The file's name.
  • restartedbooleanrequired
    Whether the service restarts without the file.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The service has no such file.

  • 409conflict

    The service is being deleted.

  • 429rate_limited

    Too many changes to secret files in this workspace in a minute.

DELETEhttps://onkilby.com/api/v1/services/{id}/secret-files/{name}
curl -X DELETE "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"removed": ".env", "restarted": true}
Runs in your browser against your workspace with a key you paste.

Environment groups

A group is a set of variables you define once and link to several services of the workspace: shared keys, database addresses, feature flags. A service gets its own variables plus those of its groups; when a name is in more than one place, the service's own variable wins, then the group listed first. Changing a group restarts every service that uses it, once each. Values go in and never come out.

GET/api/v1/env-groups #

List environment groups

view Any key

The workspace's groups with the names of their variables and the services that use each, never any value.

Response

200
The groups, by name.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/env-groups
curl "https://onkilby.com/api/v1/env-groups" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "env_groups": [
    {
      "id": "c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c",
      "name": "shared-keys",
      "variables": ["OPENAI_API_KEY", "SENTRY_DSN"],
      "services": [
        {
          "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
          "name": "my-api",
          "position": 1
        }
      ],
      "created_at": "2026-11-13T14:05:00Z",
      "updated_at": "2026-11-13T14:05:00Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/env-groups #

Create an environment group

secrets Developer key or higher

Creates a group, optionally with its first variables. Values are stored encrypted and never returned. A group restarts nothing until a service uses it: link it with Link groups to a service.

Request body

  • namestringrequired
    Unique in the workspace.

    3 to 40 characters: lowercase letters, digits and single hyphens, starting with a letter.

  • envobject of string
    Name to value.

    names of letters, digits and underscores up to 128 characters, values up to 8 KB, up to 100 variables in a request and 512 KB in all.

Response

201
The group.
  • iduuidrequired
  • namestringrequired
  • variablesarray of stringrequired
    The names of the variables, sorted. Values are never returned.
  • servicesarray of objectrequired
    The services that use the group: id, name and position, which is where the group is in that service's list (1 wins over 2 when both define a name).
  • created_atdatetimerequired
  • updated_atdatetimerequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 409conflict

    The workspace already has a group with that name.

  • 413too_large

    The request is larger than 512 KB.

  • 422invalid_request

    The name or a variable is not valid, or the workspace has reached its limit of groups (20 by default).

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/env-groups
curl -X POST "https://onkilby.com/api/v1/env-groups" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "shared-keys",
  "env": {
    "OPENAI_API_KEY": "your-key",
    "SENTRY_DSN": "https://example.invalid/1"
  }
}'
{
  "id": "c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c",
  "name": "shared-keys",
  "variables": ["OPENAI_API_KEY", "SENTRY_DSN"],
  "services": [],
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/env-groups/{id} #

Read an environment group

view Any key

One group: the names of its variables, never their values, and the services that use it.

Path parameters

  • iduuidrequired
    The environment group's id.

Response

200
The group.
  • iduuidrequired
  • namestringrequired
  • variablesarray of stringrequired
    The names of the variables, sorted. Values are never returned.
  • servicesarray of objectrequired
    The services that use the group: id, name and position, which is where the group is in that service's list (1 wins over 2 when both define a name).
  • created_atdatetimerequired
  • updated_atdatetimerequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such group in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/env-groups/{id}
curl "https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c",
  "name": "shared-keys",
  "variables": ["OPENAI_API_KEY", "SENTRY_DSN"],
  "services": [
    {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "my-api",
      "position": 1
    }
  ],
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/env-groups/{id} #

Change an environment group

secrets Developer key or higher

Renames the group, sets and removes some of its variables and leaves the rest alone. The change is atomic: every part applies or none does. A change to the variables restarts every service that uses the group, once each, and restarted names them. A service without a disk gets a rolling deploy (the old version keeps running until the new one is ready); a service with a disk is down for a short time, because its old instance stops first; a suspended service or a cron job takes the new values the next time it starts. A rename restarts nothing, and a request that changes nothing writes nothing. Values are stored encrypted and never returned.

Path parameters

  • iduuidrequired
    The environment group's id.

Request body Every field is optional; `{}` changes nothing. Unknown fields, `null`, a value that is not a string and a name in both lists are refused.

  • namestring
    A new name.
  • setobject of string
    Name to value.

    names of letters, digits and underscores up to 128 characters, values up to 8 KB, up to 100 variables per request.

  • unsetarray of string
    Names to remove.

Response

200
The names now set, what changed and which services restarted.
  • iduuidrequired
  • namestringrequired
  • variablesarray of stringrequired
  • addedarray of stringrequired
  • changedarray of stringrequired
  • removedarray of stringrequired
  • restartedarray of stringrequired
    The names of the services that were restarted.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such group in this workspace.

  • 409conflict

    Another group has that name.

  • 413too_large

    The request is larger than 512 KB.

  • 422invalid_request

    A name or value is not valid, the group would have more variables than allowed, or a service that uses it would receive more than 512 KB.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/env-groups/{id}
curl -X PATCH "https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "set": {"SENTRY_DSN": "https://example.invalid/2"},
  "unset": ["OLD_FLAG"]
}'
{
  "id": "c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c",
  "name": "shared-keys",
  "variables": ["OPENAI_API_KEY", "SENTRY_DSN"],
  "added": [],
  "changed": ["SENTRY_DSN"],
  "removed": ["OLD_FLAG"],
  "restarted": ["my-api"]
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/env-groups/{id} #

Delete an environment group

deploy Developer key or higher

Deletes the group. While services use it the call is refused with 409 and the message names them: send unlink=true to delete it anyway. The services are then unlinked from it and restarted once each, without its variables, and their next deploy no longer has them.

Path parameters

  • iduuidrequired
    The environment group's id.

Query parameters

  • unlinkboolean
    true to delete a group that services use, unlinking them.

    Default false.

Response

200
What was deleted and which services were unlinked and restarted.
  • deletedstringrequired
    The group's name.
  • unlinkedarray of stringrequired
    The services that used it.
  • restartedarray of stringrequired
    Those that were restarted.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such group in this workspace.

  • 409conflict

    Services still use the group, and unlink=true was not sent.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/env-groups/{id}
curl -X DELETE "https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "deleted": "shared-keys",
  "unlinked": ["my-api"],
  "restarted": ["my-api"]
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/env-groups #

List the groups a service uses

view Any key

The environment groups linked to the service, in order: when two define the same name, the first wins, and the service's own variables win over all of them.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The groups, in order.
  • env_groupsarray of objectrequired
    The groups in order, first wins: id, name and position (1 is first).

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/env-groups
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "env_groups": [
    {
      "id": "c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c",
      "name": "shared-keys",
      "position": 1
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
PUT/api/v1/services/{id}/env-groups #

Link groups to a service

deploy Developer key or higher

Makes the list you send, in that order, the groups of the service: it links what is new, unlinks what is missing and reorders. A change that does something restarts a running service once, however many groups it touches, exactly like saving the Environment tab; restarted says so. The same list again changes nothing. A group has to be one of this workspace's; any other is 404.

Path parameters

  • iduuidrequired
    The service's id.

Request body

  • env_groupsarray of stringrequired
    Group names or ids, first one winning. An empty list unlinks them all.

    up to 20 groups per service by default.

Response

200
The groups now linked and what changed.
  • env_groupsarray of objectrequired
    The groups in order: id, name and position.
  • linkedarray of stringrequired
    Names of the groups that are new.
  • unlinkedarray of stringrequired
    Names of the groups that were removed.
  • restartedbooleanrequired
    Whether the service restarts to use the new variables.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    A group is not one of this workspace's.

  • 409conflict

    The service is being deleted, or a group appears twice.

  • 422invalid_request

    More groups than a service can use, or the service would receive more than 512 KB of variables.

  • 429rate_limited

    More than 300 requests a minute for this key.

PUThttps://onkilby.com/api/v1/services/{id}/env-groups
curl -X PUT "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"env_groups": ["shared-keys", "flags"]}'
{
  "env_groups": [
    {
      "id": "c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c",
      "name": "shared-keys",
      "position": 1
    }
  ],
  "linked": ["shared-keys"],
  "unlinked": [],
  "restarted": true
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/env/effective #

List the effective environment

view Any key

Every variable the service runs with and where its value comes from: the service itself, or one of its groups. overrides names the groups whose value for the same name this one hides. Names only, never values, like List environment variables.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The variables, sorted by name.
  • variablesarray of objectrequired
    Each has name, source (service or group), group (id, name, position; null for the service's own) and overrides.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/env/effective
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env/effective" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "variables": [
    {
      "name": "LOG_LEVEL",
      "source": "service",
      "group": null,
      "overrides": ["shared-keys"]
    },
    {
      "name": "OPENAI_API_KEY",
      "source": "group",
      "group": {
        "id": "c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c",
        "name": "shared-keys",
        "position": 1
      },
      "overrides": []
    }
  ]
}
Runs in your browser against your workspace with a key you paste.

Databases

Managed Postgres with continuous backups. A database is reachable from every service in the same workspace and from nowhere else.

GET/api/v1/databases #

List databases

view Any key

The workspace's databases. The connection URL, which holds the password, is not in the list: use Get a database.

Response

200
The databases.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/databases
curl "https://onkilby.com/api/v1/databases" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "databases": [
    {
      "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
      "name": "main",
      "engine": "postgres",
      "version": "17",
      "plan": "starter",
      "storage_gb": 5,
      "status": "available",
      "status_message": "",
      "host": "db-main-rw",
      "port": 5432,
      "database": "app",
      "user": "app",
      "created_at": "2026-11-12T22:40:11Z",
      "environment": {
        "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
        "name": "Production",
        "default": true,
        "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
      },
      "autogrow": false,
      "autogrow_max_gb": 0,
      "high_availability": false,
      "synchronous_replication": false
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/databases #

Create a database

deploy Developer key or higher

Creates a Postgres database. It takes about a minute: poll Get a database until status is available, then give internal_url to a service as an environment variable. The answer is the only one besides Get that includes the URL, and it works from any service in the same workspace.

Databases are in beta. Where backups are available, a database is backed up continuously; List backups says whether yours is.

Request body

  • namestringrequired
    Unique in the workspace.

    3 to 30 characters: lowercase letters, digits and hyphens, starting with a letter.

  • versionstring
    The Postgres major version. postgres_versions in Get the workspace lists the ones this Kilby offers; leaving it out creates 17. A database cannot be upgraded to a newer major version in place.

    Default 17.

  • planstring
    The instance type.

    One of starter, standard, pro. Default starter.

  • storage_gbinteger
    The size of the disk, in GB.

    One of 1, 5, 10, 20. Default 5.

  • environmentstring
    Where to list the database: an environment id, project/environment by names, or an environment name when only one has it. Leave it out for the default one. See Projects.
  • autogrowboolean
    Grow the disk by itself: when the disk is 90% full or more, it grows by the larger of 20% and 1 GB. Off by default. Not available on every Kilby: the answer is a 422 where it is off.

    Default false.

  • autogrow_max_gbinteger
    The largest size the disk may grow to. Required with autogrow, more than storage_gb, and not more than what the workspace's disk limit leaves after its other disks.
  • high_availabilityboolean
    Run a standby of the database on another node and fail over to it automatically. It adds a second instance and a second disk, which count against the workspace's limits and are billed like any other. Refused with a 422 while the platform does not offer it.

    Default false.

  • synchronous_replicationboolean
    With high_availability: each commit waits until the standby has it. Without it, replication is asynchronous and the last few transactions can be lost in a failover.

    Default false.

Response

201
The new database, with its connection URL.

Returns a Database object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 422invalid_request

    A field is not valid, the name is taken, or the workspace's database or disk limit would be exceeded.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/databases
curl -X POST "https://onkilby.com/api/v1/databases" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "main", "version": "17", "plan": "starter", "storage_gb": 5}'
{
  "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
  "name": "main",
  "engine": "postgres",
  "version": "17",
  "plan": "starter",
  "storage_gb": 5,
  "status": "creating",
  "status_message": "Setting up the primary",
  "host": "db-main-rw",
  "port": 5432,
  "database": "app",
  "user": "app",
  "internal_url": "postgresql://app:Zq7xV2mKd9PtR4wB@db-main-rw:5432/app",
  "created_at": "2026-11-12T22:40:11Z",
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "autogrow": false,
  "autogrow_max_gb": 0,
  "high_availability": false,
  "synchronous_replication": false
}
Runs in your browser against your workspace with a key you paste.
PUT/api/v1/databases/{id}/autogrow #

Grow the disk automatically

deploy Developer key or higher

Turns on or off growing the disk by itself. While it is on, Kilby measures the disk every 5 minutes; when the disk is 90% full or more, it grows by the larger of 20% and 1 GB. It never grows above max_gb or above the workspace's disk limit, and it never shrinks. A disk can be changed once every 6 hours (an AWS rule for the volume), so a growth that is due sooner waits and happens when the time is over. Each growth sends the database.storage_grown event to webhooks and email, and is billed like any other disk.

Off by default. Where this Kilby does not have it yet, the answer is a 422.

Path parameters

  • iduuidrequired
    The database's id.

Request body

  • enabledbooleanrequired
    true to grow the disk by itself, false to stop.
  • max_gbinteger
    The largest size the disk may grow to. Required when enabled is true.

Response

200
The database with its new setting.

Returns a Database object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    max_gb is missing, not more than the disk, or more than the workspace's disk limit leaves; or growing the disk by itself is not available yet.

  • 429rate_limited

    More than 300 requests a minute for this key.

PUThttps://onkilby.com/api/v1/databases/{id}/autogrow
curl -X PUT "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/autogrow" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "max_gb": 20}'
{
  "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
  "name": "main",
  "engine": "postgres",
  "version": "17",
  "plan": "starter",
  "storage_gb": 5,
  "status": "available",
  "status_message": "",
  "host": "db-main-rw",
  "port": 5432,
  "database": "app",
  "user": "app",
  "created_at": "2026-11-12T22:40:11Z",
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "autogrow": true,
  "autogrow_max_gb": 20,
  "high_availability": false,
  "synchronous_replication": false
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/databases/{id} #

Get a database

view Any key

One database with its status and address. internal_url includes the password, so it is only returned to a key that may see secrets: a viewer key gets everything else.

Path parameters

  • iduuidrequired
    The database's id.

Response

200
The database.

Returns a Database object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/databases/{id}
curl "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
  "name": "main",
  "engine": "postgres",
  "version": "17",
  "plan": "starter",
  "storage_gb": 5,
  "status": "available",
  "status_message": "",
  "host": "db-main-rw",
  "port": 5432,
  "database": "app",
  "user": "app",
  "internal_url": "postgresql://app:Zq7xV2mKd9PtR4wB@db-main-rw:5432/app",
  "created_at": "2026-11-12T22:40:11Z",
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "autogrow": false,
  "autogrow_max_gb": 0,
  "high_availability": false,
  "synchronous_replication": false
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/databases/{id} #

Update a database

deploy Developer key or higher

Changes the instance type, grows the disk, or turns high availability on or off. Every field is optional; send at least one. environment only changes where the database is listed (see Projects); send it on its own. The database goes to updating while Kilby applies the change: poll Get a database until status is available.

High availability. Turning it on adds a standby on another node: Kilby copies the data to it in the background and the database stays available meanwhile. For a database that never had a standby, the cluster's pods change, so once the copy is done the database switches over to the new node: connections drop once, usually for less than a minute, and clients must reconnect. Turning it off removes the standby and its disk: nothing restarts, no data is lost, and the price drops. Changing the instance type of a database with a standby updates the standby first and then switches over, which also drops connections once, for a few seconds.

A failover takes tens of seconds, not zero. With synchronous_replication false, the last few transactions the standby had not received can be lost in a failover; with it true a committed transaction survives while the standby is in sync, and every write waits for a network round trip. High availability protects against a node or zone failing. It does not protect against a bad migration or a dropped table, which the standby copies at once: use backups for that.

While a database has a standby, Get a database also returns standby:

``json { "standby": { "state": "in_sync", "primary_instance": "db-main-1", "standby_instance": "db-main-2", "primary_zone": "us-east-2a", "standby_zone": "us-east-2b", "last_failover": {"at": "2026-11-13T22:41:09Z", "from": "db-main-2", "to": "db-main-1", "planned": false} } } ``

A standby counts as a second database against the workspace's CPU, memory and disk limits; the refusal says which limit.

Path parameters

  • iduuidrequired
    The database's id.

Request body

  • planstring
    The instance type.

    One of starter, standard, pro.

  • storage_gbinteger
    The size of the disk, in GB. It can grow but not shrink.

    One of 1, 5, 10, 20.

  • high_availabilityboolean
    true adds a standby, false removes it. Refused with a 422 while the platform does not offer it, unless the database already has one and you are turning it off.
  • synchronous_replicationboolean
    Each commit waits for the standby. Only with high_availability.
  • environmentstring
    Where to list the database: an environment id, project/environment by names, or a name only one environment has. It only organizes: moving restarts nothing, so send it in a request of its own, not with the other fields. See Projects.

Response

200
The database, now updating.

Returns a Database object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The database is not available yet, so its high availability cannot change.

  • 422invalid_request

    A field is not valid, nothing was sent, the environment does not exist, its name matches more than one, or it was sent with other fields, high availability is not available yet, the disk would shrink, or the workspace's CPU, memory or disk limit would be exceeded (a standby counts as a second database).

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/databases/{id}
curl -X PATCH "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"high_availability": true}'
{
  "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
  "name": "main",
  "engine": "postgres",
  "version": "17",
  "plan": "starter",
  "storage_gb": 5,
  "status": "updating",
  "status_message": "",
  "host": "db-main-rw",
  "port": 5432,
  "database": "app",
  "user": "app",
  "internal_url": "postgresql://app:Zq7xV2mKd9PtR4wB@db-main-rw:5432/app",
  "created_at": "2026-11-12T22:40:11Z",
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "autogrow": false,
  "autogrow_max_gb": 0,
  "high_availability": true,
  "synchronous_replication": false
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/databases/{id} #

Delete a database

deploy Developer key or higher

Deletes the database and its data. This cannot be undone, but the backups of a deleted database stay restorable for 30 days: see Restore a database.

Path parameters

  • iduuidrequired
    The database's id.

Response

202
The database is being deleted.
  • iduuidrequired
  • statusstringrequired
    Always deleting.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/databases/{id}
curl -X DELETE "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e", "status": "deleting"}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/databases/{id}/backups #

List backups

view Any key

Whether the database is being backed up, how far back it can be restored, and its recent base backups. Every change is archived continuously and a base backup is taken once a day, so a database can be restored to any second inside recovery_window, up to 7 days back.

status is healthy, starting, setting_up, failing or off.

Path parameters

  • iduuidrequired
    The database's id.

Response

200
The backup status.
  • enabledbooleanrequired
  • statusstringrequired

    One of healthy, starting, setting_up, failing, off.

  • messagestringrequired
    What is wrong, when status is failing.
  • retention_daysintegerrequired
    How far back the database can be restored.
  • daily_backup_timestringrequired
    When the daily base backup runs.
  • last_backup_atdatetime or nullrequired
  • recovery_windowobjectrequired
    The range you can restore to.
  • firstdatetime or nullrequired
  • latestdatetime or nullrequired
  • backupsarray of Backuprequired
  • restored_fromobject
    Present when this database was created by a restore.
  • iduuidrequired
  • namestringrequired
  • target_timedatetime or nullrequired
    null: the latest point

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/databases/{id}/backups
curl "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "enabled": true,
  "status": "healthy",
  "message": "",
  "retention_days": 7,
  "daily_backup_time": "03:17 UTC",
  "last_backup_at": "2026-11-13T03:19:40Z",
  "recovery_window": {"first": "2026-11-06T03:17:02Z", "latest": "2026-11-13T14:02:11Z"},
  "backups": [
    {
      "id": "4b1f6c2d-8e3a-4f70-9a15-0c7d2e9b8a61",
      "name": "db-main-daily-20261113031700",
      "type": "scheduled",
      "status": "succeeded",
      "message": "",
      "created_at": "2026-11-13T03:17:00Z",
      "started_at": "2026-11-13T03:17:02Z",
      "finished_at": "2026-11-13T03:19:40Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/databases/{id}/backups #

Take a backup now

deploy Developer key or higher

Queues a base backup. It starts within a minute. A database can be backed up by hand up to 6 times a day; it is also backed up continuously and every night.

Path parameters

  • iduuidrequired
    The database's id.

Response

202
The queued backup.

Returns a Backup object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    Backups are not set up for this database yet, it is not available, another backup is in progress, or 6 were taken today.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/databases/{id}/backups
curl -X POST "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "4b1f6c2d-8e3a-4f70-9a15-0c7d2e9b8a62",
  "name": "db-main-manual-1794524411",
  "type": "manual",
  "status": "queued",
  "message": "",
  "created_at": "2026-11-13T14:05:00Z",
  "started_at": null,
  "finished_at": null,
  "requested_by": "Ada Lovelace"
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/databases/{id}/restore #

Restore a database

deploy Developer key or higher

Creates a new database from the backups of this one, at the latest point or at a moment you choose inside recovery_window. The source keeps running and is not changed. The new database has its own password and its own backups.

The {id} may also be that of a database deleted in the last 30 days.

Path parameters

  • iduuidrequired
    The database's id.

Request body

  • namestringrequired
    The new database's name.

    3 to 30 characters.

  • target_timestring
    The moment to restore, in RFC 3339, UTC. Leave it out, or send latest, for the latest point.
  • planstring
    The instance type. Defaults to the source's.

    One of starter, standard, pro.

  • storage_gbinteger
    The size of the disk, in GB. Defaults to the source's; it cannot be smaller.

    One of 1, 5, 10, 20.

Response

201
The new database and where it comes from.
  • databaseDatabaserequired
    The new database, with its own internal_url.
  • restored_fromobjectrequired
  • iduuidrequired
  • namestringrequired
  • target_timedatetime or nullrequired
    null: the latest point

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No database with backups to restore from has that id.

  • 409conflict

    Backups are off, there is nothing to restore from yet, or the backups are kept somewhere this platform cannot restore from.

  • 422invalid_request

    target_time is outside the recovery window, or a field is not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/databases/{id}/restore
curl -X POST "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/restore" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "main-restore", "target_time": "2026-11-13T09:30:00Z"}'
{
  "database": {
    "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
    "name": "main-restore",
    "engine": "postgres",
    "version": "17",
    "plan": "starter",
    "storage_gb": 5,
    "status": "creating",
    "status_message": "",
    "host": "db-main-restore-rw",
    "port": 5432,
    "database": "app",
    "user": "app",
    "internal_url": "postgresql://app:Zq7xV2mKd9PtR4wB@db-main-rw:5432/app",
    "created_at": "2026-11-12T22:40:11Z",
    "environment": {
      "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
      "name": "Production",
      "default": true,
      "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
    },
    "autogrow": false,
    "autogrow_max_gb": 0,
    "high_availability": false,
    "synchronous_replication": false
  },
  "restored_from": {
    "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
    "name": "main",
    "target_time": "2026-11-13T09:30:00Z"
  }
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/databases/{id}/imports #

List imports

view Any key

The latest imports into the database, newest first, and the saved source if there is one. saved_source is what Sync again copies from: its host, port and database name, and when Kilby deletes it.

Path parameters

  • iduuidrequired
    The database's id.

Response

200
The imports.
  • Up to 20, newest first.
  • iduuidrequired
  • database_iduuidrequired
    The database the data is copied into.
  • kindstringrequired
    import for a URL that was sent, sync for a copy from the saved URL.

    One of import, sync.

  • statusstringrequired

    One of queued, running, succeeded, failed.

  • messagestringrequired
    While it runs, what it is doing. When it failed, why, and whether anything changed.
  • sourcestringrequired
    The source's host, port and database name. Never the user or the password.
  • requested_bystringrequired
    Who asked for it; empty if the account no longer exists.
  • source_versionstring or nullrequired
    The source's Postgres version, such as 16.4, once the copy has connected to it.
  • source_bytesinteger or nullrequired
    The size of the source database, in bytes.
  • target_bytesinteger or nullrequired
    The size of this database after the copy, in bytes.
  • tablesinteger or nullrequired
    How many tables this database has after the copy.
  • skipped_extensionsarray of stringrequired
    Extensions of the source that were not created, because only a superuser may create them.
  • outputstringrequired
    The end of what the copy printed, with the source URL and both passwords removed.
  • created_atdatetimerequired
  • started_atdatetime or nullrequired
  • finished_atdatetime or nullrequired
  • saved_sourceobject or nullrequired
    null when no source URL is saved.
  • sourcestringrequired
    Host, port and database name.
  • saved_atdatetimerequired
  • expires_atdatetimerequired
    When Kilby deletes it: 7 days after it was last used.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/databases/{id}/imports
curl "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "imports": [
    {
      "id": "3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b",
      "database_id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
      "kind": "import",
      "status": "succeeded",
      "message": "",
      "source": "dpg-d1abc2defg3h4i-a.oregon-postgres.render.com:5432/shop",
      "requested_by": "Ada Lovelace",
      "source_version": "16.4",
      "source_bytes": 152043520,
      "target_bytes": 148897792,
      "tables": 23,
      "skipped_extensions": ["pg_stat_statements"],
      "output": "Connecting to the source database…\nConnecting to this database…\nCopying the data…\nUpdating the planner's statistics…\nDone.",
      "created_at": "2026-11-13T14:05:00Z",
      "started_at": "2026-11-13T14:05:04Z",
      "finished_at": "2026-11-13T14:06:41Z"
    }
  ],
  "saved_source": {
    "source": "dpg-d1abc2defg3h4i-a.oregon-postgres.render.com:5432/shop",
    "saved_at": "2026-11-13T14:05:00Z",
    "expires_at": "2026-11-20T14:05:00Z"
  }
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/databases/{id}/imports #

Import from another Postgres

secrets Developer key or higher

Copies another Postgres database into this one: tables, rows, indexes, sequences, views, functions and the extensions a database owner may create. The tables it brings replace the tables of the same name here; tables only this database has are left as they are. Roles, owners and privileges are not copied: everything belongs to this database's user.

Send source_url to import. Leave the body out (or send {}) to sync again from the saved URL, for the cut-over: stop writes to the source, sync, then point your services here.

The copy runs inside this workspace, in one transaction: if it fails, or runs past 3 hours, nothing in this database changes. The source must be on the public internet, be the same Postgres version as this database or older, and accept connections from Kilby's outbound addresses (Get the network details). One import runs at a time per database. Poll Get an import for the result.

Kilby keeps the URL encrypted for 7 days after its last use, then deletes it; Forget the saved source deletes it at once. It is never returned.

Path parameters

  • iduuidrequired
    The database's id.

Request body Leave the body out to sync again from the saved URL.

  • source_urlstring
    The source's URL: postgres:// or postgresql://, with the user, the password, the host and the database name. sslmode defaults to require; disable, allow and prefer are refused. On Render, it is the database's External Database URL.

Response

202
The queued import.

Returns a DatabaseImport object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    An import into this database is already queued or running, or there is no saved URL to sync from.

  • 422invalid_request

    source_url is not a URL Kilby can import from, and the message says why: a private address, no password, sslmode=disable, a setting other than sslmode, channel_binding, connect_timeout or application_name.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/databases/{id}/imports
curl -X POST "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "source_url": "postgresql://shop_user:password@dpg-d1abc2defg3h4i-a.oregon-postgres.render.com/shop"
}'
{
  "id": "3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b",
  "database_id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
  "kind": "import",
  "status": "queued",
  "message": "",
  "source": "dpg-d1abc2defg3h4i-a.oregon-postgres.render.com:5432/shop",
  "requested_by": "Ada Lovelace",
  "source_version": null,
  "source_bytes": null,
  "target_bytes": null,
  "tables": null,
  "skipped_extensions": [],
  "output": "",
  "created_at": "2026-11-13T14:05:00Z",
  "started_at": null,
  "finished_at": null
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/databases/{id}/imports/{import_id} #

Get an import

view Any key

One import. While status is queued or running, message says what it is doing. When it failed, message says why, and output has the end of what the copy printed.

Path parameters

  • iduuidrequired
    The database's id.
  • import_iduuidrequired
    The import's id.

Response

200
The import.

Returns a DatabaseImport object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The database has no import with that id.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/databases/{id}/imports/{import_id}
curl "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports/3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b",
  "database_id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
  "kind": "import",
  "status": "succeeded",
  "message": "",
  "source": "dpg-d1abc2defg3h4i-a.oregon-postgres.render.com:5432/shop",
  "requested_by": "Ada Lovelace",
  "source_version": "16.4",
  "source_bytes": 152043520,
  "target_bytes": 148897792,
  "tables": 23,
  "skipped_extensions": ["pg_stat_statements"],
  "output": "Connecting to the source database…\nConnecting to this database…\nCopying the data…\nUpdating the planner's statistics…\nDone.",
  "created_at": "2026-11-13T14:05:00Z",
  "started_at": "2026-11-13T14:05:04Z",
  "finished_at": "2026-11-13T14:06:41Z"
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/databases/{id}/import-source #

Forget the saved source

secrets Developer key or higher

Deletes the saved source URL of the database at once. An import that already started goes on, with its own encrypted copy of the URL until it ends; one still queued fails, and changes nothing. It answers the same whether or not a URL was saved.

Path parameters

  • iduuidrequired
    The database's id.

Response

204
Deleted. There is no body.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/databases/{id}/import-source
curl -X DELETE "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/import-source" \
  -H "Authorization: Bearer $KILBY_API_KEY"
No response body.
Runs in your browser against your workspace with a key you paste.

Key Value

Managed Key Value: a private, password-protected Redis-compatible store (Valkey) for queues, caches and rate limits. It is reachable from every service in the same workspace and from nowhere else. Data survives restarts, but it is not backed up. It is only available where Kilby has turned it on; elsewhere these endpoints answer 404.

GET/api/v1/key-values #

List Key Value instances

view Any key

The workspace's Key Value instances. The connection URL, which holds the password, is not in the list: use Get the connection.

Response

200
The instances.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/key-values
curl "https://onkilby.com/api/v1/key-values" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "key_values": [
    {
      "id": "a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73",
      "name": "cache",
      "plan": "1gb",
      "memory_mb": 1024,
      "max_memory_mb": 768,
      "disk_gb": 2,
      "eviction_policy": "allkeys-lru",
      "status": "available",
      "status_message": "",
      "host": "kv-cache",
      "port": 6379,
      "created_at": "2026-11-12T22:40:11Z",
      "environment": {
        "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
        "name": "Production",
        "default": true,
        "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
      }
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/key-values #

Create a Key Value instance

deploy Developer key or higher

Creates a Key Value instance. It takes about a minute: poll Get a Key Value instance until status is available, then give internal_url to a service as an environment variable, for example REDIS_URL. The answer is the only one besides Get the connection that includes the URL.

Data is written to disk every second, so a restart loses at most the last second or two of writes. There are no backups: deleting the instance, or losing its disk, loses the data. Keep the source of truth in a database and use Key Value for what you can rebuild.

Request body

  • namestringrequired
    Unique in the workspace.

    3 to 30 characters: lowercase letters, digits and hyphens, starting with a letter.

  • planstring
    The size, by memory.

    One of 256mb, 1gb, 4gb. Default 256mb.

  • eviction_policystring
    What happens when memory is full: allkeys-lru removes the keys used least recently (a cache), noeviction refuses writes (a queue).

    One of allkeys-lru, noeviction. Default allkeys-lru.

  • environmentstring
    Where to list the instance: an environment id, project/environment by names, or an environment name when only one has it. Leave it out for the default one. See Projects.

Response

201
The new instance, with its connection URL.

Returns a KeyValue object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    Key Value is not turned on.

  • 422invalid_request

    A field is not valid, the name is taken, or the workspace's instance, memory, CPU or disk limit would be exceeded.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/key-values
curl -X POST "https://onkilby.com/api/v1/key-values" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "cache", "plan": "1gb", "eviction_policy": "allkeys-lru"}'
{
  "id": "a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73",
  "name": "cache",
  "plan": "1gb",
  "memory_mb": 1024,
  "max_memory_mb": 768,
  "disk_gb": 2,
  "eviction_policy": "allkeys-lru",
  "status": "creating",
  "status_message": "Starting…",
  "host": "kv-cache",
  "port": 6379,
  "internal_url": "redis://:Zq7xV2mKd9PtR4wB@kv-cache:6379",
  "created_at": "2026-11-12T22:40:11Z",
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  }
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/key-values/{id} #

Get a Key Value instance

view Any key

One instance with its status and address. It never includes the password: Get the connection does, for keys that may see secrets.

Path parameters

  • iduuidrequired
    The instance's id.

Response

200
The instance.

Returns a KeyValue object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/key-values/{id}
curl "https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73",
  "name": "cache",
  "plan": "1gb",
  "memory_mb": 1024,
  "max_memory_mb": 768,
  "disk_gb": 2,
  "eviction_policy": "allkeys-lru",
  "status": "available",
  "status_message": "",
  "host": "kv-cache",
  "port": 6379,
  "created_at": "2026-11-12T22:40:11Z",
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  }
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/key-values/{id} #

Change the size or the eviction policy

deploy Developer key or higher

Changes the size, the eviction policy or both. The instance restarts to apply the change, which interrupts connections for a few seconds; status is updating meanwhile. Data is kept. A bigger size grows the disk; a smaller one keeps the disk it has, because a disk cannot shrink. Make sure the data fits in the smaller size first: with noeviction writes fail when it does not.

Path parameters

  • iduuidrequired
    The instance's id.

Request body

  • planstring
    The new size.

    One of 256mb, 1gb, 4gb.

  • eviction_policystring
    The new policy.

    One of allkeys-lru, noeviction.

  • environmentstring
    Move the instance to this environment: an id, project/environment by names, or a name only one environment has. Moving restarts nothing. Send it on its own, not with plan or eviction_policy.

Response

200
The instance.

Returns a KeyValue object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    A field is not valid, nothing was sent, or the change would exceed the workspace's limits.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/key-values/{id}
curl -X PATCH "https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan": "4gb"}'
{
  "id": "a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73",
  "name": "cache",
  "plan": "4gb",
  "memory_mb": 1024,
  "max_memory_mb": 768,
  "disk_gb": 2,
  "eviction_policy": "allkeys-lru",
  "status": "updating",
  "status_message": "",
  "host": "kv-cache",
  "port": 6379,
  "created_at": "2026-11-12T22:40:11Z",
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  }
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/key-values/{id} #

Delete a Key Value instance

deploy Developer key or higher

Deletes the instance, its disk and everything on it. This cannot be undone and there is no backup to restore from.

Path parameters

  • iduuidrequired
    The instance's id.

Response

202
The instance is being deleted.
  • iduuidrequired
  • statusstringrequired
    Always deleting.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/key-values/{id}
curl -X DELETE "https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"id": "a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73", "status": "deleting"}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/key-values/{id}/connection #

Get the connection

secrets Developer key or higher

How to connect: the host, the port, the password and a redis:// URL that holds them. Only for keys that may see secrets (developer and admin keys). It works from services and cron jobs in the same workspace, not from your machine.

Path parameters

  • iduuidrequired
    The instance's id.

Response

200
The connection.
  • hoststringrequired
  • portintegerrequired
  • passwordstringrequired
  • internal_urlstringrequired
    A redis:// URL with the password.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/key-values/{id}/connection
curl "https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73/connection" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "host": "kv-cache",
  "port": 6379,
  "password": "Zq7xV2mKd9PtR4wB",
  "internal_url": "redis://:Zq7xV2mKd9PtR4wB@kv-cache:6379"
}
Runs in your browser against your workspace with a key you paste.

Cron

A cron job is a service of type cron with a schedule. Create it with Create a service; these endpoints start a run by hand and list the runs.

GET/api/v1/services/{id}/runs #

List runs

view Any key

The last 50 runs of a cron job, newest first.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The runs.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    The service is not a cron job.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/runs
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "runs": [
    {
      "name": "nightly-report-manual-1794524411",
      "status": "succeeded",
      "message": "",
      "manual": true,
      "started_at": "2026-11-12T22:46:51Z",
      "finished_at": "2026-11-12T22:46:58Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/runs #

Start a run now

deploy Developer key or higher

Runs the cron job once, outside its schedule. While a run is going, a second request answers 409.

Path parameters

  • iduuidrequired
    The service's id.

Response

202
The run has started.
  • namestringrequired
    The run's name.
  • statusstringrequired
    Always running.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The cron job is suspended, or a run is still in progress.

  • 422invalid_request

    The service is not a cron job.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 503unavailable

    Runs are not available in this environment.

POSThttps://onkilby.com/api/v1/services/{id}/runs
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"name": "nightly-report-manual-1794524411", "status": "running"}
Runs in your browser against your workspace with a key you paste.

Domains

Custom domains for web services. Add one, create the DNS records the answer lists, and Kilby checks them, requests a certificate and starts serving the domain.

GET/api/v1/services/{id}/domains #

List domains

view Any key

The custom domains of a web service, with the DNS records each one needs.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The domains and the service's own address.
  • default_hostnamestringrequired
    The address every service has.
  • domainsarray of Domainrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    The service is not a web service.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 503unavailable

    Custom domains are not turned on.

GEThttps://onkilby.com/api/v1/services/{id}/domains
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "default_hostname": "my-api-x7k2.apps.kilby.neuramorphic.ai",
  "domains": [
    {
      "id": "5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11",
      "service_id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "hostname": "api.example.com",
      "apex": false,
      "status": "pending_dns",
      "status_message": "",
      "dns_records": [
        {
          "type": "CNAME",
          "name": "api.example.com",
          "value": "my-api-x7k2.apps.kilby.neuramorphic.ai",
          "purpose": "route"
        },
        {
          "type": "TXT",
          "name": "_kilby-challenge.api.example.com",
          "value": "kilby-verify=k3x9a1c7e5b2d804",
          "purpose": "ownership"
        },
        {
          "type": "CNAME",
          "name": "_acme-challenge.api.example.com",
          "value": "k3x9a1c7e5b2d804.acme.kilby.neuramorphic.ai",
          "purpose": "certificate"
        }
      ],
      "verified_at": null,
      "certificate_expires_at": null,
      "certificate_validation": "http",
      "routed_at": null,
      "redirect_to": null,
      "last_checked_at": null,
      "next_check_at": "2026-11-13T14:07:00Z",
      "created_at": "2026-11-13T14:05:00Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/domains #

Add a custom domain

deploy Developer key or higher

Attaches a domain you own to a web service. A service can have up to 5 domains, a workspace up to 20. Wildcard domains are not supported yet.

The answer lists the DNS records to create at your DNS provider: a CNAME to the service's own address (or A records for a root domain) and a TXT record that proves you own the domain. Kilby checks them every 2 minutes for the first hour, then every hour, for 7 days. status moves from pending_dns to verifying, issuing_certificate and active; error says what to fix.

Where Kilby offers it, the list also has an _acme-challenge CNAME (purpose certificate). Moving a site that is live elsewhere, create that record alone first: it proves ownership too, and the certificate is issued while visitors still go to the old host. The domain is then active with routed_at null until you switch its first record to Kilby.

Path parameters

  • iduuidrequired
    The service's id.

Request body

  • hostnamestringrequired
    The domain, such as api.example.com.

    a valid host name, not an address under Kilby's own domains.

Response

201
The domain, waiting for its DNS records.

Returns a Domain object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The domain is already used by another service.

  • 422invalid_request

    The host name is not valid, the service is not a web service, or a limit was reached.

  • 429rate_limited

    More than 30 domains were added in the last hour.

  • 503unavailable

    Custom domains are not turned on.

POSThttps://onkilby.com/api/v1/services/{id}/domains
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "api.example.com"}'
{
  "id": "5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11",
  "service_id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "hostname": "api.example.com",
  "apex": false,
  "status": "pending_dns",
  "status_message": "",
  "dns_records": [
    {
      "type": "CNAME",
      "name": "api.example.com",
      "value": "my-api-x7k2.apps.kilby.neuramorphic.ai",
      "purpose": "route"
    },
    {
      "type": "TXT",
      "name": "_kilby-challenge.api.example.com",
      "value": "kilby-verify=k3x9a1c7e5b2d804",
      "purpose": "ownership"
    },
    {
      "type": "CNAME",
      "name": "_acme-challenge.api.example.com",
      "value": "k3x9a1c7e5b2d804.acme.kilby.neuramorphic.ai",
      "purpose": "certificate"
    }
  ],
  "verified_at": null,
  "certificate_expires_at": null,
  "certificate_validation": "http",
  "routed_at": null,
  "redirect_to": null,
  "last_checked_at": null,
  "next_check_at": "2026-11-13T14:07:00Z",
  "created_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/domains/{id}/verify #

Check a domain's DNS now

deploy Developer key or higher

Checks the domain's DNS records right away instead of waiting for the next scheduled check, and answers with the domain. Allowed 6 times a minute per domain.

Path parameters

  • iduuidrequired
    The domain's id.

Response

200
The domain after the check.

Returns a Domain object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    The domain was checked a moment ago.

POSThttps://onkilby.com/api/v1/domains/{id}/verify
curl -X POST "https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/verify" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11",
  "service_id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "hostname": "api.example.com",
  "apex": false,
  "status": "verifying",
  "status_message": "",
  "dns_records": [
    {
      "type": "CNAME",
      "name": "api.example.com",
      "value": "my-api-x7k2.apps.kilby.neuramorphic.ai",
      "purpose": "route"
    },
    {
      "type": "TXT",
      "name": "_kilby-challenge.api.example.com",
      "value": "kilby-verify=k3x9a1c7e5b2d804",
      "purpose": "ownership"
    },
    {
      "type": "CNAME",
      "name": "_acme-challenge.api.example.com",
      "value": "k3x9a1c7e5b2d804.acme.kilby.neuramorphic.ai",
      "purpose": "certificate"
    }
  ],
  "verified_at": "2026-11-13T14:05:00Z",
  "certificate_expires_at": null,
  "certificate_validation": "http",
  "routed_at": null,
  "redirect_to": null,
  "last_checked_at": null,
  "next_check_at": "2026-11-13T14:07:00Z",
  "created_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/domains/{id} #

Redirect a domain

deploy Developer key or higher

Makes the domain redirect every request to another domain of the same service, with a 301 that keeps the path and the query, such as www.example.com to example.com. null makes it serve the service again. The redirecting domain keeps its own certificate, so HTTPS requests to it work too. One hop at most: the target must serve the service, and a domain that others redirect to cannot redirect.

Path parameters

  • iduuidrequired
    The domain's id.

Request body

  • redirect_tostring or nullrequired
    Another domain of the service, or null.

Response

200
The domain.

Returns a Domain object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    redirect_to is missing, is not another domain of the service that serves it, or other domains redirect to this one.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/domains/{id}
curl -X PATCH "https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"redirect_to": "example.com"}'
{
  "id": "5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11",
  "service_id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "hostname": "www.example.com",
  "apex": false,
  "status": "pending_dns",
  "status_message": "",
  "dns_records": [
    {
      "type": "CNAME",
      "name": "api.example.com",
      "value": "my-api-x7k2.apps.kilby.neuramorphic.ai",
      "purpose": "route"
    },
    {
      "type": "TXT",
      "name": "_kilby-challenge.api.example.com",
      "value": "kilby-verify=k3x9a1c7e5b2d804",
      "purpose": "ownership"
    },
    {
      "type": "CNAME",
      "name": "_acme-challenge.api.example.com",
      "value": "k3x9a1c7e5b2d804.acme.kilby.neuramorphic.ai",
      "purpose": "certificate"
    }
  ],
  "verified_at": null,
  "certificate_expires_at": null,
  "certificate_validation": "http",
  "routed_at": null,
  "redirect_to": "example.com",
  "last_checked_at": null,
  "next_check_at": "2026-11-13T14:07:00Z",
  "created_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/services/{id}/primary-domain #

Choose the primary address

deploy Developer key or higher

Chooses the address a web service shows as its own: in the dashboard's header and Open, and as primary_domain in the API. Send the service's Kilby address, or one of its custom domains that is active, serves the service (it does not redirect) and points to Kilby. null removes the choice: the first custom domain to go live is primary, the Kilby address until then.

Nothing is deployed or restarted, and the variables Kilby sets do not change: KILBY_EXTERNAL_HOSTNAME and RENDER_EXTERNAL_HOSTNAME stay the Kilby address, and url stays the Kilby address too. If the chosen domain later stops being live, the Kilby address is reported instead, with the reason in primary_domain_note, until it is live again.

Path parameters

  • iduuidrequired
    The service's id.

Request body

  • primary_domainstring or nullrequired
    The Kilby address or a custom domain of the service, or null.

Response

200
The service.

Returns a Service object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    primary_domain is missing, is not an address of the service, or names a custom domain that is not live; or the service is not a web service.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/services/{id}/primary-domain
curl -X PATCH "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/primary-domain" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"primary_domain": "example.com"}'
{
  "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "name": "my-api",
  "type": "web",
  "image": "ghcr.io/acme/api:1.4",
  "port": 8080,
  "plan": "starter",
  "status": "live",
  "status_message": "",
  "suspended": false,
  "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai",
  "internal_address": "my-api:8080",
  "created_at": "2026-11-12T22:40:11Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "registry_credential_id": null,
  "health_check_path": "/healthz",
  "instances": 2,
  "autoscaling": {"min": 2, "max": 4, "target_cpu_percent": 70},
  "disk": null,
  "instances_running": 2,
  "instances_desired": 2,
  "pre_deploy_command": "",
  "pre_deploy_timeout_seconds": 600,
  "source": null,
  "environment": {
    "id": "9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
    "name": "Production",
    "default": true,
    "project": {"id": "2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", "name": "Default"}
  },
  "auto_concurrency": true,
  "render_compat": false,
  "stop_first": false,
  "read_only_root": false,
  "maintenance": false,
  "maintenance_message": "",
  "primary_domain": "example.com",
  "primary_domain_choice": "example.com"
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/domains/{id} #

Remove a domain

deploy Developer key or higher

Detaches the domain and stops serving it. Its certificate is removed. A domain that another one redirects to cannot be removed until that one serves the service again or is removed.

Path parameters

  • iduuidrequired
    The domain's id.

Response

202
The domain is being removed.
  • iduuidrequired
  • statusstringrequired
    Always deleting.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    Another domain redirects to this one.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/domains/{id}
curl -X DELETE "https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"id": "5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11", "status": "deleting"}
Runs in your browser against your workspace with a key you paste.

Workspaces

What the key's workspace holds, what it used, and which emails it sends.

GET/api/v1/workspace #

Get the workspace

view Any key

The workspace the key belongs to, how much of it is in use and its limits. Every key works in exactly one workspace, so this is also how you check which one a key is for.

Response

200
The workspace.
  • iduuidrequired
  • namestringrequired
  • planstring
    The workspace's plan: beta, hobby, pro, scale or enterprise. See Read the plan and the limits.

    One of beta, hobby, pro, scale, enterprise.

  • keyobjectrequired
    The API key that made this request. Never the key itself.
  • namestringrequired
    The name the key was given.
  • rolestringrequired
    What the key can do: developer or viewer.
  • servicesintegerrequired
    Services that are not cron jobs.
  • cron_jobsintegerrequired
  • databasesintegerrequired
  • postgres_versionsarray of stringrequired
    The Postgres major versions a new database can be created with, oldest first.
  • limitsobjectrequired
  • servicesintegerrequired
    Most services and cron jobs together.
  • cron_jobsintegerrequired
  • databasesintegerrequired
  • cpunumberrequired
    Cores across all running instances.
  • memory_gbnumberrequired
    GB across all running instances.
  • database_storage_gbintegerrequired
    The same as storage_gb. Kept for clients written before service disks.
  • storage_gbintegerrequired
    GB of databases and service disks together.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/workspace
curl "https://onkilby.com/api/v1/workspace" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3",
  "name": "Acme",
  "plan": "beta",
  "key": {"name": "ci", "role": "developer"},
  "services": 3,
  "cron_jobs": 1,
  "databases": 1,
  "postgres_versions": ["17", "18"],
  "limits": {
    "services": 5,
    "cron_jobs": 5,
    "databases": 2,
    "cpu": 2,
    "memory_gb": 4,
    "database_storage_gb": 50,
    "storage_gb": 50
  }
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/workspace/network #

Get the outbound IP addresses

view Any key

The IP addresses that connections from your services to the internet come from. Add them to the allow-list of a firewall or a database that your services call.

The addresses are shared. Every workspace on Kilby's infrastructure uses the same ones, so a system that allows them also allows every other Kilby customer, and a system that blocks or rate-limits them can do it to you for something another customer did. Use them as one layer, next to a password, a token or TLS client certificates, never as the only one. They can change if Kilby rebuilds its infrastructure; the list here is always the current one.

An empty outbound_ips means Kilby has not published the addresses for this installation yet. Your services still reach the internet; do not allow-list a guess.

Response

200
The addresses.
  • outbound_ipsarray of stringrequired
    IPv4 addresses, each one either a single address or a CIDR block (like 18.220.4.0/28), sorted. Empty while Kilby has not published them.
  • sharedbooleanrequired
    Always true today: the addresses are used by every workspace.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/workspace/network
curl "https://onkilby.com/api/v1/workspace/network" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"outbound_ips": ["3.23.67.240"], "shared": true}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/usage #

Read usage

view Any key

What the workspace used in a month, in total and per resource. Usage is measured every minute and summed per month, in UTC. instance_hours are the hours that are billed (the same instance time the invoice lines and the dashboard show; a pod that only ran next to its replacement during a deploy is not counted), and instance_seconds is the integer they come from. vCPU-hours and GB-hours are the CPU and memory of the instance type multiplied by the time it ran; the used_ figures are what was actually used, and are null until live metrics exist.

Query parameters

  • monthstring
    The month, as YYYY-MM. Not in the future.

    Default the current month.

Response

200
The month's usage.
  • monthstringrequired
  • fromdatetimerequired
  • todatetimerequired
  • totalsUsageFiguresrequired
  • instance_secondsintegerrequired
    Seconds instances ran that are billed, the integer behind instance_hours. The invoice, the Billing page and the Usage page show the same seconds.
  • instance_hoursnumberrequired
    Hours instances ran that are billed: instance_seconds divided by 3600, to four decimals. The dashboard writes it with two.
  • vcpu_hoursnumberrequired
    CPU of the instance type multiplied by the time it ran.
  • memory_gb_hoursnumberrequired
    Memory of the instance type multiplied by the time it ran.
  • disk_gb_monthsnumberrequired
  • used_vcpu_hoursnumber or nullrequired
    CPU actually used. null until live metrics exist.
  • used_memory_gb_hoursnumber or nullrequired
    Memory actually used. null until live metrics exist.
  • resourcesarray of UsageResourcerequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 422invalid_request

    month is not a month in the form YYYY-MM, or is in the future.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/usage
curl "https://onkilby.com/api/v1/usage?month=2026-11" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "month": "2026-11",
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-12-01T00:00:00Z",
  "totals": {
    "instance_seconds": 3317400,
    "instance_hours": 921.5,
    "vcpu_hours": 460.75,
    "memory_gb_hours": 460.75,
    "disk_gb_months": 2.1,
    "used_vcpu_hours": 31.2,
    "used_memory_gb_hours": 188.4
  },
  "resources": [
    {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "chat-app",
      "type": "service",
      "plan": "starter",
      "deleted": false,
      "instance_seconds": 1105920,
      "instance_hours": 307.2,
      "vcpu_hours": 153.6,
      "memory_gb_hours": 153.6,
      "disk_gb_months": 0,
      "used_vcpu_hours": 18.9,
      "used_memory_gb_hours": 61
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/notifications #

Get email notifications

view Any key

Which events Kilby emails to the members of the workspace. Emails go to every member. To receive events in your own systems, use webhooks instead.

Response

200
Per event type: true when it is emailed.
  • emailobject of booleanrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/notifications
curl "https://onkilby.com/api/v1/notifications" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "email": {
    "deploy.failed": true,
    "cron.run.failed": true,
    "service.suspended": true,
    "database.failed": true,
    "shell.opened": true
  }
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/notifications #

Change email notifications

workspace Admin key

Turns emails on or off per event type. Types you leave out keep their setting.

Also needs

An admin key, created by an admin or the owner of the workspace.

Request body

  • emailobject of booleanrequired
    Event type to on or off. Only the types listed by GET /notifications can be emailed.

Response

200
The settings now.
  • emailobject of booleanrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 422invalid_request

    A type cannot be emailed.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/notifications
curl -X PATCH "https://onkilby.com/api/v1/notifications" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": {"cron.run.failed": false}}'
{
  "email": {
    "deploy.failed": true,
    "cron.run.failed": false,
    "service.suspended": true,
    "database.failed": true,
    "shell.opened": true
  }
}
Runs in your browser against your workspace with a key you paste.

API keys

How keys work. Keys are created and revoked in the dashboard, never through the API: a key that could create keys would outlive its own revocation.

Create a key under API keys in the dashboard. Choose a name, a role and, if you want one, an expiry date: 30, 90 or 365 days, a date of your choosing, or never. Only admins and the owner of the workspace create and revoke keys, and they confirm with their password.

  • The key is shown once. Kilby keeps only a hash of it, so a lost key cannot be recovered: revoke it and create another.
  • The page lists each key's prefix (for example kby_ab12cd34), role, who created it, when it was last used and when it expires. Keys that are about to expire, or have not been used for 90 days, are flagged.
  • To rotate a key without downtime, create the new one, switch your systems to it, check that the old one shows no recent use, then revoke the old one.
  • Revoking is immediate. Creating, revoking and expiring a key are recorded in the workspace's Activity.

GitHub and Git

Deploy a repository instead of an image. Kilby connects to GitHub with its own GitHub App, so no token of yours is stored.

Deploy a repository

Instead of an image, send a source to Create a service: Kilby clones the repository, builds it in AWS CodeBuild, outside your cluster, and deploys the image it makes, again on every push to the branch that changes a file in the service's folder (root_dir) when auto_deploy is on. installation_id is the GitHub connection of this workspace that can read the repository. root_dir picks a folder in a monorepo; leave dockerfile_path empty and Kilby uses the Dockerfile it finds, or writes one for Node, Python and Go projects.

Look before you deploy: list the GitHub connections, pick a repository, and analyse it to see the plan Kilby would use. Send that plan back as source.build_plan to build exactly what you saw.

curl -X POST "https://onkilby.com/api/v1/services" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-api",
  "type": "web",
  "plan": "starter",
  "source": {
    "kind": "git",
    "installation_id": 4242,
    "repo": "acme/express-api",
    "branch": "main",
    "root_dir": "",
    "auto_deploy": true
  }
}'

The service starts with status building and source.latest_build holds the first build. A build goes through the stages clone, detect, build, push, release, health and live. When one fails, the build says why in diagnosis, with changes that may fix it. The deploy a build starts has the trigger git.

  • List and read builds with a key that may view; start, cancel and retry them with a key that may deploy; change build variables with a key that may see secrets.
  • A build that has released its image cannot be canceled: roll back instead.
  • A service built from Git runs what its builds produce, so its image cannot be edited; roll back to an earlier deploy to run an earlier build. Change where and how it builds with source in Change a service, and add "rebuild": true to build straight away.
GET/api/v1/git/installations #

List GitHub connections

view Any key

The GitHub accounts (people or organisations) connected to this workspace, and whether the Kilby GitHub App is set up on this server. Connect an account in the dashboard under Workspace settings, Git.

Response

200
The connections.
  • modestringrequired
    How GitHub is wired on this server.

    One of off, fake, live.

  • statestringrequired
    What GitHub can do here now: off (not turned on, or deploying from Git is off), needs_app (turned on, but a platform admin has not registered the GitHub App yet) or ready (accounts can be connected).

    One of off, needs_app, ready.

  • connectedbooleanrequired
    false until a platform admin has registered the GitHub App.
  • installationsarray of GitInstallationrequired
  • idintegerrequired
    Use it as installation_id and installation.
  • accountstringrequired
    The GitHub login.
  • typestringrequired

    One of User, Organization.

  • repository_selectionstringrequired
    Whether the GitHub App can read all of the account's repositories or only selected ones.

    One of all, selected.

  • suspendedbooleanrequired
    true while GitHub has suspended the installation.
  • linked_bystringrequired
    Who connected it to this workspace.
  • linked_atdatetimerequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/git/installations
curl "https://onkilby.com/api/v1/git/installations" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "mode": "live",
  "state": "ready",
  "connected": true,
  "installations": [
    {
      "id": 1001,
      "account": "acme",
      "type": "Organization",
      "repository_selection": "all",
      "suspended": false,
      "linked_by": "Ada Lovelace",
      "linked_at": "2026-11-13T14:05:00Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/git/repos #

List repositories

view Any key

The repositories Kilby can read through one connection, most recently pushed first, at most 100. The list is kept for 20 seconds.

Query parameters

  • installationintegerrequired
    The GitHub connection to read through: the id of an entry of List GitHub connections.
  • qstring
    Only repositories whose name contains this text.

Response

200
The repositories.
  • reposarray of GitReporequired
  • idintegerrequired
  • full_namestringrequired
    owner/name.
  • privatebooleanrequired
  • default_branchstringrequired
  • pushed_atdatetimerequired
    The latest push.
  • installation_idintegerrequired
  • ownerstringrequired
  • totalintegerrequired
    How many repositories the connection can read.
  • truncatedbooleanrequired
    true when there are more than were returned.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The connection is not connected to this workspace, or the repository or branch does not exist. GitHub is not called for a connection that is not yours.

  • 409not_connected

    GitHub is not turned on for this Kilby, or its App is not registered yet.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 502github_unavailable

    GitHub could not be reached or answered something Kilby could not read. Try again in a moment.

GEThttps://onkilby.com/api/v1/git/repos
curl "https://onkilby.com/api/v1/git/repos?installation=1001&q=api" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "repos": [
    {
      "id": 1000,
      "full_name": "acme/express-api",
      "private": true,
      "default_branch": "main",
      "pushed_at": "2026-11-13T14:05:00Z",
      "installation_id": 1001,
      "owner": "acme"
    }
  ],
  "total": 1,
  "truncated": false
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/git/branches #

List branches

view Any key

The branches of a repository, the default one first.

Query parameters

  • installationintegerrequired
    The GitHub connection to read through: the id of an entry of List GitHub connections.
  • repostringrequired
    The repository, written owner/name.

Response

200
The branches.
  • defaultstringrequired
    The default branch.
  • branchesarray of stringrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The connection is not connected to this workspace, or the repository or branch does not exist. GitHub is not called for a connection that is not yours.

  • 409not_connected

    GitHub is not turned on for this Kilby, or its App is not registered yet.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 502github_unavailable

    GitHub could not be reached or answered something Kilby could not read. Try again in a moment.

GEThttps://onkilby.com/api/v1/git/branches
curl "https://onkilby.com/api/v1/git/branches?installation=1001&repo=acme%2Fexpress-api" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"default": "main", "branches": ["main", "staging"]}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/git/commit #

Get the latest commit of a branch

view Any key

The commit a build of this branch would build now.

Query parameters

  • installationintegerrequired
    The GitHub connection to read through: the id of an entry of List GitHub connections.
  • repostringrequired
    The repository, written owner/name.
  • branchstringrequired
    The branch.

Response

200
The commit.
  • commitGitCommitrequired
  • shastringrequired
  • messagestringrequired
    The first line of the commit message.
  • authorstringrequired
  • urlurlrequired
    The commit on GitHub.
  • atdatetimerequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The connection is not connected to this workspace, or the repository or branch does not exist. GitHub is not called for a connection that is not yours.

  • 409not_connected

    GitHub is not turned on for this Kilby, or its App is not registered yet.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 502github_unavailable

    GitHub could not be reached or answered something Kilby could not read. Try again in a moment.

GEThttps://onkilby.com/api/v1/git/commit
curl "https://onkilby.com/api/v1/git/commit?branch=main&installation=1001&repo=acme%2Fexpress-api" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "commit": {
    "sha": "8a2e7d9a74a99a24383b37a774d17ddd931058c0",
    "message": "Bump express to 4.21",
    "author": "Dana Whitfield",
    "url": "https://github.com/acme/express-api/commit/8a2e7d9a74a99a24383b37a774d17ddd931058c0",
    "at": "2026-11-13T14:05:00Z"
  }
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/git/public/check #

Check a public repository

deploy Developer key or higher

Says whether a public repository exists and which commit its branch, tag or commit is at, with one archive request to the host that is cut after the first kilobytes: no GitHub connection and no credential is needed, and Kilby never calls the host's REST API (an address shared by every customer would use up its limit). The answer is kept for 60 seconds and shared by everyone who asks.

commit.known is false when the host's archive does not say which commit it is of; Kilby then shows the commit as unknown instead of inventing one. A private repository and one that does not exist look the same to a client with no credentials, so both answer not_found with the sentence that says so. A rate limit is never not_found. A person can ask 40 times a minute.

Query parameters

  • urlstringrequired
    The https address of a public repository on github.com, gitlab.com or bitbucket.org (the hosts this Kilby allows). A branch page such as https://github.com/acme/api/tree/main/apps/web also works.
  • refstring
    The branch, tag or full commit id. Empty is the repository's default branch.

Response

200
The repository exists and is public.
  • okbooleanrequired
    Always true.
  • hoststringrequired
    For example github.com.
  • repostringrequired
    The path on the host: owner/name, or group/subgroup/project on GitLab.
  • repo_urlurlrequired
    The repository's page.
  • refstringrequired
    The ref that was checked; HEAD is the default branch.
  • default_branchbooleanrequired
    The ref is the default branch.
  • rootstringrequired
    The folder a branch page's address named (https://github.com/acme/api/tree/main/apps/web), empty when it named none.
  • commitPublicCommitrequired
  • shastringrequired
    40 hex characters, or empty when the host's archive does not say.
  • shortstringrequired
    The first 7 characters.
  • knownbooleanrequired
    false when the archive does not say which commit it is of: Kilby shows it as unknown and cannot tell when it changes.
  • urlurlrequired
    The commit on the host's website. Empty when unknown.
  • howstring
    How Kilby learned the commit: the archive's header, or the archive's folder name. Left out when unknown.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no public repository at that address (or branch, tag or commit): to a client with no credentials a private repository and one that does not exist look the same, so the message only says that no public repository was found.

  • 409not_available

    Deploying from Git is not turned on for this Kilby yet, so nothing can be read.

  • 422invalid_request

    The address is not one Kilby accepts: another host, a port, a user name or password, an IP address, http, or something that is not a repository.

  • 429rate_limited

    The host asked Kilby to slow down, or Kilby's own limits for that host are used up. It is never reported as not_found. retry_after and the Retry-After header say how many seconds to wait.

  • 502host_unavailable

    The Git host did not answer or answered with an error. Try again in a few minutes.

GEThttps://onkilby.com/api/v1/git/public/check
curl "https://onkilby.com/api/v1/git/public/check?ref=main&url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "ok": true,
  "host": "github.com",
  "repo": "acme/express-api",
  "repo_url": "https://github.com/acme/express-api",
  "ref": "main",
  "default_branch": false,
  "root": "",
  "commit": {
    "sha": "8a2e7d9a74a99a24383b37a774d17ddd931058c0",
    "short": "8a2e7d9",
    "known": true,
    "url": "https://github.com/acme/express-api/commit/8a2e7d9a74a99a24383b37a774d17ddd931058c0"
  }
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/git/public/plan #

Analyse a public repository

deploy Developer key or higher

Downloads a public repository's archive and answers what Kilby understood, exactly as Analyse a repository does for a repository on GitHub: the runtime, the commands, the port, the variables the code reads and the other folders of a monorepo. Send the plan back unchanged as source.build_plan when you create the service.

The archive is read in memory under the same limits as a build's (size, number of files, links and paths); an archive that a build would refuse is refused here, with error.code archive_refused or too_large. An answer is kept for 60 seconds, and a person can ask for 10 new analyses a minute.

Query parameters

  • urlstringrequired
    The https address of a public repository on github.com, gitlab.com or bitbucket.org (the hosts this Kilby allows). A branch page such as https://github.com/acme/api/tree/main/apps/web also works.
  • refstring
    The branch, tag or full commit id. Empty is the repository's default branch.
  • rootstring
    The folder to analyse, for a monorepo. Empty is the repository root.

Response

200
The plan, and why it cannot be built when it cannot.
  • planBuildPlanrequired
  • root_dirstringrequired
    The folder that is built. Empty is the repository root.
  • strategystringrequired
    Whether Kilby builds your Dockerfile or writes one.

    One of dockerfile, generated.

  • runtimestringrequired

    One of node, python, go, static, docker.

  • frameworkstringrequired
    For example next, vite, express, fastapi or flask. Empty when none was recognised.
  • dockerfile_pathstringrequired
    Only for strategy dockerfile, relative to root_dir.
  • install_commandstringrequired
  • build_commandstringrequired
  • start_commandstringrequired
  • portintegerrequired
    0 for a worker.
  • health_pathstringrequired
    Empty when there is no good guess.
  • plan_idstringrequired
    The instance type Kilby suggests.

    One of starter, standard, pro.

  • envarray of objectrequired
    Variables the code reads, found in files such as .env.example.
  • notesarray of stringrequired
    What was found and why, in plain sentences.
  • warningsarray of stringrequired
    What might go wrong.
  • candidatesarray of objectrequired
    Other buildable folders, in a monorepo.
  • kindstring
    A suggestion for the service type.

    One of web, worker.

  • versionstring
    The runtime version the image uses.
  • package_managerstring
    For example npm, pnpm, pip or uv.
  • output_dirstring
    The folder that holds the build output.
  • root_routeboolean
    The code routes /, and no health route was found: the dashboard offers / as the health check. Only present when true.
  • errorobject or nullrequired
    null when the folder can be built.
  • codestringrequired
    A stable name, such as nothing_to_build, empty_repo, monorepo_root, too_large or archive_refused.
  • messagestringrequired
  • sourcestringrequired
    Always public_git.
  • hoststringrequired
  • repostringrequired
  • repo_urlurlrequired
  • refstringrequired
  • default_branchbooleanrequired
  • commitPublicCommitrequired
    The commit the archive is of.
  • shastringrequired
    40 hex characters, or empty when the host's archive does not say.
  • shortstringrequired
    The first 7 characters.
  • knownbooleanrequired
    false when the archive does not say which commit it is of: Kilby shows it as unknown and cannot tell when it changes.
  • urlurlrequired
    The commit on the host's website. Empty when unknown.
  • howstring
    How Kilby learned the commit: the archive's header, or the archive's folder name. Left out when unknown.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no public repository at that address (or branch, tag or commit): to a client with no credentials a private repository and one that does not exist look the same, so the message only says that no public repository was found.

  • 409not_available

    Deploying from Git is not turned on for this Kilby yet, so nothing can be read.

  • 422invalid_request

    The address is not one Kilby accepts: another host, a port, a user name or password, an IP address, http, or something that is not a repository.

  • 429rate_limited

    The host asked Kilby to slow down, or Kilby's own limits for that host are used up. It is never reported as not_found. retry_after and the Retry-After header say how many seconds to wait.

  • 502host_unavailable

    The Git host did not answer or answered with an error. Try again in a few minutes.

GEThttps://onkilby.com/api/v1/git/public/plan
curl "https://onkilby.com/api/v1/git/public/plan?ref=main&url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "plan": {
    "root_dir": "",
    "strategy": "generated",
    "runtime": "node",
    "framework": "express",
    "dockerfile_path": "",
    "install_command": "npm install",
    "build_command": "",
    "start_command": "npm start",
    "port": 3000,
    "health_path": "/healthz",
    "plan_id": "starter",
    "env": [
      {"name": "DATABASE_URL", "example": "", "secret": true},
      {"name": "LOG_LEVEL", "example": "info", "secret": false}
    ],
    "notes": ["We found an Express app and will build it with npm."],
    "warnings": ["No lockfile found: builds may not be reproducible."],
    "candidates": [],
    "kind": "web",
    "version": "22",
    "package_manager": "npm"
  },
  "error": null,
  "source": "public_git",
  "host": "github.com",
  "repo": "acme/express-api",
  "repo_url": "https://github.com/acme/express-api",
  "ref": "main",
  "default_branch": false,
  "commit": {
    "sha": "8a2e7d9a74a99a24383b37a774d17ddd931058c0",
    "short": "8a2e7d9",
    "known": true,
    "url": "https://github.com/acme/express-api/commit/8a2e7d9a74a99a24383b37a774d17ddd931058c0"
  }
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/git/plan #

Analyse a repository

deploy Developer key or higher

Reads a repository at the latest commit of a branch and answers what Kilby understood: the runtime, the commands, the port, the variables the code reads and, in a monorepo, the other folders that could be built. Send the plan back unchanged as source.build_plan when you create the service, to build exactly what you saw.

When the folder holds nothing Kilby can build, the status is still 200: error says why in plain English and plan.candidates offers other folders. An answer is kept for 60 seconds per commit and folder, and a person can ask for 20 new analyses a minute.

Query parameters

  • installationintegerrequired
    The GitHub connection to read through: the id of an entry of List GitHub connections.
  • repostringrequired
    The repository, written owner/name.
  • branchstring
    The branch to analyse.

    Default the repository's default branch.

  • rootstring
    The folder to analyse, for a monorepo. Empty is the repository root.

Response

200
The plan, and why it cannot be built when it cannot.
  • planBuildPlanrequired
  • root_dirstringrequired
    The folder that is built. Empty is the repository root.
  • strategystringrequired
    Whether Kilby builds your Dockerfile or writes one.

    One of dockerfile, generated.

  • runtimestringrequired

    One of node, python, go, static, docker.

  • frameworkstringrequired
    For example next, vite, express, fastapi or flask. Empty when none was recognised.
  • dockerfile_pathstringrequired
    Only for strategy dockerfile, relative to root_dir.
  • install_commandstringrequired
  • build_commandstringrequired
  • start_commandstringrequired
  • portintegerrequired
    0 for a worker.
  • health_pathstringrequired
    Empty when there is no good guess.
  • plan_idstringrequired
    The instance type Kilby suggests.

    One of starter, standard, pro.

  • envarray of objectrequired
    Variables the code reads, found in files such as .env.example.
  • notesarray of stringrequired
    What was found and why, in plain sentences.
  • warningsarray of stringrequired
    What might go wrong.
  • candidatesarray of objectrequired
    Other buildable folders, in a monorepo.
  • kindstring
    A suggestion for the service type.

    One of web, worker.

  • versionstring
    The runtime version the image uses.
  • package_managerstring
    For example npm, pnpm, pip or uv.
  • output_dirstring
    The folder that holds the build output.
  • root_routeboolean
    The code routes /, and no health route was found: the dashboard offers / as the health check. Only present when true.
  • errorobject or nullrequired
    null when the folder can be built.
  • codestringrequired
    A stable name, such as nothing_to_build, empty_repo, folder_not_found, unsupported_runtime, monorepo_root or invalid_manifest.
  • messagestringrequired
  • commitGitCommitrequired
    The commit that was read.
  • shastringrequired
  • messagestringrequired
    The first line of the commit message.
  • authorstringrequired
  • urlurlrequired
    The commit on GitHub.
  • atdatetimerequired
  • repostringrequired
    owner/name.
  • branchstringrequired
    The branch that was read.
  • repo_urlurlrequired
    The repository on GitHub.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The connection is not connected to this workspace, or the repository or branch does not exist. GitHub is not called for a connection that is not yours.

  • 409not_connected

    GitHub is not turned on for this Kilby, or its App is not registered yet.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 20 analyses a minute for this person. The Retry-After header says how long to wait.

  • 502github_unavailable

    GitHub could not be reached or answered something Kilby could not read. Try again in a moment.

GEThttps://onkilby.com/api/v1/git/plan
curl "https://onkilby.com/api/v1/git/plan?branch=main&installation=1001&repo=acme%2Fexpress-api" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "plan": {
    "root_dir": "",
    "strategy": "generated",
    "runtime": "node",
    "framework": "express",
    "dockerfile_path": "",
    "install_command": "npm install",
    "build_command": "",
    "start_command": "npm start",
    "port": 3000,
    "health_path": "/healthz",
    "plan_id": "starter",
    "env": [
      {"name": "DATABASE_URL", "example": "", "secret": true},
      {"name": "LOG_LEVEL", "example": "info", "secret": false}
    ],
    "notes": ["We found an Express app and will build it with npm."],
    "warnings": ["No lockfile found: builds may not be reproducible."],
    "candidates": [],
    "kind": "web",
    "version": "22",
    "package_manager": "npm"
  },
  "error": null,
  "commit": {
    "sha": "8a2e7d9a74a99a24383b37a774d17ddd931058c0",
    "message": "Bump express to 4.21",
    "author": "Dana Whitfield",
    "url": "https://github.com/acme/express-api/commit/8a2e7d9a74a99a24383b37a774d17ddd931058c0",
    "at": "2026-11-13T14:05:00Z"
  },
  "repo": "acme/express-api",
  "branch": "main",
  "repo_url": "https://github.com/acme/express-api"
}
Runs in your browser against your workspace with a key you paste.

Blueprints

A blueprint is a file in your repository that describes a whole stack: services, databases, cron jobs, domains and variables. Kilby shows what applying it would do, applies it, and keeps it in sync on every push. The file format is documented in the dashboard under Blueprints, Reference.

POST/api/v1/blueprints/plan #

Plan a blueprint

deploy Developer key or higher

Reads a blueprint file and says exactly what applying it would do, without doing anything: what is created, changed and deleted, the cost at list prices, the variables you still have to enter, and every problem found with its line and column. Send either repo (read through a connection of the workspace) or the raw yaml; a Render render.yaml is converted. The plan is kept for 24 hours and no secret value is ever in it. Reading a repository needs deploy, so a read-only key cannot plan.

Request body Send `repo` or `yaml`, not both.

  • repostring
    The repository, written owner/name.
  • branchstring

    Default the repository's default branch.

  • pathstring
    The file in the repository.

    Default kilby.yaml.

  • installation_idinteger
    The GitHub connection; found among the workspace's own when left out.
  • adoptarray of string
    Existing resources to take under management, written service api or database main.
  • yamlstring
    The file itself instead of repo.

    up to 256 KB.

Response

200
The plan.
  • idstringrequired
    Use it as plan_id to create the blueprint.
  • expires_atdatetimerequired
  • commitobject
    The commit the file was read at.
  • planobjectrequired
    name, valid, counts, resources (each with action: create, update, unchanged, delete or blocked, and its field diffs), inputs, cost, usage and findings.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 422invalid_request

    The file could not be read, is over 256 KB, or the repository is not reachable.

  • 429rate_limited

    Too many plans in a short time.

POSThttps://onkilby.com/api/v1/blueprints/plan
curl -X POST "https://onkilby.com/api/v1/blueprints/plan" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repo": "acme/monorepo", "branch": "main", "path": "kilby.yaml"}'
{
  "id": "@plan",
  "expires_at": "2026-11-13T14:05:00Z",
  "commit": {
    "sha": "f32ca27a9d1b4c0e8d5a7b6c3e2f1a09b8c7d6e5",
    "message": "Add a worker",
    "author": "Ada Lovelace"
  },
  "plan": {
    "name": "acme-platform",
    "valid": true,
    "counts": {
      "Create": 3,
      "Update": 0,
      "Unchanged": 0,
      "Delete": 0,
      "Blocked": 0,
      "NeedsApproval": 0
    },
    "resources": [
      {
        "ref": {"kind": "service", "name": "web"},
        "action": "create",
        "monthly_usd": 9
      }
    ],
    "inputs": [
      {"resource": "web", "key": "STRIPE_KEY", "set": false}
    ],
    "cost": {"monthly_usd": 32.3, "max_monthly_usd": 32.3},
    "findings": []
  }
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/blueprints #

Create a blueprint

deploy Developer key or higher

Applies a plan: creates the databases and services it lists, queues the first build of each Git service and keeps the blueprint in sync with the repository from then on. The plan is made again first; if the workspace changed since, nothing happens and the answer is 409 plan_changed. The call returns at once with status: applying: poll Read a blueprint until status is in_sync, failed or waiting_approval. The key needs both deploy and secrets, because a blueprint sets variables.

Also needs

deploy and secrets

Request body

  • plan_idstringrequired
    The id of a plan from Plan a blueprint.
  • inputsobject of object
    The values of the sync: false variables, by service name. They go to that service's encrypted variables and nowhere else.
  • build_inputsobject of object
    The same for build variables.

Response

202
The blueprint, applying in the background.
  • iduuidrequired
  • namestringrequired
  • statusstringrequired
    Where the blueprint stands.

    One of new, in_sync, changes_pending, waiting_approval, failed, applying.

  • status_messagestring
    Why it failed or what it waits for.
  • repositorystringrequired
  • branchstringrequired
  • pathstringrequired
    The file in the repository.
  • auto_syncbooleanrequired
    Whether a push that changes the file is applied without asking, when the changes are safe.
  • commitstring
    The commit whose file was last applied.
  • last_sync_atdatetime
  • created_atdatetimerequired
  • resourcesarray of objectrequired
    What the blueprint manages: kind (service or database), name, id, status (created, creating, failed or deleting) and error.
  • pending_changesarray of object
    Only when you read one blueprint: changes waiting for approval, with kind, name, action, fields, needs_approval and reason.
  • driftarray of object
    Only when you read one blueprint: managed fields changed by hand since the last sync, with kind, name, field, applied and live.
  • inputs_neededarray of object
    Only when you read one blueprint: sync: false variables nobody has entered yet, with service and key.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The plan is unknown, expired or belongs to another workspace.

  • 409plan_changed

    The workspace changed since the plan: make a new one and look at it.

  • 422invalid_request

    The plan is invalid or has blocked resources.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/blueprints
curl -X POST "https://onkilby.com/api/v1/blueprints" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": "@plan", "inputs": {"web": {"STRIPE_KEY": "your-key"}}}'
{
  "id": "@blueprint",
  "name": "acme-platform",
  "status": "applying",
  "status_message": "",
  "repository": "acme/monorepo",
  "branch": "main",
  "path": "kilby.yaml",
  "auto_sync": true,
  "commit": "f32ca27a9d1b4c0e8d5a7b6c3e2f1a09b8c7d6e5",
  "last_sync_at": "2026-11-13T14:05:00Z",
  "created_at": "2026-11-13T14:05:00Z",
  "resources": [
    {
      "kind": "database",
      "name": "main",
      "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
      "status": "created",
      "error": ""
    },
    {
      "kind": "service",
      "name": "web",
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "status": "created",
      "error": ""
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/blueprints #

List blueprints

view Any key

The workspace's blueprints with their status.

Response

200
The blueprints.
  • blueprintsarray of objectrequired
    Each shaped like Read a blueprint, without its last three fields.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/blueprints
curl "https://onkilby.com/api/v1/blueprints" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "blueprints": [
    {
      "id": "@blueprint",
      "name": "acme-platform",
      "status": "in_sync",
      "status_message": "",
      "repository": "acme/monorepo",
      "branch": "main",
      "path": "kilby.yaml",
      "auto_sync": true,
      "commit": "f32ca27a9d1b4c0e8d5a7b6c3e2f1a09b8c7d6e5",
      "last_sync_at": "2026-11-13T14:05:00Z",
      "created_at": "2026-11-13T14:05:00Z",
      "resources": [
        {
          "kind": "database",
          "name": "main",
          "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
          "status": "created",
          "error": ""
        },
        {
          "kind": "service",
          "name": "web",
          "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
          "status": "created",
          "error": ""
        }
      ]
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/blueprints/{id} #

Read a blueprint

view Any key

One blueprint with its resources, the changes waiting for approval, what was changed by hand since the last sync (drift) and the variables still to enter.

Path parameters

  • iduuidrequired
    The blueprint's id.

Response

200
The blueprint.
  • iduuidrequired
  • namestringrequired
  • statusstringrequired
    Where the blueprint stands.

    One of new, in_sync, changes_pending, waiting_approval, failed, applying.

  • status_messagestring
    Why it failed or what it waits for.
  • repositorystringrequired
  • branchstringrequired
  • pathstringrequired
    The file in the repository.
  • auto_syncbooleanrequired
    Whether a push that changes the file is applied without asking, when the changes are safe.
  • commitstring
    The commit whose file was last applied.
  • last_sync_atdatetime
  • created_atdatetimerequired
  • resourcesarray of objectrequired
    What the blueprint manages: kind (service or database), name, id, status (created, creating, failed or deleting) and error.
  • pending_changesarray of object
    Only when you read one blueprint: changes waiting for approval, with kind, name, action, fields, needs_approval and reason.
  • driftarray of object
    Only when you read one blueprint: managed fields changed by hand since the last sync, with kind, name, field, applied and live.
  • inputs_neededarray of object
    Only when you read one blueprint: sync: false variables nobody has entered yet, with service and key.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/blueprints/{id}
curl "https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "@blueprint",
  "name": "acme-platform",
  "status": "in_sync",
  "status_message": "",
  "repository": "acme/monorepo",
  "branch": "main",
  "path": "kilby.yaml",
  "auto_sync": true,
  "commit": "f32ca27a9d1b4c0e8d5a7b6c3e2f1a09b8c7d6e5",
  "last_sync_at": "2026-11-13T14:05:00Z",
  "created_at": "2026-11-13T14:05:00Z",
  "pending_changes": [],
  "drift": [],
  "inputs_needed": [],
  "resources": [
    {
      "kind": "database",
      "name": "main",
      "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
      "status": "created",
      "error": ""
    },
    {
      "kind": "service",
      "name": "web",
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "status": "created",
      "error": ""
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/blueprints/{id}/sync #

Sync a blueprint now

deploy Developer key or higher

Reads the file again and applies what changed, as a push to the branch would. Deletions and risky changes wait for approval. The key needs both deploy and secrets, because a blueprint sets variables.

Also needs

deploy and secrets

Path parameters

  • iduuidrequired
    The blueprint's id.

Response

202
Syncing in the background.
  • iduuidrequired
  • statusstringrequired
    applying.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/blueprints/{id}/sync
curl -X POST "https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/sync" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"id": "@blueprint", "status": "applying"}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/blueprints/{id}/approve #

Approve a sync

deploy Developer key or higher

Applies a sync that was waiting for approval. Deletions and risky changes are applied only by this call or by a person in the dashboard. The key needs both deploy and secrets, because a blueprint sets variables.

Also needs

deploy and secrets

Path parameters

  • iduuidrequired
    The blueprint's id.

Request body

  • sync_idstringrequired
    The id of a sync whose status is waiting_approval.

Response

202
Applying in the background.
  • iduuidrequired
  • statusstringrequired
    applying.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The sync is not waiting any more: it was approved, rejected or replaced by a newer file.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/blueprints/{id}/approve
curl -X POST "https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/approve" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sync_id": "@sync"}'
{"id": "@blueprint", "status": "applying"}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/blueprints/{id}/syncs #

List the syncs of a blueprint

view Any key

What each sync did, newest first: its trigger (create, push, manual, approval or retry), its status (applied, partial, failed, applying, waiting_approval, planned, skipped, rejected or superseded), the commit and the result of every resource.

Path parameters

  • iduuidrequired
    The blueprint's id.

Query parameters

  • limitinteger
    How many syncs.

    1 to 100.

  • beforestring
    Pass next_before of the previous answer to read older syncs.

Response

200
The syncs.
  • syncsarray of objectrequired
  • next_beforestring
    Present when there are older syncs.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/blueprints/{id}/syncs
curl "https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/syncs" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "syncs": [
    {
      "id": "@sync",
      "number": 2,
      "trigger": "push",
      "status": "applied",
      "commit": "f32ca27a9d1b4c0e8d5a7b6c3e2f1a09b8c7d6e5",
      "message": "Add a worker",
      "counts": {"Create": 1},
      "results": [
        {
          "kind": "service",
          "name": "worker",
          "action": "create",
          "status": "created",
          "message": "",
          "notes": []
        }
      ],
      "error": "",
      "approved_by": "",
      "created_at": "2026-11-13T14:05:00Z",
      "finished_at": "2026-11-13T14:05:00Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.

Billing and pricing

Plans, limits and the price list. A key reads what the workspace's plan allows and what it holds; money (the estimate and the invoices) is for owners and admins in the dashboard, never for a key.

GET/api/v1/pricing #

Read the price list

No API key

The plans and the list prices, for a website or a calculator. Public: it needs no key, answers with Access-Control-Allow-Origin: * and may be cached for five minutes. Every plan pays the same list prices; the plan sets the monthly fee, the limits and what is included.

Response

200
The price list.
  • currencystringrequired
    Always usd.
  • billingobjectrequired
    How the numbers are worked out.
  • livebooleanrequired
    true only when the platform bills real money. While false, nothing is charged.
  • periodstringrequired
  • prorationstringrequired
  • roundingstringrequired
  • minimum_charge_centsintegerrequired
    An invoice below this is not charged.
  • bandwidth_meteredbooleanrequired
    Whether outbound bandwidth is measured on this Kilby. While false it is not charged.
  • bandwidth_billed_fromstring or nullrequired
    The first day (YYYY-MM-DD) whose outbound bandwidth is billed, beyond what each plan includes: at least 30 days after customers were told. null: not billed.
  • tiersarray of objectrequired
    Hobby, Pro, Scale and Enterprise, each shaped like plan in Read the plan and the limits.
  • instancesarray of objectrequired
    The instance types.
  • pricesobjectrequired
    The other list prices, in US cents.

Errors

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/pricing
curl "https://onkilby.com/api/v1/pricing"
{
  "currency": "usd",
  "billing": {
    "live": false,
    "period": "calendar month, UTC",
    "proration": "by the second",
    "rounding": "half up, once per invoice line",
    "minimum_charge_cents": 100,
    "bandwidth_metered": true,
    "bandwidth_billed_from": null
  },
  "tiers": [
    {
      "id": "pro",
      "name": "Pro",
      "summary": "For a team shipping a product. Unlimited members.",
      "fee_cents": 2500,
      "contact_us": false,
      "support": "Email",
      "limits": {
        "services": 25,
        "cron_jobs": 25,
        "databases": 10,
        "cpu": 16,
        "memory_gb": 32,
        "storage_gb": 500,
        "members": 0,
        "custom_domains": 20,
        "included_build_minutes": 500,
        "included_bandwidth_gb": 25
      }
    }
  ],
  "instances": [
    {
      "id": "starter",
      "name": "Starter",
      "cpu": 0.5,
      "memory_gb": 0.5,
      "service_cents_per_month": 900,
      "postgres_cents_per_month": 1400
    }
  ],
  "prices": {
    "disk_cents_per_gb_month": 25,
    "postgres_storage_cents_per_gb_month": 30,
    "build_cents_per_minute": 1,
    "cron_minimum_cents_per_month": 100,
    "bandwidth_cents_per_gb": 15
  }
}
Runs in your browser against this server.
GET/api/v1/billing #

Read the plan and the limits

view Any key

The plan of the key's workspace, its limits and what it holds now, and this month's build minutes. A key never sees money: the estimate and the invoices are for the owners and admins in the dashboard. While billing is off, mode is off, the plan is beta and the limits are the beta's.

Response

200
The plan.
  • modestringrequired
    How the platform bills.

    One of off, fake, stripe.

  • billedbooleanrequired
    false in the beta and while billing is off.
  • planobjectrequired
    The workspace's plan.
  • idstringrequired
    hobby, pro, scale, enterprise or beta.

    One of beta, hobby, pro, scale, enterprise.

  • namestringrequired
  • summarystring
    One line about who the plan is for.
  • fee_centsintegerrequired
    The monthly fee of the workspace, in US cents. 0 for Hobby and the beta.
  • contact_usboolean
    true for Enterprise: the fee and limits are agreed with Kilby.
  • supportstring
  • limitsobjectrequired
    What the plan allows. members: 0 means unlimited.
  • statusstringrequired
    grace while a payment is overdue; suspended when services were suspended for it.

    One of ok, grace, suspended.

  • limitsobjectrequired
    The limits that apply now.
  • servicesintegerrequired
  • cron_jobsintegerrequired
  • databasesintegerrequired
  • cpunumberrequired
  • memory_gbnumberrequired
  • storage_gbintegerrequired
  • membersintegerrequired
  • custom_domainsintegerrequired
  • included_build_minutesintegerrequired
  • included_bandwidth_gbintegerrequired
  • usageobjectrequired
    What the workspace holds now.
  • servicesintegerrequired
  • cron_jobsintegerrequired
  • databasesintegerrequired
  • cpunumberrequired
  • memory_gbnumberrequired
  • storage_gbintegerrequired
  • membersintegerrequired
  • monthobjectrequired
    The current month, UTC.
  • startdatetimerequired
  • enddatetimerequired
  • build_minutes_usedintegerrequired
  • bandwidth_meteredbooleanrequired
    Whether outbound bandwidth is measured on this Kilby.
  • bandwidth_bytesinteger
    What the workspace's web services sent this month so far, in bytes. Only when bandwidth_metered.
  • bandwidth_billed_fromstring or null
    The first day (YYYY-MM-DD) whose outbound bandwidth is billed; null: not billed. Only when bandwidth_metered.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/billing
curl "https://onkilby.com/api/v1/billing" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "mode": "off",
  "billed": false,
  "plan": {
    "id": "beta",
    "name": "Beta",
    "summary": "Free during the beta.",
    "fee_cents": 0,
    "contact_us": false,
    "support": "Email",
    "limits": {
      "services": 5,
      "cron_jobs": 5,
      "databases": 2,
      "cpu": 2,
      "memory_gb": 4,
      "storage_gb": 50,
      "members": 0,
      "custom_domains": 20,
      "included_build_minutes": 500,
      "included_bandwidth_gb": 25
    }
  },
  "status": "ok",
  "limits": {
    "services": 5,
    "cron_jobs": 5,
    "databases": 2,
    "cpu": 2,
    "memory_gb": 4,
    "storage_gb": 50,
    "members": 0,
    "custom_domains": 20,
    "included_build_minutes": 500,
    "included_bandwidth_gb": 25
  },
  "usage": {
    "services": 3,
    "cron_jobs": 1,
    "databases": 1,
    "cpu": 1.5,
    "memory_gb": 3,
    "storage_gb": 10,
    "members": 2
  },
  "month": {
    "start": "2026-11-01T00:00:00Z",
    "end": "2026-12-01T00:00:00Z",
    "build_minutes_used": 42,
    "bandwidth_metered": true,
    "bandwidth_bytes": 1234567890,
    "bandwidth_billed_from": null
  }
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/billing/invoices #

List invoices

workspace Admin key

Invoices are for the owners and admins of the workspace, who read them in the dashboard. An API key cannot read them, whatever its role (keys live in CI systems and scripts and leak more easily than a person's session), so this always answers 403 to a key. It exists so that a client gets a clear answer.

Query parameters

  • limitinteger
    How many invoices.

    Default 12.

    1 to 60.

Response

200
The invoices.
  • invoicesarray of objectrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    Invoices are for the owner and admins of the workspace; an API key cannot read them.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/billing/invoices
curl "https://onkilby.com/api/v1/billing/invoices" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "invoices": [
    {
      "id": "@invoice",
      "number": "KB-202610-00002",
      "period": "2026-10",
      "status": "paid",
      "status_label": "Paid",
      "total_cents": 11156,
      "paid_cents": 11156,
      "refunded_cents": 0,
      "issued_at": "2026-11-13T14:05:00Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.

Kilby AI

Kilby AI explains a failed build or deploy in plain language and proposes fixes. It is off until the workspace turns it on, it removes secrets before anything is sent, and it only proposes: it never changes anything for you.

POST/api/v1/services/{id}/builds/{build}/analyze #

Explain a failed build

deploy Developer key or higher

Asks Kilby AI to read the end of a failed build's log (with every secret removed) and explain what went wrong. The answer takes about ten to forty seconds: the call returns 202 with status: queued and a Location to poll with Read the analysis of a build. When an answer already exists it returns 200 with it. The text is written by a model and can be wrong, so escape it when you show it and never run it.

Path parameters

  • iduuidrequired
    The service's id.
  • buildstringrequired
    A build's id, or its number within the service (1, 2, 3).

Response

202
Queued. Poll the analysis.
  • statusstringrequired
    none when nothing was asked yet.

    One of none, queued, running, done, failed.

  • enabledbooleanrequired
    Whether the workspace has turned Kilby AI on.
  • availablebooleanrequired
    Whether Kilby AI is configured on this server.
  • iduuid
    The analysis.
  • depthstring
    fast is the quick model; deep is the thorough one.

    One of fast, deep.

  • triggerstring
    auto when Kilby asked because no rule recognised the failure, manual when a person did.

    One of auto, manual.

  • created_atdatetime
  • finished_atdatetime
  • prompt_versionstring
  • analysisobject
    The explanation, once status is done.
  • titlestringrequired
    One sentence: what went wrong.
  • causestringrequired
    Why, in a few sentences.
  • confidencenumberrequired
    How sure the model says it is, 0 to 1.
  • stepsarray of stringrequired
    What to check.
  • fixesarray of objectrequired
    Proposed changes. Kilby checked each one the way it checks a change you make by hand, and never applies one for you. field is one of root_dir, dockerfile_path, install_command, build_command, start_command, port, plan or env (for env, value is a variable name, never a value).
  • droppedarray of stringrequired
    Proposals Kilby removed because they did not pass its checks.
  • errorobject
    Why an analysis failed.
  • codestringrequired
  • messagestringrequired
  • generated_bystringrequired
    Always ai: show it to people.
  • noticestringrequired
    Text to show beside the analysis.
200
An answer already exists.
  • statusstringrequired
    none when nothing was asked yet.

    One of none, queued, running, done, failed.

  • enabledbooleanrequired
    Whether the workspace has turned Kilby AI on.
  • availablebooleanrequired
    Whether Kilby AI is configured on this server.
  • iduuid
    The analysis.
  • depthstring
    fast is the quick model; deep is the thorough one.

    One of fast, deep.

  • triggerstring
    auto when Kilby asked because no rule recognised the failure, manual when a person did.

    One of auto, manual.

  • created_atdatetime
  • finished_atdatetime
  • prompt_versionstring
  • analysisobject
    The explanation, once status is done.
  • titlestringrequired
    One sentence: what went wrong.
  • causestringrequired
    Why, in a few sentences.
  • confidencenumberrequired
    How sure the model says it is, 0 to 1.
  • stepsarray of stringrequired
    What to check.
  • fixesarray of objectrequired
    Proposed changes. Kilby checked each one the way it checks a change you make by hand, and never applies one for you. field is one of root_dir, dockerfile_path, install_command, build_command, start_command, port, plan or env (for env, value is a variable name, never a value).
  • droppedarray of stringrequired
    Proposals Kilby removed because they did not pass its checks.
  • errorobject
    Why an analysis failed.
  • codestringrequired
  • messagestringrequired
  • generated_bystringrequired
    Always ai: show it to people.
  • noticestringrequired
    Text to show beside the analysis.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403ai_disabled

    The workspace has not turned Kilby AI on (Workspace settings, Kilby AI), or a platform admin has paused it.

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The build or deploy did not fail, so there is nothing to explain.

  • 429ai_budget

    The workspace or the platform reached its daily allowance, or ai_busy: too many analyses are running. Both send Retry-After.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/services/{id}/builds/{build}/analyze
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analyze" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "status": "queued",
  "enabled": true,
  "available": true,
  "id": "@analysis",
  "trigger": "manual",
  "created_at": "2026-11-13T14:05:00Z",
  "generated_by": "ai",
  "notice": "Written by an AI model from a copy of the log with secrets removed. It can be wrong: check it before you change anything."
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/builds/{build}/analysis #

Read the analysis of a build

view Any key

The analysis of a build, or status: none when nobody asked and none was queued automatically. Poll every few seconds while status is queued or running. The text is written by a model and can be wrong, so escape it when you show it and never run it.

Path parameters

  • iduuidrequired
    The service's id.
  • buildstringrequired
    A build's id, or its number within the service (1, 2, 3).

Response

200
The analysis.
  • statusstringrequired
    none when nothing was asked yet.

    One of none, queued, running, done, failed.

  • enabledbooleanrequired
    Whether the workspace has turned Kilby AI on.
  • availablebooleanrequired
    Whether Kilby AI is configured on this server.
  • iduuid
    The analysis.
  • depthstring
    fast is the quick model; deep is the thorough one.

    One of fast, deep.

  • triggerstring
    auto when Kilby asked because no rule recognised the failure, manual when a person did.

    One of auto, manual.

  • created_atdatetime
  • finished_atdatetime
  • prompt_versionstring
  • analysisobject
    The explanation, once status is done.
  • titlestringrequired
    One sentence: what went wrong.
  • causestringrequired
    Why, in a few sentences.
  • confidencenumberrequired
    How sure the model says it is, 0 to 1.
  • stepsarray of stringrequired
    What to check.
  • fixesarray of objectrequired
    Proposed changes. Kilby checked each one the way it checks a change you make by hand, and never applies one for you. field is one of root_dir, dockerfile_path, install_command, build_command, start_command, port, plan or env (for env, value is a variable name, never a value).
  • droppedarray of stringrequired
    Proposals Kilby removed because they did not pass its checks.
  • errorobject
    Why an analysis failed.
  • codestringrequired
  • messagestringrequired
  • generated_bystringrequired
    Always ai: show it to people.
  • noticestringrequired
    Text to show beside the analysis.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/builds/{build}/analysis
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analysis" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "status": "done",
  "enabled": true,
  "available": true,
  "id": "@analysis",
  "depth": "fast",
  "trigger": "manual",
  "created_at": "2026-11-13T14:05:00Z",
  "finished_at": "2026-11-13T14:05:00Z",
  "prompt_version": "2026-11-13.1",
  "analysis": {
    "title": "npm cannot install react-router-dom 7 with React 18",
    "cause": "react-router-dom 7.1.0 needs React 19 or newer, and the project depends on React 18.3.1.",
    "confidence": 0.92,
    "steps": [
      "Upgrade react and react-dom to 19 together with the router, then commit the new package-lock.json.",
      "Or stay on react-router-dom 6, which supports React 18."
    ],
    "fixes": [
      {
        "label": "Install with --legacy-peer-deps while you upgrade",
        "field": "install_command",
        "value": "npm ci --legacy-peer-deps"
      }
    ],
    "dropped": []
  },
  "generated_by": "ai",
  "notice": "Written by an AI model from a copy of the log with secrets removed. It can be wrong: check it before you change anything."
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/deploys/{deploy}/analyze #

Explain a failed deploy

deploy Developer key or higher

The same as Explain a failed build, for a deploy that failed while it ran (a crash, a health check that never passed, a timeout). It reads the instance status, the events and the last log lines, with secrets removed. The text is written by a model and can be wrong, so escape it when you show it and never run it.

Path parameters

  • iduuidrequired
    The service's id.
  • deploystringrequired
    A deploy's id, from List deploys.

Response

202
Queued. Poll the analysis.
  • statusstringrequired
    none when nothing was asked yet.

    One of none, queued, running, done, failed.

  • enabledbooleanrequired
    Whether the workspace has turned Kilby AI on.
  • availablebooleanrequired
    Whether Kilby AI is configured on this server.
  • iduuid
    The analysis.
  • depthstring
    fast is the quick model; deep is the thorough one.

    One of fast, deep.

  • triggerstring
    auto when Kilby asked because no rule recognised the failure, manual when a person did.

    One of auto, manual.

  • created_atdatetime
  • finished_atdatetime
  • prompt_versionstring
  • analysisobject
    The explanation, once status is done.
  • titlestringrequired
    One sentence: what went wrong.
  • causestringrequired
    Why, in a few sentences.
  • confidencenumberrequired
    How sure the model says it is, 0 to 1.
  • stepsarray of stringrequired
    What to check.
  • fixesarray of objectrequired
    Proposed changes. Kilby checked each one the way it checks a change you make by hand, and never applies one for you. field is one of root_dir, dockerfile_path, install_command, build_command, start_command, port, plan or env (for env, value is a variable name, never a value).
  • droppedarray of stringrequired
    Proposals Kilby removed because they did not pass its checks.
  • errorobject
    Why an analysis failed.
  • codestringrequired
  • messagestringrequired
  • generated_bystringrequired
    Always ai: show it to people.
  • noticestringrequired
    Text to show beside the analysis.
200
An answer already exists.
  • statusstringrequired
    none when nothing was asked yet.

    One of none, queued, running, done, failed.

  • enabledbooleanrequired
    Whether the workspace has turned Kilby AI on.
  • availablebooleanrequired
    Whether Kilby AI is configured on this server.
  • iduuid
    The analysis.
  • depthstring
    fast is the quick model; deep is the thorough one.

    One of fast, deep.

  • triggerstring
    auto when Kilby asked because no rule recognised the failure, manual when a person did.

    One of auto, manual.

  • created_atdatetime
  • finished_atdatetime
  • prompt_versionstring
  • analysisobject
    The explanation, once status is done.
  • titlestringrequired
    One sentence: what went wrong.
  • causestringrequired
    Why, in a few sentences.
  • confidencenumberrequired
    How sure the model says it is, 0 to 1.
  • stepsarray of stringrequired
    What to check.
  • fixesarray of objectrequired
    Proposed changes. Kilby checked each one the way it checks a change you make by hand, and never applies one for you. field is one of root_dir, dockerfile_path, install_command, build_command, start_command, port, plan or env (for env, value is a variable name, never a value).
  • droppedarray of stringrequired
    Proposals Kilby removed because they did not pass its checks.
  • errorobject
    Why an analysis failed.
  • codestringrequired
  • messagestringrequired
  • generated_bystringrequired
    Always ai: show it to people.
  • noticestringrequired
    Text to show beside the analysis.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403ai_disabled

    The workspace has not turned Kilby AI on (Workspace settings, Kilby AI), or a platform admin has paused it.

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    The build or deploy did not fail, so there is nothing to explain.

  • 429ai_budget

    The workspace or the platform reached its daily allowance, or ai_busy: too many analyses are running. Both send Retry-After.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/services/{id}/deploys/{deploy}/analyze
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analyze" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "status": "queued",
  "enabled": true,
  "available": true,
  "id": "@analysis",
  "trigger": "manual",
  "created_at": "2026-11-13T14:05:00Z",
  "generated_by": "ai",
  "notice": "Written by an AI model from a copy of the log with secrets removed. It can be wrong: check it before you change anything."
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/services/{id}/deploys/{deploy}/analysis #

Read the analysis of a deploy

view Any key

The analysis of a deploy, with the same answer as Read the analysis of a build. The text is written by a model and can be wrong, so escape it when you show it and never run it.

Path parameters

  • iduuidrequired
    The service's id.
  • deploystringrequired
    A deploy's id, from List deploys.

Response

200
The analysis.
  • statusstringrequired
    none when nothing was asked yet.

    One of none, queued, running, done, failed.

  • enabledbooleanrequired
    Whether the workspace has turned Kilby AI on.
  • availablebooleanrequired
    Whether Kilby AI is configured on this server.
  • iduuid
    The analysis.
  • depthstring
    fast is the quick model; deep is the thorough one.

    One of fast, deep.

  • triggerstring
    auto when Kilby asked because no rule recognised the failure, manual when a person did.

    One of auto, manual.

  • created_atdatetime
  • finished_atdatetime
  • prompt_versionstring
  • analysisobject
    The explanation, once status is done.
  • titlestringrequired
    One sentence: what went wrong.
  • causestringrequired
    Why, in a few sentences.
  • confidencenumberrequired
    How sure the model says it is, 0 to 1.
  • stepsarray of stringrequired
    What to check.
  • fixesarray of objectrequired
    Proposed changes. Kilby checked each one the way it checks a change you make by hand, and never applies one for you. field is one of root_dir, dockerfile_path, install_command, build_command, start_command, port, plan or env (for env, value is a variable name, never a value).
  • droppedarray of stringrequired
    Proposals Kilby removed because they did not pass its checks.
  • errorobject
    Why an analysis failed.
  • codestringrequired
  • messagestringrequired
  • generated_bystringrequired
    Always ai: show it to people.
  • noticestringrequired
    Text to show beside the analysis.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/deploys/{deploy}/analysis
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analysis" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "status": "done",
  "enabled": true,
  "available": true,
  "id": "@analysis",
  "depth": "fast",
  "trigger": "manual",
  "created_at": "2026-11-13T14:05:00Z",
  "finished_at": "2026-11-13T14:05:00Z",
  "prompt_version": "2026-11-13.1",
  "analysis": {
    "title": "npm cannot install react-router-dom 7 with React 18",
    "cause": "react-router-dom 7.1.0 needs React 19 or newer, and the project depends on React 18.3.1.",
    "confidence": 0.92,
    "steps": [
      "Upgrade react and react-dom to 19 together with the router, then commit the new package-lock.json.",
      "Or stay on react-router-dom 6, which supports React 18."
    ],
    "fixes": [
      {
        "label": "Install with --legacy-peer-deps while you upgrade",
        "field": "install_command",
        "value": "npm ci --legacy-peer-deps"
      }
    ],
    "dropped": []
  },
  "generated_by": "ai",
  "notice": "Written by an AI model from a copy of the log with secrets removed. It can be wrong: check it before you change anything."
}
Runs in your browser against your workspace with a key you paste.

Templates

A template is a ready-made service, such as an open-source chat interface, a vector database or a workflow tool, that you deploy in one call. It creates ordinary services in your workspace, with a disk, generated secrets and the right settings, so everything in this reference about services applies to them afterwards.

GET/api/v1/templates #

List templates

view Any key

Every template of the gallery, with what it would create. The list is the same for every workspace; available says whether this Kilby can deploy a template now. Templates that need a GPU are listed, with available false, until GPU instance types are offered.

Response

200
The templates.
  • templatesarray of Templaterequired
  • idstringrequired
    Stable. Use it in the paths of the other template endpoints.
  • titlestringrequired
  • summarystringrequired
    One sentence.
  • descriptionstringrequired
    A few sentences.
  • categorystringrequired
    AI apps, Vector databases, Automation, Web or Data.
  • homepageurlrequired
    The project's own page.
  • availablebooleanrequired
    false when this Kilby cannot deploy it yet, for example a template that needs a GPU.
  • unavailable_reasonstring
    Why it cannot be deployed. Only present when available is false.
  • estimated_monthly_centsintegerrequired
    What everything it creates costs for a whole month at list prices, in cents. A template that needs a GPU assumes it runs all month.
  • resourcesarray of objectrequired
    The services it creates, in order. Each has key, role, type (web, private or worker), default_name, image (public, pinned to one tag), port (null for a worker), command (only when it replaces the image's), plan, health_check_path, disk (null, or mount_path and size_gb) and env. Each variable in env has name, source and note: source is fixed (with its value), generated (a secret made when you deploy: it is never shown by this API), input (a value you can send in inputs) or address (set to the service's own public address).
  • inputsarray of objectrequired
    The values it asks for, with name, label, help, required, secret and default. Send them in inputs when you deploy.
  • notesarray of stringrequired
    What to know before deploying, said plainly.
  • after_deployarray of stringrequired
    What to do once it runs: the first login, where the data lives, how other services reach it.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/templates
curl "https://onkilby.com/api/v1/templates" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "templates": [
    {
      "id": "qdrant",
      "title": "Qdrant",
      "summary": "A vector database with a REST API and an API key, on its own disk.",
      "description": "Qdrant stores embeddings and finds the nearest ones fast, with filters. It is a common choice for retrieval-augmented generation. This template runs it as a private service with an API key and a disk, so collections survive redeploys.",
      "category": "Vector databases",
      "homepage": "https://qdrant.tech",
      "available": true,
      "estimated_monthly_cents": 1025,
      "resources": [
        {
          "key": "qdrant",
          "role": "Vector database",
          "type": "private",
          "default_name": "qdrant",
          "image": "qdrant/qdrant:v1.20.1",
          "port": 6333,
          "plan": "starter",
          "health_check_path": "",
          "disk": {"mount_path": "/qdrant/storage", "size_gb": 5},
          "env": [
            {
              "name": "QDRANT__SERVICE__API_KEY",
              "source": "generated",
              "note": "Qdrant refuses requests without it, even from inside the workspace."
            }
          ]
        }
      ],
      "inputs": [],
      "notes": [
        "The Starter instance has 512 MB of memory: enough for a few hundred thousand small vectors. Change the instance type in the service settings when it fills up."
      ],
      "after_deploy": [
        "Other services in this workspace call it at http://qdrant:6333 and send the key in the api-key header. The key is under Environment in the service."
      ]
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/templates/{id} #

Get a template

view Any key

One template with everything it would create, its settings and what to do after deploying it. Secrets it would generate are described, never shown: they do not exist until you deploy.

Path parameters

  • idstringrequired
    The template's id, from List templates.

Response

200
The template.

Returns a Template object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no template with that id.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/templates/{id}
curl "https://onkilby.com/api/v1/templates/open-webui" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "qdrant",
  "title": "Qdrant",
  "summary": "A vector database with a REST API and an API key, on its own disk.",
  "description": "Qdrant stores embeddings and finds the nearest ones fast, with filters. It is a common choice for retrieval-augmented generation. This template runs it as a private service with an API key and a disk, so collections survive redeploys.",
  "category": "Vector databases",
  "homepage": "https://qdrant.tech",
  "available": true,
  "estimated_monthly_cents": 1025,
  "resources": [
    {
      "key": "qdrant",
      "role": "Vector database",
      "type": "private",
      "default_name": "qdrant",
      "image": "qdrant/qdrant:v1.20.1",
      "port": 6333,
      "plan": "starter",
      "health_check_path": "",
      "disk": {"mount_path": "/qdrant/storage", "size_gb": 5},
      "env": [
        {
          "name": "QDRANT__SERVICE__API_KEY",
          "source": "generated",
          "note": "Qdrant refuses requests without it, even from inside the workspace."
        }
      ]
    }
  ],
  "inputs": [],
  "notes": [
    "The Starter instance has 512 MB of memory: enough for a few hundred thousand small vectors. Change the instance type in the service settings when it fills up."
  ],
  "after_deploy": [
    "Other services in this workspace call it at http://qdrant:6333 and send the key in the api-key header. The key is under Environment in the service."
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/templates/{id}/deploy #

Deploy a template

deploy Developer key or higher

Creates the template's services in the workspace and starts their first deploys. It is the same as the Deploy button of the template's page: every limit of the workspace, every rule for names and every audit event applies. Either every service is created or none: if the workspace cannot hold all of them, nothing is made and the answer says which limit.

Keys, passwords and the like that the template needs are generated for you and stored encrypted as environment variables of the services. They are not in the answer: read them with the environment endpoints (needs secrets) or in the dashboard.

Send name to name the template's main service, or names (by the key of each resource) to name several. Leave both out to use the suggested names.

Path parameters

  • idstringrequired
    The template's id, from List templates.

Request body The body is optional: without it the suggested names and default settings are used.

  • namestring
    The name of the main service (the first web service of the template, or its first service). Same rules as for a service.

    3 to 40 characters: lowercase letters, digits and hyphens, starting with a letter. Not starting with db-.

  • namesobject of string
    Names by resource key, for a template that creates more than one service.
  • inputsobject of string
    Values for the settings the template asks for (its inputs), by variable name. Values are stored encrypted.

Response

201
The services that were created.
  • templatestringrequired
    The template's id.
  • primaryuuidrequired
    The service to open first: the template's main one.
  • servicesarray of Servicerequired
    Every service that was created, in the order of the template's resources.
  • after_deployarray of stringrequired
    What to do next, with the names you chose.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no template with that id.

  • 409conflict

    The workspace already has a service with one of the names.

  • 422invalid_request

    A name or a setting is not valid, the template cannot be deployed on this Kilby yet (a GPU template), or the services would not fit in the workspace's limits.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/templates/{id}/deploy
curl -X POST "https://onkilby.com/api/v1/templates/open-webui/deploy" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "team-chat"}'
{
  "template": "qdrant",
  "primary": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "services": [
    {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "qdrant",
      "type": "private",
      "image": "qdrant/qdrant:v1.20.1",
      "port": 6333,
      "plan": "starter",
      "status": "pending",
      "status_message": "",
      "suspended": false,
      "internal_address": "qdrant:6333",
      "created_at": "2026-11-13T14:05:00Z",
      "updated_at": "2026-11-13T14:05:00Z",
      "registry_credential_id": null,
      "health_check_path": "",
      "instances": 1,
      "autoscaling": null,
      "disk": {"mount_path": "/qdrant/storage", "size_gb": 5},
      "instances_running": 0,
      "instances_desired": 1,
      "pre_deploy_command": "",
      "pre_deploy_timeout_seconds": 600,
      "source": null,
      "auto_concurrency": true,
      "render_compat": false,
      "stop_first": false,
      "read_only_root": false,
      "maintenance": false,
      "maintenance_message": ""
    }
  ],
  "after_deploy": [
    "Other services in this workspace call it at http://qdrant:6333 and send the key in the api-key header. The key is under Environment in the service."
  ]
}
Runs in your browser against your workspace with a key you paste.

Webhooks

Two ways for Kilby to call you. Event webhooks send signed JSON when something happens. Deploy hooks go the other way: a secret URL your CI calls to deploy.

Event webhooks

An event webhook sends signed JSON to a URL of yours when something happens in the workspace. Add an endpoint with Add a webhook endpoint, or in the dashboard under Notifications, and choose the events it receives. Every delivery is an HTTPS POST with this envelope; data depends on type.

{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "deploy.started",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "service": {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "my-api",
      "type": "web",
      "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai"
    },
    "deploy": {
      "id": "5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d",
      "title": "Instance type: Starter to Standard",
      "trigger": "update",
      "image": "ghcr.io/acme/api:1.5",
      "status": "deploying",
      "created_at": "2026-11-13T14:05:00Z"
    }
  }
}
deploy.startedA deploy began rolling out.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "deploy.started",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "service": {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "my-api",
      "type": "web",
      "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai"
    },
    "deploy": {
      "id": "5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d",
      "title": "Instance type: Starter to Standard",
      "trigger": "update",
      "image": "ghcr.io/acme/api:1.5",
      "status": "deploying",
      "created_at": "2026-11-13T14:05:00Z"
    }
  }
}
deploy.succeededA deploy is live. For a cron job: its new settings are in place.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "deploy.succeeded",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "service": {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "my-api",
      "type": "web",
      "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai"
    },
    "deploy": {
      "id": "5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d",
      "title": "Instance type: Starter to Standard",
      "trigger": "update",
      "image": "ghcr.io/acme/api:1.5",
      "status": "live",
      "created_at": "2026-11-13T14:05:00Z",
      "finished_at": "2026-11-13T14:06:12Z"
    }
  }
}
deploy.failedA deploy did not go live. The event says why.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "deploy.failed",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "service": {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "my-api",
      "type": "web",
      "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai"
    },
    "deploy": {
      "id": "5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d",
      "title": "Instance type: Starter to Standard",
      "trigger": "update",
      "image": "ghcr.io/acme/api:1.5",
      "status": "failed",
      "reason": "probe",
      "message": "The service never accepted connections on port 8080.",
      "created_at": "2026-11-13T14:05:00Z",
      "finished_at": "2026-11-13T14:08:30Z"
    }
  }
}
service.suspendedA service or cron job was suspended, by someone in the workspace or by a platform administrator.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "service.suspended",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "service": {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "my-api",
      "type": "web",
      "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai"
    },
    "by_admin": false
  }
}
service.resumedA suspended service or cron job was started again.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "service.resumed",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "service": {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "my-api",
      "type": "web",
      "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai"
    },
    "by_admin": false
  }
}
cron.run.failedA run of a cron job exited with an error or ran too long.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "cron.run.failed",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "service": {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "nightly-report",
      "type": "cron"
    },
    "run": {
      "name": "nightly-report-29384760",
      "message": "The command exited with an error.",
      "manual": false,
      "started_at": "2026-11-13T14:05:00Z",
      "finished_at": "2026-11-13T14:05:41Z"
    }
  }
}
database.availableA database finished starting, or recovered, and accepts connections.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "database.available",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "database": {
      "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
      "name": "main",
      "version": "17",
      "plan": "starter"
    },
    "message": ""
  }
}
database.failedA database stopped being healthy and needs attention.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "database.failed",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "database": {
      "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
      "name": "main",
      "version": "17",
      "plan": "starter"
    },
    "message": "The primary is not ready."
  }
}
database.storage_grownKilby made a database's disk bigger because it was nearly full. The event says from which size to which, and when the disk can grow again.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "database.storage_grown",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "database": {
      "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
      "name": "main",
      "version": "17",
      "plan": "starter"
    },
    "storage": {
      "from_gb": 5,
      "to_gb": 6,
      "max_gb": 20,
      "used_percent": 93,
      "next_growth_after": "2026-11-14T20:10:00Z"
    },
    "message": "The disk grew from 5 GB to 6 GB because it was 93% full."
  }
}
database.failoverThe primary of a database with high availability changed hands: a failover after a failure, or a switchover the operator made to update it. The event says which, and from which instance to which.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "database.failover",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "database": {
      "id": "0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
      "name": "main",
      "version": "17",
      "plan": "starter"
    },
    "failover": {"from": "db-main-2", "to": "db-main-1", "planned": false},
    "message": "The primary failed over from db-main-2 to db-main-1."
  }
}
key_value.availableA Key Value instance finished starting, or recovered, and accepts connections.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "key_value.available",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "key_value": {
      "id": "a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73",
      "name": "cache",
      "plan": "1gb"
    },
    "message": ""
  }
}
key_value.failedA Key Value instance stopped being healthy and needs attention.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "key_value.failed",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "key_value": {
      "id": "a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73",
      "name": "cache",
      "plan": "1gb"
    },
    "message": "The server ran out of memory and was stopped. Choose a larger size."
  }
}
billing.invoice_readyAn invoice was issued for the workspace.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "billing.invoice_ready",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "billing": {
      "invoice_id": "@invoice",
      "invoice_number": "KB-202611-00003",
      "total_cents": 10594,
      "period": "2026-11"
    }
  }
}
billing.payment_failedA payment failed. The services keep running for the grace period.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "billing.payment_failed",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "billing": {
      "invoice_id": "@invoice",
      "invoice_number": "KB-202611-00003",
      "total_cents": 10594,
      "period": "2026-11",
      "reason": "Your card was declined.",
      "grace_until": "2026-11-21T00:00:00Z"
    }
  }
}
billing.suspension_soonThe grace period ends within a day: the services will be suspended.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "billing.suspension_soon",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "billing": {
      "invoice_id": "@invoice",
      "invoice_number": "KB-202611-00003",
      "total_cents": 10594,
      "grace_until": "2026-11-21T00:00:00Z"
    }
  }
}
billing.workspace_suspendedThe grace period ended and the workspace's services were suspended. Nothing is deleted.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "billing.workspace_suspended",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "billing": {
      "invoice_id": "@invoice",
      "invoice_number": "KB-202611-00003",
      "services": 4,
      "retain_until": "2027-02-19T00:00:00Z"
    }
  }
}
billing.workspace_resumedAn invoice was paid and what billing suspended runs again.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "billing.workspace_resumed",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "billing": {
      "invoice_id": "@invoice",
      "invoice_number": "KB-202611-00003",
      "services": 4
    }
  }
}
billing.budget_alertSpending this month reached 80% or 100% of the monthly budget.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "billing.budget_alert",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "billing": {
      "budget_cents": 15000,
      "spent_cents": 12000,
      "threshold": 80,
      "hard_cap": false
    }
  }
}
log_stream.disabledA log stream was turned off automatically after its destination kept failing. Its address and credential are never in the event.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "log_stream.disabled",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "log_stream": {
      "id": "d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64",
      "name": "Datadog production",
      "kind": "datadog",
      "reason": "Turned off automatically after 10 failed deliveries in a row over 12 minutes. Last error: The provider refused the credentials (HTTP 403). Check the key or token."
    }
  }
}
shell.openedSomeone opened a shell into a running container of a service in this workspace.
{
  "id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
  "type": "shell.opened",
  "created_at": "2026-11-13T14:05:00Z",
  "workspace": {"id": "3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3", "name": "Acme"},
  "data": {
    "service": {
      "id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "name": "my-api",
      "type": "web",
      "url": "https://my-api-x7k2.apps.kilby.neuramorphic.ai"
    },
    "actor": "Ada Lovelace",
    "actor_id": "6a1d3c52-8e07-4b49-9f2a-5c7e1d0b3a84"
  }
}

Headers on every delivery:

  • Kilby-Signature: t=<unix seconds>,v1=<hex signature>, see below.
  • Kilby-Event-Id, Kilby-Event-Type: the event's id and type. The id is the same on every retry, so use it to ignore duplicates.
  • Kilby-Delivery-Id, Kilby-Delivery-Attempt: this attempt, from 1.
  • User-Agent: Kilby-Webhooks/1.0 and Content-Type: application/json.

Answer with any 2xx within 10 seconds. Anything else, a timeout or a redirect (redirects are not followed) counts as a failure: Kilby tries again after 1 minute, 5 minutes and 30 minutes, four attempts in all. An endpoint that fails 20 attempts in a row is turned off, and the workspace's owners are told; turn it back on with Change a webhook endpoint once it is fixed. Events are not delivered in order, and an event can arrive twice.

Verifying signatures

Anyone can call your URL, so check each delivery's signature. The scheme is the one Stripe uses. Kilby computes an HMAC-SHA256 over the timestamp, a dot and the raw body, keyed with the endpoint's secret: the whole whsec_… string, prefix included. Compare it with the v1 value in constant time, and refuse a timestamp more than 5 minutes from your clock, so that a captured request cannot be replayed.

For the example body below, signed with the secret whsec_your-signing-secret, the header is:

Kilby-Signature: t=1794524411,v1=aff0f5c2e1dfd0808335f42b64782bf5fe83b884517f2d73692d258345a8dfb6
# Check one delivery by hand with openssl.
# BODY is the request body exactly as received, SIGNATURE the Kilby-Signature header,
# and the secret is the whole whsec_... string from when you created the endpoint.
T=$(printf '%s' "$SIGNATURE" | sed -E 's/.*t=([0-9]+).*/\1/')
V1=$(printf '%s' "$SIGNATURE" | sed -E 's/.*v1=([0-9a-f]+).*/\1/')
EXPECTED=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$KILBY_WEBHOOK_SECRET" -hex | sed 's/^.* //')
if [ "$EXPECTED" = "$V1" ]; then echo valid; else echo invalid; fi

Verify against the bytes you received, before you parse them: parsing and printing JSON again changes it. If you roll the secret, the old one stops verifying at once.

Deploy hooks

A deploy hook is a secret URL that deploys one service, made for CI. It needs no API key: the URL is the credential, so keep it in your CI's secrets. Create it in the service's settings or with Create a deploy hook; the URL is shown once. After you push an image, call the hook. Without image it deploys the current image again; with it, a new tag or digest of the same repository.

curl -X POST "https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046?image=ghcr.io%2Facme%2Fapi%3A3f2a9c1&title=Fix+login+redirect"

Build hooks

A service built from a public repository has no push webhook: nobody tells Kilby when the repository changes. A build hook is the secret URL a CI job calls after a push, so that Kilby builds the latest commit. Like a deploy hook it needs no API key, and it can start a build of this one service and nothing else: no parameter names a repository, a ref or a commit. Create it in the service's settings or with Create a build hook; the URL is shown once. The hook asks the host for the latest commit, builds it when it changed, and answers 200 with "status": "up_to_date" when there is nothing new.

curl -X POST "https://onkilby.com/hooks/git/kdh_3f9a1c7e5b2d8046?force=1"
GET/api/v1/services/{id}/deploy-hook #

Get a deploy hook

view Any key

Whether the service has a deploy hook, and when it was last used. The URL itself is never shown again after it was created.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The hook, without its URL.

Returns a DeployHook object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The service has no deploy hook.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/deploy-hook
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "prefix": "kdh_3f9a",
  "created_at": "2026-11-13T14:05:00Z",
  "last_used_at": null
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/deploy-hook #

Create a deploy hook

deploy Developer key or higher

Creates the service's deploy hook, or replaces it: the old URL stops working at once. The answer holds the URL, once; keep it in your CI's secrets. See Deploy hooks for how to call it.

Path parameters

  • iduuidrequired
    The service's id.

Response

201
The hook, with its URL.

Returns a DeployHook object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 20 hooks were created in the last hour.

POSThttps://onkilby.com/api/v1/services/{id}/deploy-hook
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "url": "https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046a9e1c4f7b30d2685c1a7e9f4d6b8203a5",
  "prefix": "kdh_3f9a",
  "created_at": "2026-11-13T14:05:00Z",
  "last_used_at": null
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/services/{id}/deploy-hook #

Revoke a deploy hook

deploy Developer key or higher

Revokes the hook. Its URL stops working immediately.

Path parameters

  • iduuidrequired
    The service's id.

Response

204
Revoked. There is no body.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The service has no deploy hook.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/services/{id}/deploy-hook
curl -X DELETE "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook" \
  -H "Authorization: Bearer $KILBY_API_KEY"
No response body.
Runs in your browser against your workspace with a key you paste.
POST/hooks/deploy/{token} #

Deploy with a deploy hook

No API key

Deploys the service the hook belongs to. It needs no API key: the URL is the credential. Without image it deploys the current image again; with it, a new tag or digest of the same repository (another repository is refused, so a leaked URL cannot run someone else's image).

It allows 10 deploys a minute per hook and 60 requests a minute per address. The hook works while the person who created it is still a member of the workspace and may deploy.

Path parameters

  • tokenstringrequired
    The secret part of the hook URL, starting with kdh_.

Query parameters

  • imagestring
    A new tag or digest of the service's own image repository.
  • titlestring
    A title for the deploy, such as the commit's subject. Plain text. The deploy is listed as the title and the tag it deployed, for example Fix login redirect (3f2a9c1). It can also be sent as the title field of a JSON body.

    up to 120 characters.

Response

202
The deploy has been queued.
  • deployobjectrequired
  • iduuidrequired
  • statusstringrequired
    Always queued.
  • imagestringrequired
  • triggerstringrequired
    Always hook.
  • titlestringrequired
    The tag it deployed, and your title when you sent one.
  • serviceobjectrequired
  • iduuidrequired
  • namestringrequired

Errors

  • 404not_found

    The hook does not exist or was revoked.

  • 409conflict

    The service is suspended.

  • 422invalid_request

    image is not in the service's own repository, or the title is longer than 120 characters.

  • 429rate_limited

    More than 10 deploys a minute for this hook, or 60 requests a minute from your address.

POSThttps://onkilby.com/hooks/deploy/{token}
curl -X POST "https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046?image=ghcr.io%2Facme%2Fapi%3A3f2a9c1&title=Fix+login+redirect"
{
  "deploy": {
    "id": "5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d",
    "status": "queued",
    "image": "ghcr.io/acme/api:3f2a9c1",
    "trigger": "hook",
    "title": "Fix login redirect (3f2a9c1)"
  },
  "service": {"id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea", "name": "my-api"}
}
Runs in your browser against this server.
GET/api/v1/services/{id}/git-hook #

Get a build hook

view Any key

Whether a service built from a public repository has a build hook, and when it was last used. The URL itself is never shown again after it was created.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The hook, without its URL.

Returns a DeployHook object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The service has no build hook.

  • 422invalid_request

    The service is not built from a public repository.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/git-hook
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "prefix": "kgh_3f9a",
  "created_at": "2026-11-13T14:05:00Z",
  "last_used_at": null
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/services/{id}/git-hook #

Create a build hook

deploy Developer key or higher

Creates the build hook of a service built from a public repository, or replaces it: the old URL stops working at once. The answer holds the URL, once; keep it in your CI's secrets. See Build hooks for how to call it.

Path parameters

  • iduuidrequired
    The service's id.

Response

201
The hook, with its URL.

Returns a DeployHook object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    The service is not built from a public repository.

  • 429rate_limited

    More than 20 hooks were created in the last hour.

POSThttps://onkilby.com/api/v1/services/{id}/git-hook
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "url": "https://onkilby.com/hooks/git/kgh_3f9a1c7e5b2d8046a9e1c4f7b30d2685c1a7e9f4d6b8203a5",
  "prefix": "kgh_3f9a",
  "created_at": "2026-11-13T14:05:00Z",
  "last_used_at": null
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/services/{id}/git-hook #

Revoke a build hook

deploy Developer key or higher

Revokes the hook. Its URL stops working immediately.

Path parameters

  • iduuidrequired
    The service's id.

Response

204
Revoked. There is no body.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The service has no build hook.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/services/{id}/git-hook
curl -X DELETE "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook" \
  -H "Authorization: Bearer $KILBY_API_KEY"
No response body.
Runs in your browser against your workspace with a key you paste.
POST/hooks/git/{token} #

Build the latest commit with a build hook

No API key

Builds the latest commit of the branch, tag or commit a service built from a public repository follows. It needs no API key: the URL is the credential, and it can start a build of this one service and nothing else (no parameter names a repository, a ref or a commit). Kilby asks the host for the latest commit (one archive request, shared and cached for a minute) and queues a build when it differs from the newest build's; with force=1 it builds anyway.

It allows 4 calls a minute per hook, 12 forced builds an hour, and 60 requests a minute per address. The hook works while the person who created it is still a member of the workspace and may deploy.

Path parameters

  • tokenstringrequired
    The secret part of the hook URL, starting with kgh_.

Query parameters

  • forceboolean
    Build even when the commit did not change.

Response

202
A build was queued.
  • statusstringrequired
    queued.
  • commitobjectrequired
  • shastringrequired
    Empty when the archive does not say.
  • knownbooleanrequired
  • buildobjectrequired
  • iduuidrequired
  • numberintegerrequired
  • statusstringrequired
  • triggerstringrequired
    Always hook.
  • serviceobjectrequired
  • iduuidrequired
  • namestringrequired
200
Nothing new: the latest commit was already built (or is being built).
  • statusstringrequired
    up_to_date.
  • commitobjectrequired
  • shastringrequired
  • knownbooleanrequired
  • buildobjectrequired
    The build that has this commit.
  • numberintegerrequired
  • statusstringrequired
  • serviceobjectrequired
  • iduuidrequired
  • namestringrequired

Errors

  • 404not_found

    The hook does not exist or was revoked.

  • 409conflict

    The service is suspended.

  • 422invalid_request

    A field is missing or not valid.

  • 429rate_limited

    More than 4 calls a minute for this hook, or 60 requests a minute from your address, or the host asked Kilby to slow down.

  • 503unavailable

    Deploying from Git is not turned on for this Kilby yet.

POSThttps://onkilby.com/hooks/git/{token}
curl -X POST "https://onkilby.com/hooks/git/kdh_3f9a1c7e5b2d8046?force=1"
{
  "status": "queued",
  "commit": {"sha": "8a2e7d9a74a99a24383b37a774d17ddd931058c0", "known": true},
  "build": {
    "id": "5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24",
    "number": 7,
    "status": "queued",
    "trigger": "hook"
  },
  "service": {"id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea", "name": "my-api"}
}
Runs in your browser against this server.
GET/api/v1/webhooks #

List webhook endpoints

view Any key

The workspace's webhook endpoints. A key that cannot manage webhooks sees only each URL's host, because for chat services the URL itself is the credential.

Response

200
The endpoints.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/webhooks
curl "https://onkilby.com/api/v1/webhooks" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "webhooks": [
    {
      "id": "e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90",
      "url": "https://example.com/kilby-events",
      "description": "On-call",
      "events": ["deploy.failed", "cron.run.failed"],
      "enabled": true,
      "created_at": "2026-11-13T14:05:00Z",
      "updated_at": "2026-11-13T14:05:00Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/webhooks #

Add a webhook endpoint

workspace Admin key

Starts sending the chosen events to a URL. The answer holds the signing secret, once: use it to verify that a request came from Kilby (see Verifying signatures). A workspace can have up to 5 endpoints.

Also needs

An admin key, created by an admin or the owner of the workspace.

Request body

  • urlurlrequired
    Where to send events. It must be https and point to a public internet address.

    up to 500 characters.

  • descriptionstring
    A note for you.

    up to 100 characters.

  • eventsarray of stringrequired
    The event types to send. At least one. The list is under Event webhooks.

Response

201
The endpoint, with its signing secret.

Returns a Webhook object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 409conflict

    The workspace already has 5 endpoints.

  • 422invalid_request

    The URL is not allowed, or no event was chosen, or one is not an event type.

  • 429rate_limited

    More than 20 endpoints were created in the last hour.

POSThttps://onkilby.com/api/v1/webhooks
curl -X POST "https://onkilby.com/api/v1/webhooks" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/kilby-events",
  "description": "On-call",
  "events": ["deploy.failed", "cron.run.failed"]
}'
{
  "id": "e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90",
  "url": "https://example.com/kilby-events",
  "description": "On-call",
  "events": ["deploy.failed", "cron.run.failed"],
  "enabled": true,
  "secret": "whsec_your-signing-secret",
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/webhooks/{id} #

Get a webhook endpoint

view Any key

One endpoint. The signing secret is never returned here.

Path parameters

  • iduuidrequired
    The webhook endpoint's id.

Response

200
The endpoint.

Returns a Webhook object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/webhooks/{id}
curl "https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90",
  "url": "https://example.com/kilby-events",
  "description": "On-call",
  "events": ["deploy.failed", "cron.run.failed"],
  "enabled": true,
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/webhooks/{id} #

Change a webhook endpoint

workspace Admin key

Changes the URL, the description or the events, or turns the endpoint on or off. Send only what changes. Turn a disabled endpoint back on with enabled: true after you fixed it.

Also needs

An admin key, created by an admin or the owner of the workspace.

Path parameters

  • iduuidrequired
    The webhook endpoint's id.

Request body

  • urlurl
    A new URL.
  • descriptionstring
    A new note.

    up to 100 characters.

  • eventsarray of string
    The event types to send. At least one. The list is under Event webhooks.
  • enabledboolean
    false pauses delivery; true resumes it.

Response

200
The endpoint after the change.

Returns a Webhook object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 422invalid_request

    A field is not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/webhooks/{id}
curl -X PATCH "https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
{
  "id": "e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90",
  "url": "https://example.com/kilby-events",
  "description": "On-call",
  "events": ["deploy.failed", "cron.run.failed"],
  "enabled": false,
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/webhooks/{id} #

Delete a webhook endpoint

workspace Admin key

Deletes the endpoint. It receives no more events.

Also needs

An admin key, created by an admin or the owner of the workspace.

Path parameters

  • iduuidrequired
    The webhook endpoint's id.

Response

204
Deleted. There is no body.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/webhooks/{id}
curl -X DELETE "https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90" \
  -H "Authorization: Bearer $KILBY_API_KEY"
No response body.
Runs in your browser against your workspace with a key you paste.
POST/api/v1/webhooks/{id}/test #

Send a test event

workspace Admin key

Sends the endpoint one event of type test, signed like any other. It is delivered once, without retries, within a few seconds; see the result in List deliveries.

Also needs

An admin key, created by an admin or the owner of the workspace.

Path parameters

  • iduuidrequired
    The webhook endpoint's id.

Response

202
The test event is queued.
  • event_iduuidrequired
  • typestringrequired
    Always test.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 10 test events a minute for this endpoint.

POSThttps://onkilby.com/api/v1/webhooks/{id}/test
curl -X POST "https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/test" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"event_id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65", "type": "test"}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/webhooks/{id}/secret #

Roll the signing secret

workspace Admin key

Replaces the endpoint's signing secret. The old secret stops verifying at once, so update your receiver first or accept both for a moment. The answer holds the new secret, once.

Also needs

An admin key, created by an admin or the owner of the workspace.

Path parameters

  • iduuidrequired
    The webhook endpoint's id.

Response

200
The endpoint, with the new secret.

Returns a Webhook object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/webhooks/{id}/secret
curl -X POST "https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/secret" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90",
  "url": "https://example.com/kilby-events",
  "description": "On-call",
  "events": ["deploy.failed", "cron.run.failed"],
  "enabled": true,
  "secret": "whsec_your-signing-secret",
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/webhooks/{id}/deliveries #

List deliveries

view Any key

The last 100 deliveries to the endpoint, newest first, with the status code your server answered, how long it took and how many attempts were made. A delivery that failed is tried again after 1 minute, 5 minutes and 30 minutes, then given up.

Path parameters

  • iduuidrequired
    The webhook endpoint's id.

Response

200
The deliveries.
  • deliveriesarray of Deliveryrequired
  • max_attemptsintegerrequired
    How many times one event is tried.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/webhooks/{id}/deliveries
curl "https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/deliveries" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "deliveries": [
    {
      "id": "2e9b4c71-6d3a-4f08-b1c5-8a7e0d9f3c42",
      "event_id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
      "event_type": "deploy.failed",
      "status": "succeeded",
      "attempts": 1,
      "response_code": 200,
      "duration_ms": 184,
      "created_at": "2026-11-13T14:05:00Z",
      "last_attempt_at": "2026-11-13T14:05:00Z"
    }
  ],
  "max_attempts": 4
}
Runs in your browser against your workspace with a key you paste.

DNS AI

DNS AI hosts a domain's whole DNS zone on Kilby. Create the zone, prove the domain is yours with the TXT record in ownership_record, capture the records the domain answers today, add them, and give the registrar the zone's four name servers; ready_to_switch says when nothing is missing. Reading needs any key; every change needs an admin key, because one change can stop a domain's email. When DNS AI is off on this Kilby every call answers 404.

GET/api/v1/dns/zones #

List zones

view Any key

The workspace's zones, oldest first, and how many its plan allows.

Response

200
The zones.
  • zonesarray of DNSZonerequired
  • iduuidrequired
  • namestringrequired
    The domain, such as example.com.
  • statusstringrequired
    verifying: waiting for the ownership record (ownership_record) at the domain's current DNS; no name servers exist yet. creating: being made. pending: waiting for the registrar to use its name servers. active: the registry delegates the domain to exactly these name servers. elsewhere: the registry delegates it to other servers. deleting: removal asked for; the zone stays, empty, while the registrar still uses it.

    One of verifying, creating, pending, active, elsewhere, deleting.

  • status_messagestringrequired
    Why, when the status needs explaining.
  • name_serversarray of stringrequired
    The four name servers to give the registrar.
  • delegated_name_serversarray of stringrequired
    What the registry said at the last check.
  • dnssec_at_registrarbooleanrequired
    The registry holds a DS record for the domain. Kilby does not sign zones yet, so moving stays blocked.
  • versionintegerrequired
    The records' version: every change adds one.
  • publishedbooleanrequired
    Kilby's name servers answer the latest version.
  • publish_errorstringrequired
    Why the latest version is not published yet, if it failed.
  • ready_to_switchbooleanrequired
    Nothing captured is missing, the latest version is published and DNSSEC is off at the registrar: the name servers can move.
  • not_ready_reasonsarray of stringrequired
    Why ready_to_switch is false.
  • record_setsintegerrequired
  • capturedintegerrequired
    Records the domain answered before the move and Kilby verified.
  • missingintegerrequired
    Captured records this zone does not answer the same yet (not counting those marked as not wanted).
  • created_atdatetimerequired
  • updated_atdatetimerequired
  • ownership_recordDNSOwnershipRecord or nullrequired
    While the zone is verifying: the record to create at the domain's current DNS provider to prove it is yours. null once proven.
  • limitintegerrequired
    How many zones the workspace may hold, waiting ones included.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/dns/zones
curl "https://onkilby.com/api/v1/dns/zones" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "zones": [
    {
      "id": "7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13",
      "name": "example.com",
      "status": "pending",
      "status_message": "",
      "name_servers": [
        "ns-1093.awsdns-08.org",
        "ns-1823.awsdns-35.co.uk",
        "ns-282.awsdns-35.com",
        "ns-841.awsdns-41.net"
      ],
      "delegated_name_servers": ["ns1.previous-host.example", "ns2.previous-host.example"],
      "dnssec_at_registrar": false,
      "version": 3,
      "published": true,
      "publish_error": "",
      "ready_to_switch": true,
      "not_ready_reasons": [],
      "record_sets": 4,
      "captured": 4,
      "missing": 0,
      "created_at": "2026-11-13T14:05:00Z",
      "updated_at": "2026-11-13T14:05:00Z",
      "ownership_record": null
    }
  ],
  "limit": 10
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/dns/zones #

Create a zone

workspace Admin key

Starts hosting a domain. First prove it is yours: create the TXT record in ownership_record at the domain's current DNS provider, then call verify (Kilby also looks by itself, every 2 minutes for the first hour and then hourly). Only then does Kilby make the zone and its four name servers. Nothing changes for the domain's visitors until its registrar uses them. A zone that is never proven, or whose name servers the registrar never uses, is removed after 7 days.

Request body

  • namestring
    The whole domain, as bought: example.com, not www.example.com.

Response

201
The new zone, verifying: waiting for its ownership record.

Returns a DNSZone object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403limit_reached

    The workspace holds as many zones as its plan allows, or as many waiting ones.

  • 403forbidden

    The key's role does not allow this.

  • 409conflict

    The workspace already hosts that domain, or its registry already uses the name servers of a zone Kilby hosts. When no workspace holds that zone, a Kilby admin can attach it to this workspace with its records; the message says which case it is, without naming another workspace.

  • 422invalid_request

    Not a whole domain Kilby can host: a subdomain, a reserved domain, or not a domain name.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/dns/zones
curl -X POST "https://onkilby.com/api/v1/dns/zones" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com"}'
{
  "id": "7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13",
  "name": "example.com",
  "status": "verifying",
  "status_message": "_kilby-challenge.example.com does not answer with this zone's value yet. DNS changes can take a few minutes to show.",
  "name_servers": [],
  "delegated_name_servers": [],
  "dnssec_at_registrar": false,
  "version": 0,
  "published": true,
  "publish_error": "",
  "ready_to_switch": false,
  "not_ready_reasons": ["Prove the domain is yours first: create the ownership record."],
  "record_sets": 0,
  "captured": 0,
  "missing": 0,
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "ownership_record": {
    "name": "_kilby-challenge.example.com",
    "type": "TXT",
    "value": "kilby-verify=d4f1a07c9e3b42h8k2m5q7s9"
  }
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/dns/zones/{id} #

Get a zone

view Any key

One zone and its record sets.

Path parameters

  • iduuidrequired
    The zone's id.

Response

200
The zone and its records.
  • zoneDNSZonerequired
  • iduuidrequired
  • namestringrequired
    The domain, such as example.com.
  • statusstringrequired
    verifying: waiting for the ownership record (ownership_record) at the domain's current DNS; no name servers exist yet. creating: being made. pending: waiting for the registrar to use its name servers. active: the registry delegates the domain to exactly these name servers. elsewhere: the registry delegates it to other servers. deleting: removal asked for; the zone stays, empty, while the registrar still uses it.

    One of verifying, creating, pending, active, elsewhere, deleting.

  • status_messagestringrequired
    Why, when the status needs explaining.
  • name_serversarray of stringrequired
    The four name servers to give the registrar.
  • delegated_name_serversarray of stringrequired
    What the registry said at the last check.
  • dnssec_at_registrarbooleanrequired
    The registry holds a DS record for the domain. Kilby does not sign zones yet, so moving stays blocked.
  • versionintegerrequired
    The records' version: every change adds one.
  • publishedbooleanrequired
    Kilby's name servers answer the latest version.
  • publish_errorstringrequired
    Why the latest version is not published yet, if it failed.
  • ready_to_switchbooleanrequired
    Nothing captured is missing, the latest version is published and DNSSEC is off at the registrar: the name servers can move.
  • not_ready_reasonsarray of stringrequired
    Why ready_to_switch is false.
  • record_setsintegerrequired
  • capturedintegerrequired
    Records the domain answered before the move and Kilby verified.
  • missingintegerrequired
    Captured records this zone does not answer the same yet (not counting those marked as not wanted).
  • created_atdatetimerequired
  • updated_atdatetimerequired
  • ownership_recordDNSOwnershipRecord or nullrequired
    While the zone is verifying: the record to create at the domain's current DNS provider to prove it is yours. null once proven.
  • recordsarray of DNSRecordSetrequired
  • namestringrequired
    Relative to the zone: @ for the domain itself, www, _dmarc.
  • typestringrequired
    ALIAS points to Kilby's load balancer and works on the domain itself.

    One of A, AAAA, CNAME, MX, TXT, CAA, SRV, ALIAS.

  • ttlintegerrequired
    Seconds, 60 to 86400.
  • valuesarray of stringrequired
    MX: 10 mail.example.com. SRV: 10 5 5060 sip.example.com. CAA: 0 issue "letsencrypt.org". ALIAS: kilby.
  • managed_by_domainuuid or nullrequired
    The custom domain Kilby keeps this record for (Configure automatically); it cannot be changed by hand. null for your own records.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The workspace has no zone with that id.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/dns/zones/{id}
curl "https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "zone": {
    "id": "7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13",
    "name": "example.com",
    "status": "pending",
    "status_message": "",
    "name_servers": [
      "ns-1093.awsdns-08.org",
      "ns-1823.awsdns-35.co.uk",
      "ns-282.awsdns-35.com",
      "ns-841.awsdns-41.net"
    ],
    "delegated_name_servers": ["ns1.previous-host.example", "ns2.previous-host.example"],
    "dnssec_at_registrar": false,
    "version": 3,
    "published": true,
    "publish_error": "",
    "ready_to_switch": true,
    "not_ready_reasons": [],
    "record_sets": 4,
    "captured": 4,
    "missing": 0,
    "created_at": "2026-11-13T14:05:00Z",
    "updated_at": "2026-11-13T14:05:00Z",
    "ownership_record": null
  },
  "records": [
    {
      "name": "@",
      "type": "MX",
      "ttl": 3600,
      "values": ["1 aspmx.l.google.com", "5 alt1.aspmx.l.google.com"],
      "managed_by_domain": null
    },
    {
      "name": "@",
      "type": "TXT",
      "ttl": 300,
      "values": ["v=spf1 include:_spf.google.com ~all"],
      "managed_by_domain": null
    },
    {
      "name": "_dmarc",
      "type": "TXT",
      "ttl": 300,
      "values": ["v=DMARC1; p=quarantine"],
      "managed_by_domain": null
    },
    {
      "name": "www",
      "type": "CNAME",
      "ttl": 300,
      "values": ["site.previous-host.example"],
      "managed_by_domain": null
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/dns/zones/{id}/verify #

Check the ownership record

workspace Admin key

Looks for the zone's ownership record now, at the name servers the registry delegates the domain to today. When it answers with the zone's value, Kilby makes the zone and its four name servers (creating, then pending). A zone that is not verifying is returned as it is.

Path parameters

  • iduuidrequired
    The zone's id.

Response

200
The zone. Still verifying (with status_message saying what was found) until the record answers.

Returns a DNSZone object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The workspace has no zone with that id.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/dns/zones/{id}/verify
curl -X POST "https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/verify" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13",
  "name": "example.com",
  "status": "verifying",
  "status_message": "_kilby-challenge.example.com does not answer with this zone's value yet. DNS changes can take a few minutes to show.",
  "name_servers": [],
  "delegated_name_servers": [],
  "dnssec_at_registrar": false,
  "version": 0,
  "published": true,
  "publish_error": "",
  "ready_to_switch": false,
  "not_ready_reasons": ["Prove the domain is yours first: create the ownership record."],
  "record_sets": 0,
  "captured": 0,
  "missing": 0,
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "ownership_record": {
    "name": "_kilby-challenge.example.com",
    "type": "TXT",
    "value": "kilby-verify=d4f1a07c9e3b42h8k2m5q7s9"
  }
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/dns/zones/{id} #

Delete a zone

workspace Admin key

Removes the zone's records at once. The zone itself stays, empty, while the registrar still uses its name servers, so that nobody else can take the domain over; Kilby removes it once the registrar points elsewhere. A zone still verifying has nothing in DNS yet and goes at once.

Path parameters

  • iduuidrequired
    The zone's id.

Response

202
The zone, now deleting.

Returns a DNSZone object.

204
The zone was still verifying: it is gone.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The workspace has no zone with that id.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/dns/zones/{id}
curl -X DELETE "https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13",
  "name": "example.com",
  "status": "pending",
  "status_message": "",
  "name_servers": [
    "ns-1093.awsdns-08.org",
    "ns-1823.awsdns-35.co.uk",
    "ns-282.awsdns-35.com",
    "ns-841.awsdns-41.net"
  ],
  "delegated_name_servers": ["ns1.previous-host.example", "ns2.previous-host.example"],
  "dnssec_at_registrar": false,
  "version": 3,
  "published": true,
  "publish_error": "",
  "ready_to_switch": true,
  "not_ready_reasons": [],
  "record_sets": 4,
  "captured": 4,
  "missing": 0,
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "ownership_record": null
}
Runs in your browser against your workspace with a key you paste.
PUT/api/v1/dns/zones/{id}/records #

Create or replace a record set

workspace Admin key

Saves every value of one name and type, replacing the set of that name and type if there is one. Kilby publishes the new version to its name servers within a minute. Records kept for a custom domain cannot be changed here.

Path parameters

  • iduuidrequired
    The zone's id.

Request body

  • namestring
    Relative to the zone: @, www, _dmarc.
  • typestring
  • ttlinteger
    Seconds, 60 to 86400. Default 300.
  • valuesarray of string
    One or more values.
  • replacestring
    To rename or retype a set: the name and type of the set it replaces, such as www CNAME.

Response

200
The zone and its records.
  • zoneDNSZonerequired
  • iduuidrequired
  • namestringrequired
    The domain, such as example.com.
  • statusstringrequired
    verifying: waiting for the ownership record (ownership_record) at the domain's current DNS; no name servers exist yet. creating: being made. pending: waiting for the registrar to use its name servers. active: the registry delegates the domain to exactly these name servers. elsewhere: the registry delegates it to other servers. deleting: removal asked for; the zone stays, empty, while the registrar still uses it.

    One of verifying, creating, pending, active, elsewhere, deleting.

  • status_messagestringrequired
    Why, when the status needs explaining.
  • name_serversarray of stringrequired
    The four name servers to give the registrar.
  • delegated_name_serversarray of stringrequired
    What the registry said at the last check.
  • dnssec_at_registrarbooleanrequired
    The registry holds a DS record for the domain. Kilby does not sign zones yet, so moving stays blocked.
  • versionintegerrequired
    The records' version: every change adds one.
  • publishedbooleanrequired
    Kilby's name servers answer the latest version.
  • publish_errorstringrequired
    Why the latest version is not published yet, if it failed.
  • ready_to_switchbooleanrequired
    Nothing captured is missing, the latest version is published and DNSSEC is off at the registrar: the name servers can move.
  • not_ready_reasonsarray of stringrequired
    Why ready_to_switch is false.
  • record_setsintegerrequired
  • capturedintegerrequired
    Records the domain answered before the move and Kilby verified.
  • missingintegerrequired
    Captured records this zone does not answer the same yet (not counting those marked as not wanted).
  • created_atdatetimerequired
  • updated_atdatetimerequired
  • ownership_recordDNSOwnershipRecord or nullrequired
    While the zone is verifying: the record to create at the domain's current DNS provider to prove it is yours. null once proven.
  • recordsarray of DNSRecordSetrequired
  • namestringrequired
    Relative to the zone: @ for the domain itself, www, _dmarc.
  • typestringrequired
    ALIAS points to Kilby's load balancer and works on the domain itself.

    One of A, AAAA, CNAME, MX, TXT, CAA, SRV, ALIAS.

  • ttlintegerrequired
    Seconds, 60 to 86400.
  • valuesarray of stringrequired
    MX: 10 mail.example.com. SRV: 10 5 5060 sip.example.com. CAA: 0 issue "letsencrypt.org". ALIAS: kilby.
  • managed_by_domainuuid or nullrequired
    The custom domain Kilby keeps this record for (Configure automatically); it cannot be changed by hand. null for your own records.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The workspace has no zone with that id.

  • 422invalid_request

    DNS does not allow it, and the message says why: a CNAME on the domain itself or next to another record, a bad value, a record kept for a custom domain.

  • 429rate_limited

    More than 300 requests a minute for this key.

PUThttps://onkilby.com/api/v1/dns/zones/{id}/records
curl -X PUT "https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "www",
  "type": "CNAME",
  "ttl": 300,
  "values": ["site.previous-host.example"]
}'
{
  "zone": {
    "id": "7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13",
    "name": "example.com",
    "status": "pending",
    "status_message": "",
    "name_servers": [
      "ns-1093.awsdns-08.org",
      "ns-1823.awsdns-35.co.uk",
      "ns-282.awsdns-35.com",
      "ns-841.awsdns-41.net"
    ],
    "delegated_name_servers": ["ns1.previous-host.example", "ns2.previous-host.example"],
    "dnssec_at_registrar": false,
    "version": 3,
    "published": true,
    "publish_error": "",
    "ready_to_switch": true,
    "not_ready_reasons": [],
    "record_sets": 4,
    "captured": 4,
    "missing": 0,
    "created_at": "2026-11-13T14:05:00Z",
    "updated_at": "2026-11-13T14:05:00Z",
    "ownership_record": null
  },
  "records": [
    {
      "name": "@",
      "type": "MX",
      "ttl": 3600,
      "values": ["1 aspmx.l.google.com", "5 alt1.aspmx.l.google.com"],
      "managed_by_domain": null
    },
    {
      "name": "@",
      "type": "TXT",
      "ttl": 300,
      "values": ["v=spf1 include:_spf.google.com ~all"],
      "managed_by_domain": null
    },
    {
      "name": "_dmarc",
      "type": "TXT",
      "ttl": 300,
      "values": ["v=DMARC1; p=quarantine"],
      "managed_by_domain": null
    },
    {
      "name": "www",
      "type": "CNAME",
      "ttl": 300,
      "values": ["site.previous-host.example"],
      "managed_by_domain": null
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/dns/zones/{id}/records/{type}/{name} #

Delete a record set

workspace Admin key

Removes every value of one name and type.

Path parameters

  • iduuidrequired
    The zone's id.
  • typestringrequired
    The record type.
  • namestringrequired
    The name, relative to the zone (@ for the domain itself).

Response

200
The zone and its records.
  • zoneDNSZonerequired
  • iduuidrequired
  • namestringrequired
    The domain, such as example.com.
  • statusstringrequired
    verifying: waiting for the ownership record (ownership_record) at the domain's current DNS; no name servers exist yet. creating: being made. pending: waiting for the registrar to use its name servers. active: the registry delegates the domain to exactly these name servers. elsewhere: the registry delegates it to other servers. deleting: removal asked for; the zone stays, empty, while the registrar still uses it.

    One of verifying, creating, pending, active, elsewhere, deleting.

  • status_messagestringrequired
    Why, when the status needs explaining.
  • name_serversarray of stringrequired
    The four name servers to give the registrar.
  • delegated_name_serversarray of stringrequired
    What the registry said at the last check.
  • dnssec_at_registrarbooleanrequired
    The registry holds a DS record for the domain. Kilby does not sign zones yet, so moving stays blocked.
  • versionintegerrequired
    The records' version: every change adds one.
  • publishedbooleanrequired
    Kilby's name servers answer the latest version.
  • publish_errorstringrequired
    Why the latest version is not published yet, if it failed.
  • ready_to_switchbooleanrequired
    Nothing captured is missing, the latest version is published and DNSSEC is off at the registrar: the name servers can move.
  • not_ready_reasonsarray of stringrequired
    Why ready_to_switch is false.
  • record_setsintegerrequired
  • capturedintegerrequired
    Records the domain answered before the move and Kilby verified.
  • missingintegerrequired
    Captured records this zone does not answer the same yet (not counting those marked as not wanted).
  • created_atdatetimerequired
  • updated_atdatetimerequired
  • ownership_recordDNSOwnershipRecord or nullrequired
    While the zone is verifying: the record to create at the domain's current DNS provider to prove it is yours. null once proven.
  • recordsarray of DNSRecordSetrequired
  • namestringrequired
    Relative to the zone: @ for the domain itself, www, _dmarc.
  • typestringrequired
    ALIAS points to Kilby's load balancer and works on the domain itself.

    One of A, AAAA, CNAME, MX, TXT, CAA, SRV, ALIAS.

  • ttlintegerrequired
    Seconds, 60 to 86400.
  • valuesarray of stringrequired
    MX: 10 mail.example.com. SRV: 10 5 5060 sip.example.com. CAA: 0 issue "letsencrypt.org". ALIAS: kilby.
  • managed_by_domainuuid or nullrequired
    The custom domain Kilby keeps this record for (Configure automatically); it cannot be changed by hand. null for your own records.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The zone has no record set of that name and type.

  • 422invalid_request

    The record is kept by Kilby for a custom domain.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/dns/zones/{id}/records/{type}/{name}
curl -X DELETE "https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records/TXT/_dmarc" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "zone": {
    "id": "7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13",
    "name": "example.com",
    "status": "pending",
    "status_message": "",
    "name_servers": [
      "ns-1093.awsdns-08.org",
      "ns-1823.awsdns-35.co.uk",
      "ns-282.awsdns-35.com",
      "ns-841.awsdns-41.net"
    ],
    "delegated_name_servers": ["ns1.previous-host.example", "ns2.previous-host.example"],
    "dnssec_at_registrar": false,
    "version": 3,
    "published": true,
    "publish_error": "",
    "ready_to_switch": true,
    "not_ready_reasons": [],
    "record_sets": 4,
    "captured": 4,
    "missing": 0,
    "created_at": "2026-11-13T14:05:00Z",
    "updated_at": "2026-11-13T14:05:00Z",
    "ownership_record": null
  },
  "records": [
    {
      "name": "@",
      "type": "MX",
      "ttl": 3600,
      "values": ["1 aspmx.l.google.com", "5 alt1.aspmx.l.google.com"],
      "managed_by_domain": null
    },
    {
      "name": "@",
      "type": "TXT",
      "ttl": 300,
      "values": ["v=spf1 include:_spf.google.com ~all"],
      "managed_by_domain": null
    },
    {
      "name": "_dmarc",
      "type": "TXT",
      "ttl": 300,
      "values": ["v=DMARC1; p=quarantine"],
      "managed_by_domain": null
    },
    {
      "name": "www",
      "type": "CNAME",
      "ttl": 300,
      "values": ["site.previous-host.example"],
      "managed_by_domain": null
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/dns/zones/{id}/capture #

Capture today's records

workspace Admin key

Asks the name servers the domain uses today about every record a source suggests, and keeps only what they really answer. scan looks at common names and mail records; zonefile reads text, a zone file exported from the current provider. Answers every record captured so far.

Path parameters

  • iduuidrequired
    The zone's id.

Request body

  • sourcestring
    scan or zonefile.
  • textstring
    The zone file, for zonefile.

Response

200
What was found.
  • foundintegerrequired
    Record sets the current name servers answered.
  • unansweredintegerrequired
    Suggested records they did not answer: left out.
  • warningsarray of stringrequired
    Lines of a zone file that were skipped, and why.
  • Everything captured for this zone so far.
  • namestringrequired
  • typestringrequired
  • ttlintegerrequired
  • valuesarray of stringrequired
  • sourcestringrequired
    What suggested it: Scan, Zone file, or another source.
  • reasonstringrequired
    Why that name was looked at.
  • waivedbooleanrequired
    Marked as not wanted: it does not block the move.
  • missingbooleanrequired
    This zone does not answer the same values yet.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The workspace has no zone with that id.

  • 422invalid_request

    No such source, or the domain already uses Kilby's name servers, or its current name servers did not answer.

  • 429rate_limited

    Too many captures of this zone in the last hour.

POSThttps://onkilby.com/api/v1/dns/zones/{id}/capture
curl -X POST "https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/capture" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "scan"}'
{
  "found": 1,
  "unanswered": 0,
  "warnings": [],
  "captured": [
    {
      "name": "_dmarc",
      "type": "TXT",
      "ttl": 300,
      "values": ["v=DMARC1; p=quarantine"],
      "source": "Scan",
      "reason": "Mail: DMARC policy",
      "waived": false,
      "missing": false
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/domains/{id}/configure-dns #

Configure a custom domain from its zone

workspace Admin key

For a custom domain inside an active zone of the workspace: adds an ALIAS to Kilby's load balancer at its name and the _acme-challenge record that gets its certificate. Kilby keeps both for the domain. Records of a site at that name (A, AAAA, CNAME) are replaced; mail records are left alone.

Path parameters

  • iduuidrequired
    The domain's id.

Response

200
The zone and its records.
  • zoneDNSZonerequired
  • iduuidrequired
  • namestringrequired
    The domain, such as example.com.
  • statusstringrequired
    verifying: waiting for the ownership record (ownership_record) at the domain's current DNS; no name servers exist yet. creating: being made. pending: waiting for the registrar to use its name servers. active: the registry delegates the domain to exactly these name servers. elsewhere: the registry delegates it to other servers. deleting: removal asked for; the zone stays, empty, while the registrar still uses it.

    One of verifying, creating, pending, active, elsewhere, deleting.

  • status_messagestringrequired
    Why, when the status needs explaining.
  • name_serversarray of stringrequired
    The four name servers to give the registrar.
  • delegated_name_serversarray of stringrequired
    What the registry said at the last check.
  • dnssec_at_registrarbooleanrequired
    The registry holds a DS record for the domain. Kilby does not sign zones yet, so moving stays blocked.
  • versionintegerrequired
    The records' version: every change adds one.
  • publishedbooleanrequired
    Kilby's name servers answer the latest version.
  • publish_errorstringrequired
    Why the latest version is not published yet, if it failed.
  • ready_to_switchbooleanrequired
    Nothing captured is missing, the latest version is published and DNSSEC is off at the registrar: the name servers can move.
  • not_ready_reasonsarray of stringrequired
    Why ready_to_switch is false.
  • record_setsintegerrequired
  • capturedintegerrequired
    Records the domain answered before the move and Kilby verified.
  • missingintegerrequired
    Captured records this zone does not answer the same yet (not counting those marked as not wanted).
  • created_atdatetimerequired
  • updated_atdatetimerequired
  • ownership_recordDNSOwnershipRecord or nullrequired
    While the zone is verifying: the record to create at the domain's current DNS provider to prove it is yours. null once proven.
  • recordsarray of DNSRecordSetrequired
  • namestringrequired
    Relative to the zone: @ for the domain itself, www, _dmarc.
  • typestringrequired
    ALIAS points to Kilby's load balancer and works on the domain itself.

    One of A, AAAA, CNAME, MX, TXT, CAA, SRV, ALIAS.

  • ttlintegerrequired
    Seconds, 60 to 86400.
  • valuesarray of stringrequired
    MX: 10 mail.example.com. SRV: 10 5 5060 sip.example.com. CAA: 0 issue "letsencrypt.org". ALIAS: kilby.
  • managed_by_domainuuid or nullrequired
    The custom domain Kilby keeps this record for (Configure automatically); it cannot be changed by hand. null for your own records.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The workspace has no domain with that id.

  • 409conflict

    No active zone of the workspace contains the domain.

  • 429rate_limited

    More than 300 requests a minute for this key.

POSThttps://onkilby.com/api/v1/domains/{id}/configure-dns
curl -X POST "https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/configure-dns" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "zone": {
    "id": "7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13",
    "name": "example.com",
    "status": "pending",
    "status_message": "",
    "name_servers": [
      "ns-1093.awsdns-08.org",
      "ns-1823.awsdns-35.co.uk",
      "ns-282.awsdns-35.com",
      "ns-841.awsdns-41.net"
    ],
    "delegated_name_servers": ["ns1.previous-host.example", "ns2.previous-host.example"],
    "dnssec_at_registrar": false,
    "version": 3,
    "published": true,
    "publish_error": "",
    "ready_to_switch": true,
    "not_ready_reasons": [],
    "record_sets": 4,
    "captured": 4,
    "missing": 0,
    "created_at": "2026-11-13T14:05:00Z",
    "updated_at": "2026-11-13T14:05:00Z",
    "ownership_record": null
  },
  "records": [
    {
      "name": "@",
      "type": "MX",
      "ttl": 3600,
      "values": ["1 aspmx.l.google.com", "5 alt1.aspmx.l.google.com"],
      "managed_by_domain": null
    },
    {
      "name": "@",
      "type": "TXT",
      "ttl": 300,
      "values": ["v=spf1 include:_spf.google.com ~all"],
      "managed_by_domain": null
    },
    {
      "name": "_dmarc",
      "type": "TXT",
      "ttl": 300,
      "values": ["v=DMARC1; p=quarantine"],
      "managed_by_domain": null
    },
    {
      "name": "www",
      "type": "CNAME",
      "ttl": 300,
      "values": ["site.previous-host.example"],
      "managed_by_domain": null
    }
  ]
}
Runs in your browser against your workspace with a key you paste.

Log streams

A log stream forwards the logs of your services to a provider you use: Datadog, an HTTPS endpoint, syslog over TLS, Grafana Loki or Better Stack. It needs log storage to be on; when it is not, GET /log-streams says enabled: false and the other calls answer 503. A credential goes in and never comes out: every answer says whether one is set and shows its last four characters. Reading names and states needs any key; the settings need a Developer key or higher; changing anything needs an admin key.

GET/api/v1/log-streams #

List log streams

view Any key

The workspace's log streams. enabled is false when this platform does not forward logs yet (then the list is empty and unavailable_reason says why). A Viewer key sees each stream's name, provider and state only; a Developer key or higher sees the settings, the last four characters of the credential and the delivery state.

Response

200
The log streams.
  • enabledbooleanrequired
  • unavailable_reasonstring
    Why forwarding is not available. Only when it is not.
  • limitintegerrequired
    How many log streams a workspace can have.
  • log_streamsarray of LogStreamrequired
  • iduuidrequired
  • namestringrequired
    Unique in the workspace.
  • kindstringrequired
    The provider.

    One of datadog, https, syslog, loki, betterstack.

  • enabledbooleanrequired
    Whether lines are forwarded. A destination turned off keeps its settings.
  • statestringrequired
    healthy: the last delivery worked. failing: deliveries are failing and being retried. disabled: turned off, by a person or by Kilby after sustained failure (see disabled_reason). waiting: on, nothing delivered yet.

    One of healthy, failing, disabled, waiting.

  • created_atdatetimerequired
  • endpointstring
    The address: an https URL, or host:port for syslog. Empty for Datadog, where the site picks it.
  • optionsobject
    The provider's non-secret settings: site and tags (Datadog), header, format, gzip and tls (HTTPS), facility and tls (syslog), user and tls (Loki).
  • servicesarray of uuid
    The services forwarded. An empty list is every service.
  • min_levelstring
    The lowest level forwarded.

    One of debug, info, warn, error.

  • secretobject
    set says whether a credential is stored and last4 is its last four characters. The credential itself is never returned.
  • last_success_atdatetime or null
    When a batch was last delivered.
  • last_errorstring
    Why the last delivery failed, in one sentence; empty while it works.
  • disabled_reasonstring
    Why Kilby turned it off; empty otherwise.
  • last_testobject or null
    The answer to the last test line: at, ok and status, a sentence that names the HTTP status the provider answered. Never the provider's body.
  • todayobject
    Lines and bytes sent today (UTC) and the lines that were dropped, by reason: slow (the destination was too slow or down and the buffer was full), rate and daily (the limits) and failed (a batch that was given up).
  • updated_atdatetime

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/log-streams
curl "https://onkilby.com/api/v1/log-streams" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "enabled": true,
  "limit": 3,
  "log_streams": [
    {
      "id": "d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64",
      "name": "Datadog production",
      "kind": "datadog",
      "enabled": true,
      "state": "healthy",
      "created_at": "2026-11-13T14:05:00Z",
      "endpoint": "",
      "options": {"site": "eu1", "tags": "env:prod,team:ai"},
      "services": [],
      "min_level": "info",
      "secret": {"set": true, "last4": "c0de"},
      "last_success_at": "2026-11-13T14:05:00Z",
      "last_error": "",
      "disabled_reason": "",
      "last_test": {
        "at": "2026-11-13T14:05:00Z",
        "ok": true,
        "status": "Datadog answered HTTP 202."
      },
      "today": {
        "lines_sent": 12408,
        "bytes_sent": 1960112,
        "dropped": {"slow": 0, "rate": 0, "daily": 0, "failed": 0}
      },
      "updated_at": "2026-11-13T14:05:00Z"
    }
  ]
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/log-streams #

Add a log stream

workspace Admin key

Adds a destination. Kilby starts forwarding within about 15 seconds. Use Send a test line to check it. The credential is stored encrypted, and this answer shows only its last four characters.

Needs an admin key. A workspace can have up to three log streams.

Request body

  • namestringrequired
    A name for the destination, unique in the workspace.

    1 to 60 characters.

  • kindstringrequired
    The provider. It cannot be changed later.

    One of datadog, https, syslog, loki, betterstack.

  • endpointstring
    https: the URL. betterstack and loki: the https URL. syslog: host:port (the port defaults to 6514). Not used for Datadog. A URL cannot hold a user name, a password, or a key in its query string; every address must resolve to a public address.

    up to 500 characters.

  • secretstring
    The API key or token: required for Datadog and Better Stack, optional for the others. It is stored encrypted and never returned.

    12 to 512 visible characters.

  • optionsobject
    Settings that belong to the provider: site (us1, us3, us5, eu1 or ap1) and tags for Datadog; header (the header the token is sent in, instead of Authorization: Bearer), format (ndjson or json), gzip and tls (verify or skip) for https; facility (user, daemon or local0 to local7) and tls for syslog; user and tls for Loki. An option that does not belong to the provider is refused.
  • servicesarray of string
    Service names or ids to forward. Empty or left out is every service.

    up to 50 services of this workspace.

  • min_levelstring
    The lowest level forwarded. The level is guessed from the line, like the Logs tab does.

    One of debug, info, warn, error. Default debug.

  • enabledboolean
    Whether to forward lines.

    Default true.

Response

201
The log stream.

Returns a LogStream object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key is not an admin key.

  • 409conflict

    The name is taken, or the workspace already has three log streams.

  • 422invalid_request

    A field is not valid: a private or non-https address, a credential in the URL, a token that is too short, an unknown service.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 503unavailable

    Log forwarding is not available: log storage is off, or log streams are.

POSThttps://onkilby.com/api/v1/log-streams
curl -X POST "https://onkilby.com/api/v1/log-streams" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Datadog production",
  "kind": "datadog",
  "secret": "0123456789abcdef0123456789abc0de",
  "options": {"site": "eu1", "tags": "env:prod,team:ai"},
  "min_level": "info"
}'
{
  "id": "d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64",
  "name": "Datadog production",
  "kind": "datadog",
  "enabled": true,
  "state": "healthy",
  "created_at": "2026-11-13T14:05:00Z",
  "endpoint": "",
  "options": {"site": "eu1", "tags": "env:prod,team:ai"},
  "services": [],
  "min_level": "info",
  "secret": {"set": true, "last4": "c0de"},
  "last_success_at": "2026-11-13T14:05:00Z",
  "last_error": "",
  "disabled_reason": "",
  "last_test": {
    "at": "2026-11-13T14:05:00Z",
    "ok": true,
    "status": "Datadog answered HTTP 202."
  },
  "today": {
    "lines_sent": 12408,
    "bytes_sent": 1960112,
    "dropped": {"slow": 0, "rate": 0, "daily": 0, "failed": 0}
  },
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/log-streams/{id} #

Read a log stream

view Any key

One log stream, with the same visibility rules as the list.

Path parameters

  • iduuidrequired
    The log stream's id.

Response

200
The log stream.

Returns a LogStream object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    There is no such log stream in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/log-streams/{id}
curl "https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64",
  "name": "Datadog production",
  "kind": "datadog",
  "enabled": true,
  "state": "healthy",
  "created_at": "2026-11-13T14:05:00Z",
  "endpoint": "",
  "options": {"site": "eu1", "tags": "env:prod,team:ai"},
  "services": [],
  "min_level": "info",
  "secret": {"set": true, "last4": "c0de"},
  "last_success_at": "2026-11-13T14:05:00Z",
  "last_error": "",
  "disabled_reason": "",
  "last_test": {
    "at": "2026-11-13T14:05:00Z",
    "ok": true,
    "status": "Datadog answered HTTP 202."
  },
  "today": {
    "lines_sent": 12408,
    "bytes_sent": 1960112,
    "dropped": {"slow": 0, "rate": 0, "daily": 0, "failed": 0}
  },
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/log-streams/{id} #

Change a log stream

workspace Admin key

Changes the fields you send and leaves the rest. The credential is kept unless you send a new secret or remove_secret: true. If you change where the credential is sent (the address, the Datadog site, the header or the Loki user) you must send the credential again: it is never shown, so Kilby will not move it to a new address for you. Turning a destination back on clears its failure state.

Path parameters

  • iduuidrequired
    The log stream's id.

Request body

  • namestring
    A name for the destination, unique in the workspace.

    1 to 60 characters.

  • endpointstring
    https: the URL. betterstack and loki: the https URL. syslog: host:port (the port defaults to 6514). Not used for Datadog. A URL cannot hold a user name, a password, or a key in its query string; every address must resolve to a public address.

    up to 500 characters.

  • secretstring
    The API key or token: required for Datadog and Better Stack, optional for the others. It is stored encrypted and never returned.

    12 to 512 visible characters.

  • optionsobject
    Settings that belong to the provider: site (us1, us3, us5, eu1 or ap1) and tags for Datadog; header (the header the token is sent in, instead of Authorization: Bearer), format (ndjson or json), gzip and tls (verify or skip) for https; facility (user, daemon or local0 to local7) and tls for syslog; user and tls for Loki. An option that does not belong to the provider is refused.
  • servicesarray of string
    Service names or ids to forward. Empty or left out is every service.

    up to 50 services of this workspace.

  • min_levelstring
    The lowest level forwarded. The level is guessed from the line, like the Logs tab does.

    One of debug, info, warn, error. Default debug.

  • enabledboolean
    Whether to forward lines.

    Default true.

  • remove_secretboolean
    Remove the stored credential (not for Datadog or Better Stack).

    Default false.

Response

200
The log stream.

Returns a LogStream object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key is not an admin key.

  • 404not_found

    There is no such log stream in this workspace.

  • 409conflict

    The name is taken, or the workspace already has three log streams.

  • 422invalid_request

    A field is not valid: a private or non-https address, a credential in the URL, a token that is too short, an unknown service.

  • 429rate_limited

    More than 300 requests a minute for this key.

  • 503unavailable

    Log forwarding is not available: log storage is off, or log streams are.

PATCHhttps://onkilby.com/api/v1/log-streams/{id}
curl -X PATCH "https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"min_level": "warn"}'
{
  "id": "d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64",
  "name": "Datadog production",
  "kind": "datadog",
  "enabled": true,
  "state": "healthy",
  "created_at": "2026-11-13T14:05:00Z",
  "endpoint": "",
  "options": {"site": "eu1", "tags": "env:prod,team:ai"},
  "services": [],
  "min_level": "info",
  "secret": {"set": true, "last4": "c0de"},
  "last_success_at": "2026-11-13T14:05:00Z",
  "last_error": "",
  "disabled_reason": "",
  "last_test": {
    "at": "2026-11-13T14:05:00Z",
    "ok": true,
    "status": "Datadog answered HTTP 202."
  },
  "today": {
    "lines_sent": 12408,
    "bytes_sent": 1960112,
    "dropped": {"slow": 0, "rate": 0, "daily": 0, "failed": 0}
  },
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/log-streams/{id} #

Delete a log stream

workspace Admin key

Deletes the destination and its counters. Nothing more is sent to it. Logs already stored in Kilby are not touched.

Path parameters

  • iduuidrequired
    The log stream's id.

Response

204
Deleted. There is no body.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key is not an admin key.

  • 404not_found

    There is no such log stream in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/log-streams/{id}
curl -X DELETE "https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64" \
  -H "Authorization: Bearer $KILBY_API_KEY"
No response body.
Runs in your browser against your workspace with a key you paste.
POST/api/v1/log-streams/{id}/test #

Send a test line

workspace Admin key

Delivers one line, once, and reports what the provider answered. Only the HTTP status is reported, never the provider's body. Syslog has no acknowledgement: ok then means the TLS connection was verified and the message was written. A failed test is still a 200 with ok: false. It works on a destination that is turned off, so you can check it before turning it back on. It allows 6 test lines a minute per log stream.

Path parameters

  • iduuidrequired
    The log stream's id.

Response

200
What happened.
  • okbooleanrequired
  • statusinteger
    The HTTP status the provider answered. Absent for syslog and when there was no answer.
  • messagestringrequired
    One sentence.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key is not an admin key.

  • 404not_found

    There is no such log stream in this workspace.

  • 429rate_limited

    More than 6 test lines a minute for this log stream.

  • 503unavailable

    Log forwarding is not available.

POSThttps://onkilby.com/api/v1/log-streams/{id}/test
curl -X POST "https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64/test" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"ok": true, "status": 202, "message": "Datadog answered HTTP 202."}
Runs in your browser against your workspace with a key you paste.

Pull request previews

A web service built from a GitHub repository connected to Kilby can have a preview of every pull request into the branch it deploys: an ordinary service that runs the pull request's code at an address of its own. Kilby builds every new commit of the pull request, keeps one comment on it with the preview's address, and removes the preview when the pull request is closed or merged, or after 7 days without a new commit. Pull requests from forks never get one. Previews copy the service's variables except the ones that look secret, unless copy_secrets is on.

GET/api/v1/services/{id}/previews #

Get a service's previews

view Any key

The service's preview settings, and its previews with their state.

Path parameters

  • iduuidrequired
    The service's id.

Response

200
The service's preview settings and its previews, open ones first.
  • eligiblebooleanrequired
    The service can have previews: a web service built from a GitHub repository connected to Kilby.
  • not_eligible_reasonstringrequired
    Why not, when eligible is false.
  • settingsPreviewSettingsrequired
  • enabledbooleanrequired
    Every pull request into the service's branch gets a preview.
  • copy_secretsbooleanrequired
    Previews also get the variables that look secret (a name with KEY, TOKEN, SECRET or PASSWORD in it, or a value such as an API key or a URL with a password).
  • run_pre_deploybooleanrequired
    Previews run the service's pre-deploy command.
  • planstringrequired
    The instance type of each preview.

    One of starter, standard, pro.

  • variablesarray of stringrequired
    The names of the variables previews get on top of the copied ones. Their values are never returned.
  • previewsarray of Previewrequired
    The open previews and the 50 most recent ones in all.
  • iduuidrequired
  • pull_requestintegerrequired
    The pull request's number.
  • titlestringrequired
  • branchstringrequired
    The pull request's head branch.
  • commitstringrequired
    The latest commit Kilby was told about, or empty.
  • statestringrequired
    active: it runs, or is being built. refused: the pull request got no preview (reason says why). closed: the pull request was closed or merged. expired: no new commit for 7 days. removed: removed in Kilby, previews turned off, or its service deleted.

    One of active, refused, closed, expired, removed.

  • reasonstringrequired
    Why, for every state but active.
  • service_iduuid or nullrequired
    The preview's own service, while it has one.
  • urlstringrequired
    The preview's address while it is active, else empty.
  • statusstringrequired
    The preview service's status while it is active (building, deploying, live, failed), else empty.
  • expires_atdatetimerequired
    When Kilby removes it if no new commit comes.
  • created_atdatetimerequired
  • updated_atdatetimerequired
  • ended_atdatetime or nullrequired
    When it ended; null while it is open.
  • runningintegerrequired
    How many previews the workspace runs now.
  • limitintegerrequired
    How many its plan runs at once: 0 on Hobby, 5 on Pro, 20 on Scale.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The workspace has no service with that id.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/services/{id}/previews
curl "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "eligible": true,
  "not_eligible_reason": "",
  "settings": {
    "enabled": true,
    "copy_secrets": false,
    "run_pre_deploy": false,
    "plan": "starter",
    "variables": ["DATABASE_URL"]
  },
  "previews": [
    {
      "id": "5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350",
      "pull_request": 42,
      "title": "Add the search page",
      "branch": "search-page",
      "commit": "8a2e7d9a74a99a24383b37a774d17ddd931058c0",
      "state": "active",
      "reason": "",
      "service_id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "url": "https://my-api-pr-42-x7k2.apps.kilby.neuramorphic.ai",
      "status": "live",
      "expires_at": "2026-11-13T14:05:00Z",
      "created_at": "2026-11-13T14:05:00Z",
      "updated_at": "2026-11-13T14:05:00Z",
      "ended_at": null
    }
  ],
  "running": 1,
  "limit": 5
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/services/{id}/previews #

Change a service's preview settings

secrets Developer key or higher

Every field is optional. variables replaces the previews' own variables ({} removes them). Previews made from then on use the new settings; a preview that runs keeps what it was made with. Turning previews off removes the previews that run, within a minute.

Path parameters

  • iduuidrequired
    The service's id.

Request body

  • enabledboolean
  • copy_secretsboolean
  • run_pre_deployboolean
  • planstring
    starter, standard or pro.
  • variablesobject of string or null
    Variables previews get on top of the copied ones, which win over them.

Response

200
The service's preview settings and its previews, open ones first.
  • eligiblebooleanrequired
    The service can have previews: a web service built from a GitHub repository connected to Kilby.
  • not_eligible_reasonstringrequired
    Why not, when eligible is false.
  • settingsPreviewSettingsrequired
  • enabledbooleanrequired
    Every pull request into the service's branch gets a preview.
  • copy_secretsbooleanrequired
    Previews also get the variables that look secret (a name with KEY, TOKEN, SECRET or PASSWORD in it, or a value such as an API key or a URL with a password).
  • run_pre_deploybooleanrequired
    Previews run the service's pre-deploy command.
  • planstringrequired
    The instance type of each preview.

    One of starter, standard, pro.

  • variablesarray of stringrequired
    The names of the variables previews get on top of the copied ones. Their values are never returned.
  • previewsarray of Previewrequired
    The open previews and the 50 most recent ones in all.
  • iduuidrequired
  • pull_requestintegerrequired
    The pull request's number.
  • titlestringrequired
  • branchstringrequired
    The pull request's head branch.
  • commitstringrequired
    The latest commit Kilby was told about, or empty.
  • statestringrequired
    active: it runs, or is being built. refused: the pull request got no preview (reason says why). closed: the pull request was closed or merged. expired: no new commit for 7 days. removed: removed in Kilby, previews turned off, or its service deleted.

    One of active, refused, closed, expired, removed.

  • reasonstringrequired
    Why, for every state but active.
  • service_iduuid or nullrequired
    The preview's own service, while it has one.
  • urlstringrequired
    The preview's address while it is active, else empty.
  • statusstringrequired
    The preview service's status while it is active (building, deploying, live, failed), else empty.
  • expires_atdatetimerequired
    When Kilby removes it if no new commit comes.
  • created_atdatetimerequired
  • updated_atdatetimerequired
  • ended_atdatetime or nullrequired
    When it ended; null while it is open.
  • runningintegerrequired
    How many previews the workspace runs now.
  • limitintegerrequired
    How many its plan runs at once: 0 on Hobby, 5 on Pro, 20 on Scale.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The workspace has no service with that id.

  • 422invalid_request

    The service cannot have previews (it is not a web service built from a connected GitHub repository, or it is a preview), an unknown instance type, a bad variable, or a field this endpoint does not know.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/services/{id}/previews
curl -X PATCH "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
{
  "eligible": true,
  "not_eligible_reason": "",
  "settings": {
    "enabled": true,
    "copy_secrets": false,
    "run_pre_deploy": false,
    "plan": "starter",
    "variables": ["DATABASE_URL"]
  },
  "previews": [
    {
      "id": "5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350",
      "pull_request": 42,
      "title": "Add the search page",
      "branch": "search-page",
      "commit": "8a2e7d9a74a99a24383b37a774d17ddd931058c0",
      "state": "active",
      "reason": "",
      "service_id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
      "url": "https://my-api-pr-42-x7k2.apps.kilby.neuramorphic.ai",
      "status": "live",
      "expires_at": "2026-11-13T14:05:00Z",
      "created_at": "2026-11-13T14:05:00Z",
      "updated_at": "2026-11-13T14:05:00Z",
      "ended_at": null
    }
  ],
  "running": 1,
  "limit": 5
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/previews/{id} #

Remove a preview

deploy Developer key or higher

Removes a preview: Kilby takes its service down and says so on the pull request. A new commit to the pull request does not bring it back; reopening the pull request does.

Path parameters

  • iduuidrequired
    The preview's id.

Response

202
The preview, now removed.

Returns a Preview object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    The workspace has no preview with that id.

  • 409conflict

    The preview was already removed, closed or expired.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/previews/{id}
curl -X DELETE "https://onkilby.com/api/v1/previews/5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350",
  "pull_request": 42,
  "title": "Add the search page",
  "branch": "search-page",
  "commit": "8a2e7d9a74a99a24383b37a774d17ddd931058c0",
  "state": "active",
  "reason": "",
  "service_id": "7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
  "url": "https://my-api-pr-42-x7k2.apps.kilby.neuramorphic.ai",
  "status": "live",
  "expires_at": "2026-11-13T14:05:00Z",
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z",
  "ended_at": null
}
Runs in your browser against your workspace with a key you paste.

Slack

Send the events of the workspace to a Slack channel as messages. A destination is an incoming webhook URL from Slack. That URL is a secret (whoever has it can post in the channel), so Kilby stores it encrypted and never returns it: you send it when you create or change a destination, and every answer shows only url_hint. It works with the same events as event webhooks, with the same retries, and turns the destination off after a run of failures.

GET/api/v1/slack-destinations #

List Slack destinations

view Any key

The workspace's Slack destinations with how each is doing. The webhook URLs are never returned.

Response

200
The destinations, and how many a workspace can have.
  • slack_destinationsarray of SlackDestinationrequired
  • iduuidrequired
  • namestringrequired
    Unique within the workspace, up to 60 characters.
  • channelstringrequired
    A label you typed, for example #deploys. Display only: the message goes to the channel the webhook was created for.
  • url_hintstringrequired
    The host and the shape of the URL with every identifier and the secret cut out, such as hooks.slack.com/services/T…/B…/****.
  • eventsarray of stringrequired
    The event types it receives.
  • enabledbooleanrequired
  • statestringrequired
    How it is doing. untested means nothing was sent yet; healthy means the last message got through; failing means the last one did not; disabled means it is turned off (see disabled_reason); sending means a message is on its way.

    One of untested, healthy, failing, disabled, sending.

  • state_detailstringrequired
    The state in one sentence, with the reason when it is failing or disabled.
  • disabled_reasonstring
    Why Kilby turned it off. Absent when it was never turned off by Kilby.
  • last_deliverySlackLastDelivery or nullrequired
    The newest message, or null when none was sent.
  • created_atdatetimerequired
  • updated_atdatetimerequired
  • maxintegerrequired

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/slack-destinations
curl "https://onkilby.com/api/v1/slack-destinations" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "slack_destinations": [
    {
      "id": "b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70",
      "name": "deploys",
      "channel": "#deploys",
      "url_hint": "hooks.slack.com/services/T…/B…/****",
      "events": ["deploy.failed", "cron.run.failed"],
      "enabled": true,
      "state": "healthy",
      "state_detail": "The last message got through.",
      "last_delivery": {
        "status": "succeeded",
        "response_code": 200,
        "at": "2026-11-13T14:05:00Z"
      },
      "created_at": "2026-11-13T14:05:00Z",
      "updated_at": "2026-11-13T14:05:00Z"
    }
  ],
  "max": 5
}
Runs in your browser against your workspace with a key you paste.
POST/api/v1/slack-destinations #

Connect a Slack channel

workspace Admin key

Starts sending the chosen events to a Slack channel. In Slack, create an incoming webhook for the channel and send its URL here: it is checked, encrypted and never shown again. The URL must be https and the host must be hooks.slack.com, unless the operator of this Kilby allowed other hosts for a server that speaks Slack's format. Send a test message with Send a test message to check it. A workspace can have up to 5 destinations.

Also needs

An admin key, created by an admin or the owner of the workspace.

Request body

  • namestringrequired
    A name for the destination.

    up to 60 characters.

  • channelstring
    A label for you, such as #deploys. Display only.

    up to 80 characters.

  • urlurlrequired
    The incoming webhook URL from Slack. Write-only.

    up to 500 characters.

  • eventsarray of stringrequired
    The event types to send. At least one. The list is under Event webhooks.

Response

201
The destination, without its URL.

Returns a SlackDestination object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 409conflict

    The workspace already has 5 destinations, or one with that name.

  • 422invalid_request

    The URL is not a Slack incoming webhook URL, or no event was chosen, or one is not an event type.

  • 429rate_limited

    More than 20 destinations were created in the last hour.

POSThttps://onkilby.com/api/v1/slack-destinations
curl -X POST "https://onkilby.com/api/v1/slack-destinations" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "deploys",
  "channel": "#deploys",
  "url": "https://hooks.slack.com/services/T000/B000/xxxx",
  "events": ["deploy.failed", "cron.run.failed"]
}'
{
  "id": "b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70",
  "name": "deploys",
  "channel": "#deploys",
  "url_hint": "hooks.slack.com/services/T…/B…/****",
  "events": ["deploy.failed", "cron.run.failed"],
  "enabled": true,
  "state": "untested",
  "state_detail": "Nothing was sent yet.",
  "last_delivery": {
    "status": "succeeded",
    "response_code": 200,
    "at": "2026-11-13T14:05:00Z"
  },
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/slack-destinations/{id} #

Get a Slack destination

view Any key

One destination. Its URL is never returned.

Path parameters

  • iduuidrequired
    The Slack destination's id.

Response

200
The destination.

Returns a SlackDestination object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/slack-destinations/{id}
curl "https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "id": "b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70",
  "name": "deploys",
  "channel": "#deploys",
  "url_hint": "hooks.slack.com/services/T…/B…/****",
  "events": ["deploy.failed", "cron.run.failed"],
  "enabled": true,
  "state": "healthy",
  "state_detail": "The last message got through.",
  "last_delivery": {
    "status": "succeeded",
    "response_code": 200,
    "at": "2026-11-13T14:05:00Z"
  },
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
PATCH/api/v1/slack-destinations/{id} #

Change a Slack destination

workspace Admin key

Changes the name, the channel label or the events, replaces the webhook URL, or turns the destination on or off. Send only what changes. Turning a destination back on, or replacing its URL, resets its count of failures.

Also needs

An admin key, created by an admin or the owner of the workspace.

Path parameters

  • iduuidrequired
    The Slack destination's id.

Request body

  • namestring
    A new name.

    up to 60 characters.

  • channelstring
    A new label.

    up to 80 characters.

  • urlurl
    A new incoming webhook URL. Write-only; leave it out to keep the current one.
  • eventsarray of string
    The event types to send. At least one. The list is under Event webhooks.
  • enabledboolean
    false pauses it; true resumes it.

Response

200
The destination after the change.

Returns a SlackDestination object.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 409conflict

    Another destination has that name.

  • 422invalid_request

    A field is not valid.

  • 429rate_limited

    More than 300 requests a minute for this key.

PATCHhttps://onkilby.com/api/v1/slack-destinations/{id}
curl -X PATCH "https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70" \
  -H "Authorization: Bearer $KILBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
{
  "id": "b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70",
  "name": "deploys",
  "channel": "#deploys",
  "url_hint": "hooks.slack.com/services/T…/B…/****",
  "events": ["deploy.failed", "cron.run.failed"],
  "enabled": false,
  "state": "healthy",
  "state_detail": "The last message got through.",
  "last_delivery": {
    "status": "succeeded",
    "response_code": 200,
    "at": "2026-11-13T14:05:00Z"
  },
  "created_at": "2026-11-13T14:05:00Z",
  "updated_at": "2026-11-13T14:05:00Z"
}
Runs in your browser against your workspace with a key you paste.
DELETE/api/v1/slack-destinations/{id} #

Delete a Slack destination

workspace Admin key

Deletes the destination and its history. It receives no more messages. The webhook stays in Slack: remove it there too if you no longer need it.

Also needs

An admin key, created by an admin or the owner of the workspace.

Path parameters

  • iduuidrequired
    The Slack destination's id.

Response

204
Deleted. There is no body.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

DELETEhttps://onkilby.com/api/v1/slack-destinations/{id}
curl -X DELETE "https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70" \
  -H "Authorization: Bearer $KILBY_API_KEY"
No response body.
Runs in your browser against your workspace with a key you paste.
POST/api/v1/slack-destinations/{id}/test #

Send a test message

workspace Admin key

Posts one test message in the channel. It is delivered once, without retries, within a few seconds, and does not count against the destination; see the result in List deliveries to a Slack destination.

Also needs

An admin key, created by an admin or the owner of the workspace.

Path parameters

  • iduuidrequired
    The Slack destination's id.

Response

202
The test message is queued.
  • event_iduuidrequired
  • typestringrequired
    Always test.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 10 test messages a minute for this destination.

POSThttps://onkilby.com/api/v1/slack-destinations/{id}/test
curl -X POST "https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/test" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{"event_id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65", "type": "test"}
Runs in your browser against your workspace with a key you paste.
GET/api/v1/slack-destinations/{id}/deliveries #

List deliveries to a Slack destination

view Any key

The last 100 messages sent to the destination, newest first, with the status code Slack answered, what went wrong in one sentence, how long it took and how many attempts were made. A message is tried again after 1 minute, 5 minutes and 30 minutes when Slack is busy (429, with its Retry-After honored) or does not answer, then given up. An answer that says the webhook or the message is wrong (400, 403, 404, 410) is not retried.

Path parameters

  • iduuidrequired
    The Slack destination's id.

Response

200
The deliveries.
  • deliveriesarray of Deliveryrequired
  • max_attemptsintegerrequired
    How many times one message is tried.

Errors

  • 401unauthorized

    The key is missing, not valid, revoked or expired (key_expired).

  • 403forbidden

    The key's role does not allow this.

  • 404not_found

    No such resource in this workspace.

  • 429rate_limited

    More than 300 requests a minute for this key.

GEThttps://onkilby.com/api/v1/slack-destinations/{id}/deliveries
curl "https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/deliveries" \
  -H "Authorization: Bearer $KILBY_API_KEY"
{
  "deliveries": [
    {
      "id": "2e9b4c71-6d3a-4f08-b1c5-8a7e0d9f3c42",
      "event_id": "b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65",
      "event_type": "deploy.failed",
      "status": "succeeded",
      "attempts": 1,
      "response_code": 200,
      "duration_ms": 184,
      "created_at": "2026-11-13T14:05:00Z",
      "last_attempt_at": "2026-11-13T14:05:00Z"
    }
  ],
  "max_attempts": 4
}
Runs in your browser against your workspace with a key you paste.

Objects

The shapes the API returns, by name. A field marked or null is always there and can be null; a field that is not marked required can be missing.

ErrorEvery error has this shape. Branch on code, show message to people.
  • errorobjectrequired
  • codestringrequired
    A stable machine-readable name, such as invalid_request or forbidden.

    One of bad_request, unauthorized, key_expired, forbidden, two_factor_required, not_found, conflict, not_connected, invalid_request, rate_limited, internal, github_unavailable, unavailable.

  • messagestringrequired
    A sentence for people. It may change; do not match on it.
ServiceA web service, private service, background worker or cron job.
  • iduuidrequired
    The service's id. Use it in the paths of every other endpoint.
  • namestringrequired
    Unique within the workspace. It is also the service's internal host name.
  • typestringrequired
    What kind of service it is.

    One of web, private, worker, cron.

  • imagestringrequired
    The container image that runs. For a service built from Git it is the name of the latest build's image, service:version (for example api:42434fb), which is not a reference to pull from anywhere else.
  • commandstring
    Replaces the image's start command. Only present when set.
  • schedulestring
    Five cron fields, in UTC. Only present on cron jobs.
  • portinteger or nullrequired
    The port the service listens on. null for workers and cron jobs.
  • planstringrequired
    The instance type.

    One of starter, standard, pro.

  • statusstringrequired
    Where the service is now. Poll it after a change. failed means the latest deploy failed or the service stopped working: without a disk the previous version keeps serving while instances_running is above 0, with a disk it does not.

    One of pending, building, deploying, live, scheduled, failed, suspended, deleting.

  • status_messagestringrequired
    Why the service is in this status, in one sentence, when that helps. Empty otherwise.
  • suspendedbooleanrequired
    true while the service is suspended.
  • urlurl
    The Kilby address of a web service (https://<name>-<suffix>.apps...). It stays the Kilby address when a custom domain is the primary address, so clients that read it keep working: read primary_domain for the address the service shows as its own.
  • internal_addressstring
    host:port for other services in the same workspace. Only present when the service has a port.
  • created_atdatetimerequired
  • updated_atdatetimerequired
  • registry_credential_iduuid or nullrequired
    The registry credentials used to pull the image, or null for a public image.
  • health_check_pathstringrequired
    An HTTP path a deploy must answer before it goes live. Empty: the port only has to accept connections.
  • instancesintegerrequired
    The number of instances, or the minimum when autoscaling.
  • autoscalingAutoscaling or nullrequired
    null when the number of instances is fixed.
  • minintegerrequired
    At least this many instances.

    1 to 10.

  • maxintegerrequired
    At most this many instances.

    2 to 10, at least min.

  • target_cpu_percentintegerrequired
    Add instances above this average CPU use, remove them below it.

    10 to 95.

  • diskDisk or nullrequired
    null when the service has no disk.
  • mount_pathstringrequired
    Where it appears inside the container, for example /data.
  • size_gbintegerrequired
    Size in GB. It can grow, once every 6 hours, but not shrink.

    1 to 50.

  • instances_runningintegerrequired
    Instances that are ready now.
  • instances_desiredintegerrequired
    Instances Kilby is trying to run.
  • pre_deploy_commandstringrequired
    The command that runs once before every deploy. Empty when there is none.
  • pre_deploy_timeout_secondsintegerrequired
    The most time that command may take.
  • sourceSource or nullrequired
    Where a service built from Git comes from. null for a service that runs an image.
  • kindstringrequired
    git for a repository reached through the GitHub connection, public_git for a public repository built from its archive.

    One of git, public_git.

  • urlurl
    public_git only: the repository's address.
  • hoststring
    public_git only: github.com, gitlab.com or bitbucket.org (the hosts this Kilby allows).
  • refstring
    public_git only: the branch, tag or commit that is built. HEAD is the repository's default branch.
  • auto_checkboolean
    public_git only: Kilby checks for new commits every 15 minutes and builds them. Off by default.
  • installation_idintegerrequired
    The GitHub connection of this workspace that can read the repository.
  • repostringrequired
    owner/name.
  • branchstringrequired
    The branch Kilby builds.
  • root_dirstringrequired
    The folder of the repository that is built. Empty is the root.
  • dockerfile_pathstringrequired
    The Dockerfile to use, relative to root_dir. Empty: Kilby decides.
  • auto_deploybooleanrequired
    Build and deploy on a push to the branch that changes a file in the service's folder (root_dir; the whole repository when it is empty).
  • versionstringrequired
    Changes whenever the source settings do. Send it back in PATCH /services/{id} to refuse the change if someone edited them meanwhile.
  • build_planBuildPlan
    The plan builds use: commands, port and runtime.
  • root_dirstringrequired
    The folder that is built. Empty is the repository root.
  • strategystringrequired
    Whether Kilby builds your Dockerfile or writes one.

    One of dockerfile, generated.

  • runtimestringrequired

    One of node, python, go, static, docker.

  • frameworkstringrequired
    For example next, vite, express, fastapi or flask. Empty when none was recognised.
  • dockerfile_pathstringrequired
    Only for strategy dockerfile, relative to root_dir.
  • install_commandstringrequired
  • build_commandstringrequired
  • start_commandstringrequired
  • portintegerrequired
    0 for a worker.
  • health_pathstringrequired
    Empty when there is no good guess.
  • plan_idstringrequired
    The instance type Kilby suggests.

    One of starter, standard, pro.

  • envarray of objectrequired
    Variables the code reads, found in files such as .env.example.
  • notesarray of stringrequired
    What was found and why, in plain sentences.
  • warningsarray of stringrequired
    What might go wrong.
  • candidatesarray of objectrequired
    Other buildable folders, in a monorepo.
  • kindstring
    A suggestion for the service type.

    One of web, worker.

  • versionstring
    The runtime version the image uses.
  • package_managerstring
    For example npm, pnpm, pip or uv.
  • output_dirstring
    The folder that holds the build output.
  • root_routeboolean
    The code routes /, and no health route was found: the dashboard offers / as the health check. Only present when true.
  • latest_buildBuild
    The most recent build. Only present in the answer to creating a service.
  • environmentEnvironmentRef
    Where the service is listed: its environment and the project of that environment. It only organizes: it changes nothing about how the service runs, and a service that was never placed is in the Default project, in Production.
  • iduuidrequired
    The environment's id.
  • namestringrequired
    The environment's name, such as Production.
  • defaultbooleanrequired
    true for Production of the Default project, where everything that was never placed is.
  • projectobjectrequired
    The project the environment belongs to.
  • iduuidrequired
  • namestringrequired
  • auto_concurrencybooleanrequired
    Whether Kilby sets WEB_CONCURRENCY for the service from its instance type. Always false for workers and cron jobs.
  • render_compatbooleanrequired
    Whether Kilby also sets Render's variables (RENDER=true, RENDER_EXTERNAL_HOSTNAME...) with this service's values.
  • stop_firstbooleanrequired
    Whether each deploy stops the old instance before it starts the new one, so the two never run together. Only background workers and private services can turn it on; a service with a disk always deploys that way.
  • read_only_rootbooleanrequired
    Whether the container's root filesystem is read-only, with a writable /tmp. Off unless it was switched on.
  • maintenancebooleanrequired
    true while maintenance mode is on: visitors of a web service see the maintenance page and the instances keep running. Always false for services that are not web services, and while the platform does not show pages of its own (see PUT /services/{id}/maintenance).
  • maintenance_messagestringrequired
    The message the maintenance page shows, plain text of up to 280 characters. It is kept while maintenance mode is off.
  • primary_domainstring
    Web services: the address the service shows as its own (the dashboard's header and Open): its Kilby address, or one of its custom domains that is active, serves the service and points to Kilby. Without a choice, the first custom domain to go live; a chosen domain that is not live right now is never reported here: the Kilby address is.
  • primary_domain_choicestring or null
    Web services: the address chosen as primary with PATCH /services/{id}/primary-domain, or null when none was chosen.
  • primary_domain_notestring
    Web services, only when the chosen domain is not used: why (removed, redirecting, without a certificate, not pointing to Kilby).
AutoscalingInstances follow CPU use between a minimum and a maximum.
  • minintegerrequired
    At least this many instances.

    1 to 10.

  • maxintegerrequired
    At most this many instances.

    2 to 10, at least min.

  • target_cpu_percentintegerrequired
    Add instances above this average CPU use, remove them below it.

    10 to 95.

DiskA persistent disk that keeps files across deploys and restarts. A service with a disk is down for a short time on every deploy and every change that restarts it, because the disk must be released before the new instance starts, and a failed deploy leaves it not running.
  • mount_pathstringrequired
    Where it appears inside the container, for example /data.
  • size_gbintegerrequired
    Size in GB. It can grow, once every 6 hours, but not shrink.

    1 to 50.

PublicCommitThe commit a public repository's archive is of.
  • shastringrequired
    40 hex characters, or empty when the host's archive does not say.
  • shortstringrequired
    The first 7 characters.
  • knownbooleanrequired
    false when the archive does not say which commit it is of: Kilby shows it as unknown and cannot tell when it changes.
  • urlurlrequired
    The commit on the host's website. Empty when unknown.
  • howstring
    How Kilby learned the commit: the archive's header, or the archive's folder name. Left out when unknown.
SourceWhere a service built from Git comes from.
  • kindstringrequired
    git for a repository reached through the GitHub connection, public_git for a public repository built from its archive.

    One of git, public_git.

  • urlurl
    public_git only: the repository's address.
  • hoststring
    public_git only: github.com, gitlab.com or bitbucket.org (the hosts this Kilby allows).
  • refstring
    public_git only: the branch, tag or commit that is built. HEAD is the repository's default branch.
  • auto_checkboolean
    public_git only: Kilby checks for new commits every 15 minutes and builds them. Off by default.
  • installation_idintegerrequired
    The GitHub connection of this workspace that can read the repository.
  • repostringrequired
    owner/name.
  • branchstringrequired
    The branch Kilby builds.
  • root_dirstringrequired
    The folder of the repository that is built. Empty is the root.
  • dockerfile_pathstringrequired
    The Dockerfile to use, relative to root_dir. Empty: Kilby decides.
  • auto_deploybooleanrequired
    Build and deploy on a push to the branch that changes a file in the service's folder (root_dir; the whole repository when it is empty).
  • versionstringrequired
    Changes whenever the source settings do. Send it back in PATCH /services/{id} to refuse the change if someone edited them meanwhile.
  • build_planBuildPlan
    The plan builds use: commands, port and runtime.
  • root_dirstringrequired
    The folder that is built. Empty is the repository root.
  • strategystringrequired
    Whether Kilby builds your Dockerfile or writes one.

    One of dockerfile, generated.

  • runtimestringrequired

    One of node, python, go, static, docker.

  • frameworkstringrequired
    For example next, vite, express, fastapi or flask. Empty when none was recognised.
  • dockerfile_pathstringrequired
    Only for strategy dockerfile, relative to root_dir.
  • install_commandstringrequired
  • build_commandstringrequired
  • start_commandstringrequired
  • portintegerrequired
    0 for a worker.
  • health_pathstringrequired
    Empty when there is no good guess.
  • plan_idstringrequired
    The instance type Kilby suggests.

    One of starter, standard, pro.

  • envarray of objectrequired
    Variables the code reads, found in files such as .env.example.
  • namestringrequired
  • examplestringrequired
  • secretbooleanrequired
    Looks like a secret: its value is not shown.
  • buildboolean
    Offered as a build variable.
  • notesarray of stringrequired
    What was found and why, in plain sentences.
  • warningsarray of stringrequired
    What might go wrong.
  • candidatesarray of objectrequired
    Other buildable folders, in a monorepo.
  • root_dirstringrequired
  • runtimestringrequired
  • frameworkstringrequired
  • labelstringrequired
  • build_commandstringrequired
  • dockerfile_pathstringrequired
  • kindstring
    A suggestion for the service type.

    One of web, worker.

  • versionstring
    The runtime version the image uses.
  • package_managerstring
    For example npm, pnpm, pip or uv.
  • output_dirstring
    The folder that holds the build output.
  • root_routeboolean
    The code routes /, and no health route was found: the dashboard offers / as the health check. Only present when true.
  • latest_buildBuild
    The most recent build. Only present in the answer to creating a service.
SourceInputWhere to build a service from, in the body of POST /services.
  • kindstringrequired
    git for a repository the GitHub connection can read, public_git for a public repository built from its archive (no GitHub connection).

    One of git, public_git.

  • urlurl
    kind public_git: the https address of the repository, on one of the hosts this Kilby allows. Required for public_git.
  • refstring
    kind public_git: the branch, tag or commit to build.

    Default the repository's default branch.

  • auto_checkboolean
    kind public_git: check for new commits every 15 minutes and build them. Off by default; a workspace can turn it on for a few services.

    Default false.

  • installation_idinteger
    kind git: the GitHub connection of this workspace that can read the repository.
  • repostring
    kind git: owner/name.
  • branchstring
    The branch to build and to follow.

    Default the repository's default branch.

  • root_dirstring
    The folder to build, for a monorepo. Empty is the repository root.
  • dockerfile_pathstring
    A Dockerfile to use, relative to root_dir. Empty: Kilby uses the Dockerfile it finds, or writes one.
  • build_planobject
    The build plan the detector proposed, to build exactly what was shown. Leave it out to let Kilby detect it.
  • auto_deployboolean
    Build and deploy on a push to the branch that changes a file in the service's folder (root_dir; the whole repository when it is empty).

    Default true.

  • build_envobject of string
    Variables available while building (not at runtime). Their values are stored encrypted and never returned.
SourceEditThe source settings to change, in the body of PATCH /services/{id}. Everything is optional: what you leave out stays.
  • versionstring
    The source.version you read. If the settings changed since, the answer is 409 and nothing is written.
  • branchstring
    The branch to build and follow. Kilby checks it can read it.
  • root_dirstring
    The folder to build. Kilby reads the new folder again and takes its plan; commands in the same request win over it.
  • dockerfile_pathstring
    A Dockerfile, relative to root_dir. An empty string goes back to the default.
  • install_commandstring
  • build_commandstring
    An empty string clears it.
  • start_commandstring
  • portinteger
    A number, or a number written as a string. A service built from Git has one port.
  • health_pathstring
    The health check path, as for health_check_path.
  • auto_deployboolean
    Build and deploy on a push that changes a file in the service's folder. Not for a public_git service: it has no push webhook.
  • auto_checkboolean
    public_git only: check for new commits every 15 minutes.
  • build_planBuildPlan
    A whole plan, as returned by GET /git/plan or GET /git/public/plan.
  • root_dirstringrequired
    The folder that is built. Empty is the repository root.
  • strategystringrequired
    Whether Kilby builds your Dockerfile or writes one.

    One of dockerfile, generated.

  • runtimestringrequired

    One of node, python, go, static, docker.

  • frameworkstringrequired
    For example next, vite, express, fastapi or flask. Empty when none was recognised.
  • dockerfile_pathstringrequired
    Only for strategy dockerfile, relative to root_dir.
  • install_commandstringrequired
  • build_commandstringrequired
  • start_commandstringrequired
  • portintegerrequired
    0 for a worker.
  • health_pathstringrequired
    Empty when there is no good guess.
  • plan_idstringrequired
    The instance type Kilby suggests.

    One of starter, standard, pro.

  • envarray of objectrequired
    Variables the code reads, found in files such as .env.example.
  • namestringrequired
  • examplestringrequired
  • secretbooleanrequired
    Looks like a secret: its value is not shown.
  • buildboolean
    Offered as a build variable.
  • notesarray of stringrequired
    What was found and why, in plain sentences.
  • warningsarray of stringrequired
    What might go wrong.
  • candidatesarray of objectrequired
    Other buildable folders, in a monorepo.
  • root_dirstringrequired
  • runtimestringrequired
  • frameworkstringrequired
  • labelstringrequired
  • build_commandstringrequired
  • dockerfile_pathstringrequired
  • kindstring
    A suggestion for the service type.

    One of web, worker.

  • versionstring
    The runtime version the image uses.
  • package_managerstring
    For example npm, pnpm, pip or uv.
  • output_dirstring
    The folder that holds the build output.
  • root_routeboolean
    The code routes /, and no health route was found: the dashboard offers / as the health check. Only present when true.
  • build_envobject of string or null
    Build variables to set. They merge into the current ones, and null removes one. Needs the secrets permission.
  • planstring
    The instance type from the next deploy. A service that was never built cannot change it.

    One of starter, standard, pro.

GitInstallationA GitHub account (person or organisation) connected to the workspace.
  • idintegerrequired
    Use it as installation_id and installation.
  • accountstringrequired
    The GitHub login.
  • typestringrequired

    One of User, Organization.

  • repository_selectionstringrequired
    Whether the GitHub App can read all of the account's repositories or only selected ones.

    One of all, selected.

  • suspendedbooleanrequired
    true while GitHub has suspended the installation.
  • linked_bystringrequired
    Who connected it to this workspace.
  • linked_atdatetimerequired
GitRepoA repository the connected account lets Kilby read.
  • idintegerrequired
  • full_namestringrequired
    owner/name.
  • privatebooleanrequired
  • default_branchstringrequired
  • pushed_atdatetimerequired
    The latest push.
  • installation_idintegerrequired
  • ownerstringrequired
GitCommitA commit of a branch.
  • shastringrequired
  • messagestringrequired
    The first line of the commit message.
  • authorstringrequired
  • urlurlrequired
    The commit on GitHub.
  • atdatetimerequired
BuildPlanWhat Kilby understood about a repository: how it builds and runs it.
  • root_dirstringrequired
    The folder that is built. Empty is the repository root.
  • strategystringrequired
    Whether Kilby builds your Dockerfile or writes one.

    One of dockerfile, generated.

  • runtimestringrequired

    One of node, python, go, static, docker.

  • frameworkstringrequired
    For example next, vite, express, fastapi or flask. Empty when none was recognised.
  • dockerfile_pathstringrequired
    Only for strategy dockerfile, relative to root_dir.
  • install_commandstringrequired
  • build_commandstringrequired
  • start_commandstringrequired
  • portintegerrequired
    0 for a worker.
  • health_pathstringrequired
    Empty when there is no good guess.
  • plan_idstringrequired
    The instance type Kilby suggests.

    One of starter, standard, pro.

  • envarray of objectrequired
    Variables the code reads, found in files such as .env.example.
  • namestringrequired
  • examplestringrequired
  • secretbooleanrequired
    Looks like a secret: its value is not shown.
  • buildboolean
    Offered as a build variable.
  • notesarray of stringrequired
    What was found and why, in plain sentences.
  • warningsarray of stringrequired
    What might go wrong.
  • candidatesarray of objectrequired
    Other buildable folders, in a monorepo.
  • root_dirstringrequired
  • runtimestringrequired
  • frameworkstringrequired
  • labelstringrequired
  • build_commandstringrequired
  • dockerfile_pathstringrequired
  • kindstring
    A suggestion for the service type.

    One of web, worker.

  • versionstring
    The runtime version the image uses.
  • package_managerstring
    For example npm, pnpm, pip or uv.
  • output_dirstring
    The folder that holds the build output.
  • root_routeboolean
    The code routes /, and no health route was found: the dashboard offers / as the health check. Only present when true.
CommitA commit that was built.
  • shastringrequired
    The full commit id.
  • messagestringrequired
    The first line of the commit message.
  • authorstringrequired
  • branchstringrequired
BuildOne build of a service from Git.
  • iduuidrequired
  • numberintegerrequired
    1, 2, 3 within the service. A build can be addressed by its number.
  • triggerstringrequired
    What started it.

    One of push, manual, rebuild.

  • statusstringrequired

    One of queued, running, succeeded, failed, canceled.

  • stagestringrequired
    The stage it is in, or failed in.

    One of clone, detect, build, push, release, health, live.

  • commitCommitrequired
  • shastringrequired
    The full commit id.
  • messagestringrequired
    The first line of the commit message.
  • authorstringrequired
  • branchstringrequired
  • stagesarray of BuildStagerequired
    Every stage with its own status and times.
  • namestringrequired

    One of clone, detect, build, push, release, health, live.

  • statusstringrequired

    One of pending, running, succeeded, failed, skipped, canceled.

  • started_atdatetime or nullrequired
  • finished_atdatetime or nullrequired
  • notestring
    A short remark, such as how many bytes were pushed.
  • errorstring
    One sentence when it failed.
  • diagnosisDiagnosis or nullrequired
    Why it failed and what to change, when Kilby can tell.
  • image_digeststring
    The digest of the image it pushed.
  • created_bystring
    Who started it, for a manual build.
  • created_atdatetimerequired
  • started_atdatetime or nullrequired
  • finished_atdatetime or nullrequired
BuildStageOne stage of a build.
  • namestringrequired

    One of clone, detect, build, push, release, health, live.

  • statusstringrequired

    One of pending, running, succeeded, failed, skipped, canceled.

  • started_atdatetime or nullrequired
  • finished_atdatetime or nullrequired
  • notestring
    A short remark, such as how many bytes were pushed.
DiagnosisWhy a build failed, in plain English.
  • codestringrequired
    A stable machine name, for example no_dockerfile.
  • titlestringrequired
    One sentence: what went wrong.
  • detailstringrequired
    A few sentences: why, and what to check.
  • fixesarray of Fixrequired
    Changes that may solve it.
  • labelstringrequired
  • fieldstringrequired
    The setting to change, such as root_dir, dockerfile_path or port.
  • valuestringrequired
FixA proposed change to one setting of the service.
  • labelstringrequired
  • fieldstringrequired
    The setting to change, such as root_dir, dockerfile_path or port.
  • valuestringrequired
DeployOne deploy of a service.
  • iduuidrequired
  • imagestringrequired
    The image it ran.
  • triggerstringrequired
    What started it.

    One of create, update, manual, resume, rollback, hook, git.

  • statusstringrequired

    One of queued, deploying, live, failed, superseded, canceled.

  • messagestringrequired
    Why it failed, in one sentence. Empty otherwise.
  • created_atdatetimerequired
  • finished_atdatetime or nullrequired
  • titlestringrequired
    What a list shows for the deploy: the first line of the commit for a deploy from Git, the image tag or digest, "Rollback to ...", what a settings change changed, or "Manual redeploy by ...". Plain text of at most 120 characters, never a variable's value. It is kept with the deploy and does not change.
  • pre_deployPreDeploy or nullrequired
    The run of the service's pre-deploy command for this deploy. null when the deploy had none.
  • commandstringrequired
    The command, as it was when the deploy was queued.
  • statusstringrequired
    running, then succeeded (it exited 0 and the rollout went on), failed (it exited with an error), timeout (it ran past the limit) or skipped (a manual redeploy asked to skip it). canceled: a newer deploy replaced this one while it ran. A failed or timeout run fails the deploy before the new version starts.

    One of running, succeeded, failed, timeout, skipped, canceled.

  • messagestringrequired
    What happened, in one sentence, when it did not succeed. Empty otherwise.
  • started_atdatetime or nullrequired
  • finished_atdatetime or nullrequired
  • exit_codeinteger or nullrequired
    The command's exit code. null when it did not get to run, or was stopped at the limit.
  • outputstringrequired
    The last 200 lines it printed, up to 32 KB, with every value of the service's environment that looks like a secret replaced by ***.
PreDeployThe pre-deploy command of one deploy: what ran before the new version started.
  • commandstringrequired
    The command, as it was when the deploy was queued.
  • statusstringrequired
    running, then succeeded (it exited 0 and the rollout went on), failed (it exited with an error), timeout (it ran past the limit) or skipped (a manual redeploy asked to skip it). canceled: a newer deploy replaced this one while it ran. A failed or timeout run fails the deploy before the new version starts.

    One of running, succeeded, failed, timeout, skipped, canceled.

  • messagestringrequired
    What happened, in one sentence, when it did not succeed. Empty otherwise.
  • started_atdatetime or nullrequired
  • finished_atdatetime or nullrequired
  • exit_codeinteger or nullrequired
    The command's exit code. null when it did not get to run, or was stopped at the limit.
  • outputstringrequired
    The last 200 lines it printed, up to 32 KB, with every value of the service's environment that looks like a secret replaced by ***.
DeployRecordA deploy, with the deploy it rolled back to when it is a rollback.
  • iduuidrequired
  • imagestringrequired
  • triggerstringrequired

    One of create, update, manual, resume, rollback, hook, git.

  • statusstringrequired

    One of queued, deploying, live, failed, superseded, canceled.

  • messagestringrequired
  • reasonstring
    Why a failed deploy failed.

    One of crash, oom, probe, quota, image, timeout, predeploy.

  • rollback_ofuuid
    The deploy whose settings this one restores.
  • created_atdatetimerequired
  • finished_atdatetime or nullrequired
  • titlestringrequired
    What a list shows for the deploy: "Rollback to ..." for a rollback. See Deploy.
  • environment_restoredboolean
    Only in the answer to a rollback: whether the environment variables of the earlier deploy were restored.
RollbackPreviewWhat a rollback would change. Variable values are never in it.
  • deployRollbackDeployrequired
    The deploy it would go back to.
  • iduuidrequired
  • imagestringrequired
    The exact image it ran.
  • triggerstringrequired
  • statusstringrequired
  • created_atdatetimerequired
  • finished_atdatetime or nullrequired
  • can_roll_backbooleanrequired
    false when the rollback cannot go ahead; blocked_reason says why.
  • blocked_reasonstring
    Why it cannot go ahead.
  • generationintegerrequired
    The version of the service this preview was made from.
  • settingsarray of RollbackSettingrequired
    Image, start command, port or schedule, instance type, health check path, instances and the disk, in this order.
  • fieldstringrequired
    image, command, port, schedule, plan, health, instances or disk.

    One of image, command, port, schedule, plan, health, instances, disk.

  • labelstringrequired
  • currentstringrequired
    What the service has now.
  • afterstringrequired
    What it has after the rollback.
  • changesbooleanrequired
    The two differ.
  • keptbooleanrequired
    A rollback leaves it as it is.
  • notestring
    Why it is kept, or what is not known.
  • environmentRollbackEnvironmentrequired
    The environment variables that would change: names only.
  • recordedbooleanrequired
    The deploy remembers its variables. false: they stay as they are now.
  • readablebooleanrequired
    The stored copies could be opened. false: nothing is compared or restored.
  • restore_defaultbooleanrequired
    The variables are restored when restore_env is left out.
  • addedarray of stringrequired
    Names set by the earlier deploy and not set now.
  • removedarray of stringrequired
    Names set now and not set by the earlier deploy.
  • changedarray of stringrequired
    Names set in both with different values.
  • unchangedintegerrequired
    How many variables are the same.
  • notestring
    Why nothing is restored, when that is so.
  • if_restoredstring
    What happens with restore_env true.
  • if_keptstring
    What happens with restore_env false.
  • strategystringrequired
    How the service is replaced.

    One of rolling_update, recreate, next_run.

  • notesarray of stringrequired
    What else happens, in sentences.
RollbackDeployThe deploy a rollback would go back to.
  • iduuidrequired
  • imagestringrequired
    The exact image it ran.
  • triggerstringrequired
  • statusstringrequired
  • created_atdatetimerequired
  • finished_atdatetime or nullrequired
RollbackSettingOne setting of the service, now and after the rollback.
  • fieldstringrequired
    image, command, port, schedule, plan, health, instances or disk.

    One of image, command, port, schedule, plan, health, instances, disk.

  • labelstringrequired
  • currentstringrequired
    What the service has now.
  • afterstringrequired
    What it has after the rollback.
  • changesbooleanrequired
    The two differ.
  • keptbooleanrequired
    A rollback leaves it as it is.
  • notestring
    Why it is kept, or what is not known.
RollbackEnvironmentWhich environment variables a rollback would add, remove or change, by name.
  • recordedbooleanrequired
    The deploy remembers its variables. false: they stay as they are now.
  • readablebooleanrequired
    The stored copies could be opened. false: nothing is compared or restored.
  • restore_defaultbooleanrequired
    The variables are restored when restore_env is left out.
  • addedarray of stringrequired
    Names set by the earlier deploy and not set now.
  • removedarray of stringrequired
    Names set now and not set by the earlier deploy.
  • changedarray of stringrequired
    Names set in both with different values.
  • unchangedintegerrequired
    How many variables are the same.
  • notestring
    Why nothing is restored, when that is so.
  • if_restoredstring
    What happens with restore_env true.
  • if_keptstring
    What happens with restore_env false.
RunOne run of a cron job.
  • namestringrequired
    The run's name. Pass it to nothing: it is only for reading.
  • statusstringrequired

    One of running, succeeded, failed.

  • messagestringrequired
    Why it failed, in one sentence. Empty otherwise.
  • manualbooleanrequired
    true when someone started it with the trigger endpoint.
  • started_atdatetimerequired
  • finished_atdatetime or nullrequired
DatabaseA managed Postgres database.
  • iduuidrequired
  • namestringrequired
  • enginestringrequired
    Always postgres.

    One of postgres.

  • versionstringrequired
    The major version.
  • planstringrequired

    One of starter, standard, pro.

  • storage_gbintegerrequired
    The size of the disk now, in GB.
  • statusstringrequired

    One of creating, available, updating, failed, deleting.

  • status_messagestringrequired
  • hoststringrequired
    The host name other services in the workspace connect to.
  • portintegerrequired
  • databasestringrequired
    The database name.
  • userstringrequired
    The user name.
  • internal_urlstring
    A connection URL that includes the password. Only in the answers that create a database and in GET /databases/{id} for keys that may see secrets.
  • created_atdatetimerequired
  • environmentEnvironmentRef
    Where the database is listed: its environment and the project of that environment.
  • iduuidrequired
    The environment's id.
  • namestringrequired
    The environment's name, such as Production.
  • defaultbooleanrequired
    true for Production of the Default project, where everything that was never placed is.
  • projectobjectrequired
    The project the environment belongs to.
  • iduuidrequired
  • namestringrequired
  • autogrowbooleanrequired
    true when the disk grows by itself when it reaches 90%.
  • autogrow_max_gbintegerrequired
    The largest size the disk may grow to. 0 when it was never turned on.
  • disk_used_percentinteger
    How full the disk was when it was last measured. Only there while autogrow is on and the database has been measured.
  • disk_checked_atdatetime
    When the disk was last measured.
  • high_availabilitybooleanrequired
    true when the database runs a standby on another node and fails over to it by itself. Always false while the platform does not offer it.
  • synchronous_replicationbooleanrequired
    true when each commit waits for the standby. Only with high availability.
  • read_only_hoststring
    With high availability: the host name of the read-only service, which reaches the standby only. It can be a little behind the primary and has nothing to answer while the standby is down. The read-write host is the same with or without a standby.
  • standbyobject
    With high availability, in GET /databases/{id} and PATCH /databases/{id}: what Kilby last saw of the primary and the standby. There is no replication lag in it: the cluster's status does not report one.
  • statestringrequired
    creating: being built. in_sync: running and streaming from the primary. catching_up: running, not caught up. down: not running. unknown: not looked at yet.

    One of creating, in_sync, catching_up, down, unknown.

  • primary_instancestringrequired
    The pod that is the primary.
  • standby_instancestringrequired
    The pod that is the standby. Empty while it is being created.
  • primary_zonestring
    The availability zone of the primary's node.
  • standby_zonestring
    The availability zone of the standby's node. When it is the same as the primary's, a zone outage takes both.
  • checked_atdatetime
    When Kilby last looked.
  • out_of_sync_sincedatetime
    Present while the standby is not in sync.
  • last_failoverobject
    The last time the primary changed hands.
  • atdatetimerequired
  • fromstringrequired
  • tostringrequired
  • plannedbooleanrequired
    true for a switchover Kilby's operator made to update the database, false for a failover after a failure.
BackupOne base backup of a database.
  • iduuidrequired
  • namestringrequired
  • typestringrequired

    One of scheduled, manual, initial.

  • statusstringrequired

    One of queued, running, succeeded, failed.

  • messagestringrequired
  • created_atdatetimerequired
  • started_atdatetime or nullrequired
  • finished_atdatetime or nullrequired
  • requested_bystring
    Who asked for a manual backup.
DNSRecordA DNS record to create at your DNS provider.
  • typestringrequired

    One of CNAME, A, AAAA, TXT.

  • namestringrequired
  • valuestringrequired
  • purposestringrequired
    route sends visitors to Kilby, ownership proves you own the domain, certificate lets Kilby issue the certificate before the domain points to Kilby.

    One of route, ownership, certificate.

DomainA custom domain of a web service.
  • iduuidrequired
  • service_iduuidrequired
  • hostnamestringrequired
  • apexbooleanrequired
    true for a root domain such as example.com, which needs A records.
  • statusstringrequired

    One of pending_dns, verifying, issuing_certificate, active, error, deleting.

  • status_messagestringrequired
    What to fix, in one sentence.
  • dns_recordsarray of DNSRecordrequired
    The records that make the domain work.
  • typestringrequired

    One of CNAME, A, AAAA, TXT.

  • namestringrequired
  • valuestringrequired
  • purposestringrequired
    route sends visitors to Kilby, ownership proves you own the domain, certificate lets Kilby issue the certificate before the domain points to Kilby.

    One of route, ownership, certificate.

  • verified_atdatetime or nullrequired
  • certificate_expires_atdatetime or nullrequired
  • certificate_validationstringrequired
    How Let's Encrypt checks the domain: http on the domain itself, dns through its _acme-challenge record.

    One of http, dns.

  • routed_atdatetime or nullrequired
    When the domain was first seen pointing to Kilby. Null while it is pending, or active but its visitors still go elsewhere.
  • redirect_tostring or nullrequired
    The domain of the same service this one redirects to, or null when it serves the service.
  • last_checked_atdatetime or nullrequired
  • next_check_atdatetime
    When Kilby checks the records again: while status is pending_dns, and while an active domain waits to be pointed to Kilby or renews its certificate through DNS.
  • created_atdatetimerequired
RegistryCredentialCredentials for a private image registry. The password is never returned.
  • iduuidrequired
  • namestringrequired
  • registrystringrequired
    The registry host, such as ghcr.io.
  • usernamestringrequired
  • used_byarray of ServiceLinkrequired
    The services that pull with these credentials.
  • iduuidrequired
  • namestringrequired
  • created_atdatetimerequired
  • updated_atdatetimerequired
DeployHookThe deploy hook of a service. The URL is only in the answer that creates it.
  • urlurl
    The secret URL. Only present when the hook was just created.
  • prefixstringrequired
    The start of the token, so you can recognise it.
  • created_atdatetimerequired
  • last_used_atdatetime or nullrequired
WebhookA webhook endpoint that receives signed events.
  • iduuidrequired
  • urlurlrequired
    Keys that cannot manage webhooks see only the host.
  • descriptionstringrequired
  • eventsarray of stringrequired
    The event types it receives.
  • enabledbooleanrequired
  • disabled_reasonstring
    Why Kilby turned it off.
  • secretstring
    The signing secret. Only in the answers that create the endpoint or roll the secret.
  • created_atdatetimerequired
  • updated_atdatetimerequired
DeliveryOne attempt series to deliver an event to a webhook endpoint.
  • iduuidrequired
  • event_iduuidrequired
  • event_typestringrequired
  • statusstringrequired

    One of pending, succeeded, failed, canceled.

  • attemptsintegerrequired
  • response_codeinteger or nullrequired
    The status code your endpoint answered.
  • duration_msinteger or nullrequired
  • errorstring
    What went wrong, in one sentence.
  • created_atdatetimerequired
  • last_attempt_atdatetime or nullrequired
  • next_attempt_atdatetime
    When Kilby tries again. Only while status is pending.
UsageFiguresWhat was used, in hours.
  • instance_secondsintegerrequired
    Seconds instances ran that are billed, the integer behind instance_hours. The invoice, the Billing page and the Usage page show the same seconds.
  • instance_hoursnumberrequired
    Hours instances ran that are billed: instance_seconds divided by 3600, to four decimals. The dashboard writes it with two.
  • vcpu_hoursnumberrequired
    CPU of the instance type multiplied by the time it ran.
  • memory_gb_hoursnumberrequired
    Memory of the instance type multiplied by the time it ran.
  • disk_gb_monthsnumberrequired
  • used_vcpu_hoursnumber or nullrequired
    CPU actually used. null until live metrics exist.
  • used_memory_gb_hoursnumber or nullrequired
    Memory actually used. null until live metrics exist.
UsageResourceThe usage of one service, cron job or database.
  • iduuidrequired
  • namestringrequired
  • typestringrequired
  • planstringrequired
  • deletedbooleanrequired
    true when the resource no longer exists but used something in the month.
  • instance_secondsintegerrequired
  • instance_hoursnumberrequired
  • vcpu_hoursnumberrequired
  • memory_gb_hoursnumberrequired
  • disk_gb_monthsnumberrequired
  • used_vcpu_hoursnumber or nullrequired
  • used_memory_gb_hoursnumber or nullrequired
MetricPointCPU and memory at one moment, averaged over the range's step.
  • timedatetimerequired
  • instancesnumberrequired
  • cpu_usednumber or nullrequired
    Cores, average over the step.
  • cpu_peaknumber or nullrequired
  • cpu_limitnumberrequired
    Cores the instance type allows.
  • memory_used_mbnumber or nullrequired
  • memory_peak_mbnumber or nullrequired
  • memory_limit_mbnumberrequired
RequestPointWhat a web service served during one step of the range.
  • timedatetimerequired
    The start of the step.
  • requestsintegerrequired
    Responses in the step, all classes.
  • requests_per_secondnumber or nullrequired
    Average over the step. null where Kilby could not have counted yet, which is not zero.
  • statusobjectrequired
    Responses per status class.
  • 1xxintegerrequired
  • 2xxintegerrequired
  • 3xxintegerrequired
  • 4xxintegerrequired
  • 5xxintegerrequired
  • error_ratenumber or nullrequired
    5xx divided by all responses, 0 to 1. null without requests.
  • latency_msobjectrequired
    Latency percentiles of the step, in milliseconds. null where too few requests were served.
  • p50number or nullrequired
  • p95number or nullrequired
  • p99number or nullrequired
  • samplesintegerrequired
    Requests the percentiles are drawn from.
  • min_samplesintegerrequired
    p50 and p95 are null below this.
  • min_samples_p99integerrequired
    p99 is null below this.
LogLineOne line of a service's stored log.
  • timedatetimerequired
    When the container printed it.
  • instancestring
    The short name of the instance that printed it. Empty for a line Kilby wrote.
  • messagestringrequired
    The text, up to 16 KB; a longer line is cut and says so.
  • levelstringrequired
    error, warn, info or debug, guessed from the text.

    One of error, warn, info, debug.

  • kilbyboolean
    true for a line Kilby wrote itself, such as how many lines were not stored.
BuildLogLineOne line of a build's log.
  • seqintegerrequired
    Increases by one per line. Pass the last one as after to continue.
  • atdatetimerequired
  • stagestringrequired
  • levelstringrequired

    One of info, warn, error.

  • textstringrequired
DatabaseImportOne copy of another Postgres database into a Kilby database. It has no URL: the source URL is write-only.
  • iduuidrequired
  • database_iduuidrequired
    The database the data is copied into.
  • kindstringrequired
    import for a URL that was sent, sync for a copy from the saved URL.

    One of import, sync.

  • statusstringrequired

    One of queued, running, succeeded, failed.

  • messagestringrequired
    While it runs, what it is doing. When it failed, why, and whether anything changed.
  • sourcestringrequired
    The source's host, port and database name. Never the user or the password.
  • requested_bystringrequired
    Who asked for it; empty if the account no longer exists.
  • source_versionstring or nullrequired
    The source's Postgres version, such as 16.4, once the copy has connected to it.
  • source_bytesinteger or nullrequired
    The size of the source database, in bytes.
  • target_bytesinteger or nullrequired
    The size of this database after the copy, in bytes.
  • tablesinteger or nullrequired
    How many tables this database has after the copy.
  • skipped_extensionsarray of stringrequired
    Extensions of the source that were not created, because only a superuser may create them.
  • outputstringrequired
    The end of what the copy printed, with the source URL and both passwords removed.
  • created_atdatetimerequired
  • started_atdatetime or nullrequired
  • finished_atdatetime or nullrequired
DiskSnapshotA snapshot of a service's disk: a copy of the whole disk at one moment, taken while the service ran (crash-consistent).
  • idstringrequired
    The snapshot's id, such as snap-0a1b2c3d4e5f67890. Use it to restore.
  • created_atdatetimerequired
    When the snapshot started. It shows the disk as it was then.
  • size_gbintegerrequired
    The size of the disk, in GB.
  • statusstringrequired
    Only a completed snapshot can be restored.

    One of completed, in_progress, failed.

  • progress_percentintegerrequired
    How far an in-progress snapshot is.
  • typestringrequired
    daily and weekly snapshots are taken by the schedule and deleted when they expire; manual ones are never deleted by it.

    One of daily, weekly, manual.

  • expires_atdatetime or nullrequired
    When the schedule deletes it. null for a manual snapshot.
RestoredDiskA disk made from a snapshot. It waits until a new service is started on it in the dashboard.
  • iduuidrequired
  • namestringrequired
    The name of the disk in the workspace.
  • statusstringrequired
    ready once the disk can be mounted.

    One of starting, creating, ready, failed, deleting.

  • messagestringrequired
    Why a restore failed. Empty otherwise.
  • size_gbintegerrequired
  • snapshot_idstringrequired
    The snapshot it was made from.
  • snapshot_created_atdatetimerequired
    The moment the disk shows.
  • created_atdatetimerequired
    When the restore was asked for.
  • serviceobject or nullrequired
    The service that uses the disk; null while it is free.
  • iduuidrequired
  • namestringrequired
DNSZoneA domain hosted in DNS AI.
  • iduuidrequired
  • namestringrequired
    The domain, such as example.com.
  • statusstringrequired
    verifying: waiting for the ownership record (ownership_record) at the domain's current DNS; no name servers exist yet. creating: being made. pending: waiting for the registrar to use its name servers. active: the registry delegates the domain to exactly these name servers. elsewhere: the registry delegates it to other servers. deleting: removal asked for; the zone stays, empty, while the registrar still uses it.

    One of verifying, creating, pending, active, elsewhere, deleting.

  • status_messagestringrequired
    Why, when the status needs explaining.
  • name_serversarray of stringrequired
    The four name servers to give the registrar.
  • delegated_name_serversarray of stringrequired
    What the registry said at the last check.
  • dnssec_at_registrarbooleanrequired
    The registry holds a DS record for the domain. Kilby does not sign zones yet, so moving stays blocked.
  • versionintegerrequired
    The records' version: every change adds one.
  • publishedbooleanrequired
    Kilby's name servers answer the latest version.
  • publish_errorstringrequired
    Why the latest version is not published yet, if it failed.
  • ready_to_switchbooleanrequired
    Nothing captured is missing, the latest version is published and DNSSEC is off at the registrar: the name servers can move.
  • not_ready_reasonsarray of stringrequired
    Why ready_to_switch is false.
  • record_setsintegerrequired
  • capturedintegerrequired
    Records the domain answered before the move and Kilby verified.
  • missingintegerrequired
    Captured records this zone does not answer the same yet (not counting those marked as not wanted).
  • created_atdatetimerequired
  • updated_atdatetimerequired
  • ownership_recordDNSOwnershipRecord or nullrequired
    While the zone is verifying: the record to create at the domain's current DNS provider to prove it is yours. null once proven.
  • namestringrequired
    The full name, such as _kilby-challenge.example.com. Most DNS providers want it relative to the domain: _kilby-challenge.
  • typestringrequired

    One of TXT.

  • valuestringrequired
    kilby-verify= and this zone's token.
DNSOwnershipRecordThe record that proves a domain is the workspace's. Kilby looks for it at the name servers the registry delegates the domain to today.
  • namestringrequired
    The full name, such as _kilby-challenge.example.com. Most DNS providers want it relative to the domain: _kilby-challenge.
  • typestringrequired

    One of TXT.

  • valuestringrequired
    kilby-verify= and this zone's token.
DNSRecordSetEvery value of one name and type in a zone.
  • namestringrequired
    Relative to the zone: @ for the domain itself, www, _dmarc.
  • typestringrequired
    ALIAS points to Kilby's load balancer and works on the domain itself.

    One of A, AAAA, CNAME, MX, TXT, CAA, SRV, ALIAS.

  • ttlintegerrequired
    Seconds, 60 to 86400.
  • valuesarray of stringrequired
    MX: 10 mail.example.com. SRV: 10 5 5060 sip.example.com. CAA: 0 issue "letsencrypt.org". ALIAS: kilby.
  • managed_by_domainuuid or nullrequired
    The custom domain Kilby keeps this record for (Configure automatically); it cannot be changed by hand. null for your own records.
DNSCapturedRecordA record the domain answered before the move, as its current name servers answered it.
  • namestringrequired
  • typestringrequired
  • ttlintegerrequired
  • valuesarray of stringrequired
  • sourcestringrequired
    What suggested it: Scan, Zone file, or another source.
  • reasonstringrequired
    Why that name was looked at.
  • waivedbooleanrequired
    Marked as not wanted: it does not block the move.
  • missingbooleanrequired
    This zone does not answer the same values yet.
KeyValueA managed Key Value instance.
  • iduuidrequired
  • namestringrequired
    Unique in the workspace. The instance is reached at kv-<name>.
  • planstringrequired
    The size, by memory.

    One of 256mb, 1gb, 4gb.

  • memory_mbintegerrequired
    The memory the instance reserves.
  • max_memory_mbintegerrequired
    The most data it holds: 75% of the memory. The rest is for the server itself.
  • disk_gbintegerrequired
    The disk the data is written to. It only grows.
  • eviction_policystringrequired
    What happens when the data reaches max_memory_mb: allkeys-lru removes the keys used least recently, noeviction refuses writes.

    One of allkeys-lru, noeviction.

  • statusstringrequired

    One of creating, available, updating, failed, deleting.

  • status_messagestringrequired
  • hoststringrequired
    The host name other services in the workspace connect to.
  • portintegerrequired
    Always 6379.
  • internal_urlstring
    A redis:// connection URL that includes the password. Only in the answer that creates an instance, and for keys that may see secrets.
  • created_atdatetimerequired
  • environmentEnvironmentRef
    Where the instance is listed: its environment and the project of that environment.
  • iduuidrequired
    The environment's id.
  • namestringrequired
    The environment's name, such as Production.
  • defaultbooleanrequired
    true for Production of the Default project, where everything that was never placed is.
  • projectobjectrequired
    The project the environment belongs to.
  • iduuidrequired
  • namestringrequired
LogStreamA destination the workspace's logs are forwarded to. The settings and the delivery state are only in the answer for a key with the Developer role or higher.
  • iduuidrequired
  • namestringrequired
    Unique in the workspace.
  • kindstringrequired
    The provider.

    One of datadog, https, syslog, loki, betterstack.

  • enabledbooleanrequired
    Whether lines are forwarded. A destination turned off keeps its settings.
  • statestringrequired
    healthy: the last delivery worked. failing: deliveries are failing and being retried. disabled: turned off, by a person or by Kilby after sustained failure (see disabled_reason). waiting: on, nothing delivered yet.

    One of healthy, failing, disabled, waiting.

  • created_atdatetimerequired
  • endpointstring
    The address: an https URL, or host:port for syslog. Empty for Datadog, where the site picks it.
  • optionsobject
    The provider's non-secret settings: site and tags (Datadog), header, format, gzip and tls (HTTPS), facility and tls (syslog), user and tls (Loki).
  • servicesarray of uuid
    The services forwarded. An empty list is every service.
  • min_levelstring
    The lowest level forwarded.

    One of debug, info, warn, error.

  • secretobject
    set says whether a credential is stored and last4 is its last four characters. The credential itself is never returned.
  • last_success_atdatetime or null
    When a batch was last delivered.
  • last_errorstring
    Why the last delivery failed, in one sentence; empty while it works.
  • disabled_reasonstring
    Why Kilby turned it off; empty otherwise.
  • last_testobject or null
    The answer to the last test line: at, ok and status, a sentence that names the HTTP status the provider answered. Never the provider's body.
  • todayobject
    Lines and bytes sent today (UTC) and the lines that were dropped, by reason: slow (the destination was too slow or down and the buffer was full), rate and daily (the limits) and failed (a batch that was given up).
  • updated_atdatetime
PreviewSettingsWhat a service's previews are made with.
  • enabledbooleanrequired
    Every pull request into the service's branch gets a preview.
  • copy_secretsbooleanrequired
    Previews also get the variables that look secret (a name with KEY, TOKEN, SECRET or PASSWORD in it, or a value such as an API key or a URL with a password).
  • run_pre_deploybooleanrequired
    Previews run the service's pre-deploy command.
  • planstringrequired
    The instance type of each preview.

    One of starter, standard, pro.

  • variablesarray of stringrequired
    The names of the variables previews get on top of the copied ones. Their values are never returned.
PreviewOne pull request of a service and what became of its preview.
  • iduuidrequired
  • pull_requestintegerrequired
    The pull request's number.
  • titlestringrequired
  • branchstringrequired
    The pull request's head branch.
  • commitstringrequired
    The latest commit Kilby was told about, or empty.
  • statestringrequired
    active: it runs, or is being built. refused: the pull request got no preview (reason says why). closed: the pull request was closed or merged. expired: no new commit for 7 days. removed: removed in Kilby, previews turned off, or its service deleted.

    One of active, refused, closed, expired, removed.

  • reasonstringrequired
    Why, for every state but active.
  • service_iduuid or nullrequired
    The preview's own service, while it has one.
  • urlstringrequired
    The preview's address while it is active, else empty.
  • statusstringrequired
    The preview service's status while it is active (building, deploying, live, failed), else empty.
  • expires_atdatetimerequired
    When Kilby removes it if no new commit comes.
  • created_atdatetimerequired
  • updated_atdatetimerequired
  • ended_atdatetime or nullrequired
    When it ended; null while it is open.
EnvironmentRefWhere a resource is listed: an environment and its project.
  • iduuidrequired
    The environment's id.
  • namestringrequired
    The environment's name, such as Production.
  • defaultbooleanrequired
    true for Production of the Default project, where everything that was never placed is.
  • projectobjectrequired
    The project the environment belongs to.
  • iduuidrequired
  • namestringrequired
ProjectEnvironmentAn environment of a project, with what it holds.
  • iduuidrequired
  • namestringrequired
    Unique in its project, without regard to capitals.
  • projectobjectrequired
    The project it belongs to.
  • iduuidrequired
  • namestringrequired
  • defaultbooleanrequired
    true for Production of the Default project: it holds everything that was never placed, and it cannot be deleted.
  • positionintegerrequired
    Where it sits among the project's environments, from 0.
  • countsobjectrequired
    How many resources it holds, by kind.
  • servicesintegerrequired
    Web, private and worker services.
  • cron_jobsintegerrequired
  • databasesintegerrequired
  • key_valuesintegerrequired
  • resourcesarray of object
    What it holds: type (web, private, worker, cron, database or key_value), id and name. Only in the answers for one project or one environment, and only when the environment holds something.
  • created_atdatetimerequired
  • updated_atdatetimerequired
ProjectA named group of environments.
  • iduuidrequired
  • namestringrequired
    Unique in the workspace, without regard to capitals. Up to 40 characters, no slash.
  • defaultbooleanrequired
    true for the Default project, which holds everything that was never placed. It can be renamed but not deleted.
  • environmentsarray of ProjectEnvironmentrequired
    In order.
  • countsobjectrequired
    How many resources it holds in all its environments, by kind.
  • servicesintegerrequired
    Web, private and worker services.
  • cron_jobsintegerrequired
  • databasesintegerrequired
  • key_valuesintegerrequired
  • created_atdatetimerequired
  • updated_atdatetimerequired
SlackDestinationA Slack channel that receives events as messages. It has no URL: the webhook URL is write-only.
  • iduuidrequired
  • namestringrequired
    Unique within the workspace, up to 60 characters.
  • channelstringrequired
    A label you typed, for example #deploys. Display only: the message goes to the channel the webhook was created for.
  • url_hintstringrequired
    The host and the shape of the URL with every identifier and the secret cut out, such as hooks.slack.com/services/T…/B…/****.
  • eventsarray of stringrequired
    The event types it receives.
  • enabledbooleanrequired
  • statestringrequired
    How it is doing. untested means nothing was sent yet; healthy means the last message got through; failing means the last one did not; disabled means it is turned off (see disabled_reason); sending means a message is on its way.

    One of untested, healthy, failing, disabled, sending.

  • state_detailstringrequired
    The state in one sentence, with the reason when it is failing or disabled.
  • disabled_reasonstring
    Why Kilby turned it off. Absent when it was never turned off by Kilby.
  • last_deliverySlackLastDelivery or nullrequired
    The newest message, or null when none was sent.
  • statusstringrequired

    One of pending, succeeded, failed, canceled.

  • response_codeinteger or nullrequired
    The status code Slack answered.
  • atdatetime or nullrequired
  • errorstring
    What went wrong, in one sentence.
  • created_atdatetimerequired
  • updated_atdatetimerequired
SlackLastDeliveryThe newest message sent to a Slack destination.
  • statusstringrequired

    One of pending, succeeded, failed, canceled.

  • response_codeinteger or nullrequired
    The status code Slack answered.
  • atdatetime or nullrequired
  • errorstring
    What went wrong, in one sentence.
TemplateA template of the gallery: what it creates, what it costs and what to do after it is deployed.
  • idstringrequired
    Stable. Use it in the paths of the other template endpoints.
  • titlestringrequired
  • summarystringrequired
    One sentence.
  • descriptionstringrequired
    A few sentences.
  • categorystringrequired
    AI apps, Vector databases, Automation, Web or Data.
  • homepageurlrequired
    The project's own page.
  • availablebooleanrequired
    false when this Kilby cannot deploy it yet, for example a template that needs a GPU.
  • unavailable_reasonstring
    Why it cannot be deployed. Only present when available is false.
  • estimated_monthly_centsintegerrequired
    What everything it creates costs for a whole month at list prices, in cents. A template that needs a GPU assumes it runs all month.
  • resourcesarray of objectrequired
    The services it creates, in order. Each has key, role, type (web, private or worker), default_name, image (public, pinned to one tag), port (null for a worker), command (only when it replaces the image's), plan, health_check_path, disk (null, or mount_path and size_gb) and env. Each variable in env has name, source and note: source is fixed (with its value), generated (a secret made when you deploy: it is never shown by this API), input (a value you can send in inputs) or address (set to the service's own public address).
  • inputsarray of objectrequired
    The values it asks for, with name, label, help, required, secret and default. Send them in inputs when you deploy.
  • notesarray of stringrequired
    What to know before deploying, said plainly.
  • after_deployarray of stringrequired
    What to do once it runs: the first login, where the data lives, how other services reach it.

Changelog

What changed in the API, newest first.

Log streams

  • /log-streams adds, lists, changes, tests and deletes destinations that a workspace's logs are forwarded to: Datadog, an HTTPS endpoint, syslog over TLS, Grafana Loki and Better Stack. A credential goes in and never comes out.

  • A new webhook event, log_stream.disabled, is sent when Kilby turns a log stream off after sustained failure.

Slack channels

  • /api/v1/slack-destinations connects a Slack channel to the workspace's events through an incoming webhook URL: create, list, change, delete, send a test message and list deliveries.

  • The webhook URL is write-only. It is encrypted when stored and never returned: answers show url_hint only.

Deploy a public Git repository

  • POST /api/v1/services takes source.kind public_git with a repository url and a ref: Kilby downloads the repository's public archive from github.com, gitlab.com or bitbucket.org (the hosts the platform allows) and builds it. No GitHub connection is needed. It works only where deploying from Git is turned on.

  • GET /api/v1/git/public/check and GET /api/v1/git/public/plan read a public repository the way GET /git/commit and GET /git/plan read one on GitHub, with one archive request each. A rate limit of the host is a 429, never a 404.

  • A service built from a public repository has a build hook, POST /hooks/git/{token}, and an optional check for new commits (source.auto_check). source.kind is public_git and source.url, source.host and source.ref say where it comes from. The commit of a build is empty when the host's archive does not say.

API keys that expire, and a reference you can download

  • API keys can have an expiry date (30, 90 or 365 days, or a date you choose) and a description. A key that has expired answers 401 with the code key_expired.

  • API keys can have the admin role. Only an admin key, created by an admin or the owner, can change webhooks and email notifications; a developer key can no longer do that.

  • Every API response carries an X-Request-Id header. Quote it when you ask for help.

  • GET /api/v1/openapi.json serves this API as an OpenAPI 3.1 document, with a code sample for every operation.

  • A key's last use is recorded at most every 5 minutes, and with the address it came from.

The API as it was in the beta

  • Services, cron jobs and Postgres databases: create, read, change, suspend, resume and delete.

  • Deploys, rollbacks, deploy hooks, and builds for services deployed from a Git repository, with build variables.

  • Custom domains, database backups and restores, registry credentials, usage and live metrics.

  • Signed event webhooks and email notifications.