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:
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/workspace", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/workspace",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
Create, change, deploy, roll back, suspend and delete services and databases
–
●
●
secrets
Read and change registry credentials, build variables and database passwords
–
●
●
workspace
Manage 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.
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"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/openapi.json");
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/openapi.json",
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"image": "ghcr.io/acme/api:1.5"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"image": "ghcr.io/acme/api:1.5"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"pre_deploy_command": null}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"pre_deploy_command": None},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"environment": "Checkout app/Staging"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"environment": "Checkout app/Staging"},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/suspend" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/suspend", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/suspend",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/resume" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/resume", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/resume",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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."
}'
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/maintenance", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"enabled": true,
"message": "We are upgrading the database. Back at 14:00 UTC."
}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.put(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/maintenance",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={
"enabled": True,
"message": "We are upgrading the database. Back at 14:00 UTC."
},
)
print(res.status_code, res.json())
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
body := strings.NewReader(`{
"enabled": true,
"message": "We are upgrading the database. Back at 14:00 UTC."
}`)
req, err := http.NewRequest("PUT", "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/maintenance", body)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("KILBY_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(res.Status, string(out))
}
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/maintenance", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"enabled": false}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.put(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/maintenance",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"enabled": False},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/logs?tail=100", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/logs?tail=100",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics?range=24h", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics?range=24h",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics/requests?range=24h", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics/requests?range=24h",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events?kind=failure%2Cscale\u0026limit=100\u0026range=24h", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events?kind=failure%2Cscale\u0026limit=100\u0026range=24h",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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-.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots/snap-0a1b2c3d4e5f67890/restore", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "my-api-before-migration"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots/snap-0a1b2c3d4e5f67890/restore",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"name": "my-api-before-migration"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/images/check", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"image": "ghcr.io/acme/api:1.4"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/images/check",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"image": "ghcr.io/acme/api:1.4"},
)
print(res.status_code, res.json())
{
"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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/projects", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/projects",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/projects", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "Checkout app"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/projects",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"name": "Checkout app"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "Checkout"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"name": "Checkout"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12?move_to=Default%2FProduction", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12?move_to=Default%2FProduction",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "Staging"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"name": "Staging"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "Prod"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"name": "Prod"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053?move_to=Default%2FProduction", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053?move_to=Default%2FProduction",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"skip_pre_deploy": true}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"skip_pre_deploy": True},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d/rollback-preview", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d/rollback-preview",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
{
"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.
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/rollback", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"deploy_id": "5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/rollback",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"deploy_id": "5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds?limit=20", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds?limit=20",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"sha": "9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"sha": "9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0"},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/logs?after=0", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/logs?after=0",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/cancel" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/cancel", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/cancel",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/retry" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/retry", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/retry",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"set": {"NPM_TOKEN": "npm_xxxxxxxx"}}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"set": {"NPM_TOKEN": "npm_xxxxxxxx"}},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/registry-credentials", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/registry-credentials",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"password": "ghp_yyyyyyyyyyyyyyyy"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"password": "ghp_yyyyyyyyyyyyyyyy"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status); // 204: nothing to read
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code) # 204: nothing to read
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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).
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/env-groups", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/env-groups",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/env-groups", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "flags"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/env-groups",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"name": "flags"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "platform-keys"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"name": "platform-keys"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"env_groups": ["shared-keys", "flags"]}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.put(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"env_groups": ["shared-keys", "flags"]},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"env_groups": []}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.put(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"env_groups": []},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env/effective", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env/effective",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/databases",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/autogrow", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"enabled": false}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.put(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/autogrow",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"enabled": False},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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:
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.
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"high_availability": true}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"high_availability": True},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"high_availability": false}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"high_availability": False},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"storage_gb": 10}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"storage_gb": 10},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"environment": "Checkout app/Staging"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"environment": "Checkout app/Staging"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
curl -X POST "https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports/3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports/3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/import-source", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status); // 204: nothing to read
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/import-source",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code) # 204: nothing to read
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/key-values", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/key-values",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"plan": "4gb"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"plan": "4gb"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"environment": "Checkout app/Staging"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"environment": "Checkout app/Staging"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73/connection", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73/connection",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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-challengeCNAME (purposecertificate). 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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"hostname": "api.example.com"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"hostname": "api.example.com"},
)
print(res.status_code, res.json())
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.
curl -X POST "https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/verify" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/verify", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/verify",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"redirect_to": "example.com"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"redirect_to": "example.com"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"redirect_to": null}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"redirect_to": None},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/primary-domain", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"primary_domain": "example.com"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/primary-domain",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"primary_domain": "example.com"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/primary-domain", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"primary_domain": null}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/primary-domain",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"primary_domain": None},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/workspace", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/workspace",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/workspace/network", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/workspace/network",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/usage?month=2026-11", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/usage?month=2026-11",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/notifications", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/notifications",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/notifications", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"email": {"cron.run.failed": false}}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/notifications",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"email": {"cron.run.failed": False}},
)
print(res.status_code, res.json())
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.
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/git/installations", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/git/installations",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/git/repos?installation=1001\u0026q=api", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/git/repos?installation=1001\u0026q=api",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/git/branches?installation=1001\u0026repo=acme%2Fexpress-api", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/git/branches?installation=1001\u0026repo=acme%2Fexpress-api",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/git/commit?branch=main\u0026installation=1001\u0026repo=acme%2Fexpress-api", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/git/commit?branch=main\u0026installation=1001\u0026repo=acme%2Fexpress-api",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/git/public/check?ref=main\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/git/public/check?ref=main\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.codearchive_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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/git/public/plan?ref=main\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/git/public/plan?ref=main\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/git/plan?branch=main\u0026installation=1001\u0026repo=acme%2Fexpress-api", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/git/plan?branch=main\u0026installation=1001\u0026repo=acme%2Fexpress-api",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
{
"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.
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/blueprints", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/blueprints",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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).
curl -X POST "https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/sync" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/sync", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/sync",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/approve", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"sync_id": "@sync"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/approve",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"sync_id": "@sync"},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/syncs", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/syncs",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/pricing");
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/pricing",
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/billing", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/billing",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/billing/invoices", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/billing/invoices",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analyze" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analyze", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analyze",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
{
"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."
}
{
"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.
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analysis", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analysis",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
{
"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.
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.
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"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analyze", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analyze",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
{
"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."
}
{
"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.
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analysis", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analysis",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
{
"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.
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.
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/templates", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/templates",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
{
"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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/templates/open-webui", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/templates/open-webui",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
{
"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.
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/templates/open-webui/deploy", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "team-chat"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/templates/open-webui/deploy",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"name": "team-chat"},
)
print(res.status_code, res.json())
{
"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.
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.
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.
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:
# 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
import crypto from "node:crypto";
// rawBody: the request body exactly as received (a Buffer or string), never re-serialised.
// header: the Kilby-Signature header. secret: the whole whsec_... string.
export function verify(rawBody, header, secret, toleranceSeconds = 300) {
let t = "";
const signatures = [];
for (const part of header.split(",")) {
const i = part.indexOf("=");
if (i < 0) continue;
const key = part.slice(0, i).trim();
const value = part.slice(i + 1).trim();
if (key === "t") t = value;
if (key === "v1") signatures.push(value);
}
if (!t || signatures.length === 0) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
const matches = signatures.some((hex) => {
const given = Buffer.from(hex, "hex");
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
});
const age = Math.abs(Date.now() / 1000 - Number(t));
return matches && age <= toleranceSeconds;
}
import hashlib
import hmac
import time
def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
"""raw_body: the request body exactly as received. secret: the whole whsec_... string."""
t, signatures = "", []
for part in header.split(","):
key, sep, value = part.strip().partition("=")
if not sep:
continue
if key == "t":
t = value
elif key == "v1":
signatures.append(value)
if not t.isdigit() or not signatures:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
matches = any(hmac.compare_digest(expected, sig) for sig in signatures)
return matches and abs(time.time() - int(t)) <= tolerance
package kilby
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"strconv"
"strings"
"time"
)
// Verify reports whether header, the Kilby-Signature of a request, is valid for its raw
// body. secret is the whole whsec_... string.
func Verify(body []byte, header, secret string, tolerance time.Duration) bool {
var t string
var signatures []string
for _, part := range strings.Split(header, ",") {
key, value, ok := strings.Cut(strings.TrimSpace(part), "=")
if !ok {
continue
}
switch key {
case "t":
t = value
case "v1":
signatures = append(signatures, value)
}
}
seconds, err := strconv.ParseInt(t, 10, 64)
if err != nil || len(signatures) == 0 {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(t + "."))
mac.Write(body)
expected := mac.Sum(nil)
matched := false
for _, s := range signatures {
if given, err := hex.DecodeString(s); err == nil && hmac.Equal(given, expected) {
matched = true
}
}
age := time.Since(time.Unix(seconds, 0))
return matched && age <= tolerance && age >= -tolerance
}
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"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046?image=ghcr.io%2Facme%2Fapi%3A3f2a9c1\u0026title=Fix+login+redirect", {
method: "POST",
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046?image=ghcr.io%2Facme%2Fapi%3A3f2a9c1\u0026title=Fix+login+redirect",
)
print(res.status_code, res.json())
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"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/hooks/git/kdh_3f9a1c7e5b2d8046?force=1", {
method: "POST",
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/hooks/git/kdh_3f9a1c7e5b2d8046?force=1",
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status); // 204: nothing to read
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code) # 204: nothing to read
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"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046?image=ghcr.io%2Facme%2Fapi%3A3f2a9c1\u0026title=Fix+login+redirect", {
method: "POST",
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046?image=ghcr.io%2Facme%2Fapi%3A3f2a9c1\u0026title=Fix+login+redirect",
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
curl -X POST "https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status); // 204: nothing to read
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code) # 204: nothing to read
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"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/hooks/git/kdh_3f9a1c7e5b2d8046?force=1", {
method: "POST",
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/hooks/git/kdh_3f9a1c7e5b2d8046?force=1",
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/webhooks", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/webhooks",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"enabled": false}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"enabled": False},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status); // 204: nothing to read
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code) # 204: nothing to read
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"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/test", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/test",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
curl -X POST "https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/secret" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/secret", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/secret",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/deliveries", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/deliveries",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/dns/zones", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/dns/zones",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/dns/zones", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "example.com"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/dns/zones",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"name": "example.com"},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
curl -X POST "https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/verify" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/verify", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/verify",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status); // 204: nothing to read
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code) # 204: nothing to read
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.
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).
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.
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records/TXT/_dmarc", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records/TXT/_dmarc",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/capture", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"source": "scan"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/capture",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"source": "scan"},
)
print(res.status_code, res.json())
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.
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).
curl -X POST "https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/configure-dns" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/configure-dns", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/configure-dns",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/log-streams", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/log-streams",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"min_level": "warn"}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"min_level": "warn"},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"enabled": true}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"enabled": True},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status); // 204: nothing to read
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code) # 204: nothing to read
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.
curl -X POST "https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64/test" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64/test", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64/test",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
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).
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"enabled": true}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"enabled": True},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/previews/5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/previews/5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/slack-destinations", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/slack-destinations",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({"enabled": false}),
});
console.log(res.status, await res.json());
import os
import requests
res = requests.patch(
"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
json={"enabled": False},
)
print(res.status_code, res.json())
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status); // 204: nothing to read
import os
import requests
res = requests.delete(
"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code) # 204: nothing to read
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.
curl -X POST "https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/test" \
-H "Authorization: Bearer $KILBY_API_KEY"
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/test", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.post(
"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/test",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.
const res = await fetch("https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/deliveries", {
headers: {
Authorization: `Bearer ${process.env.KILBY_API_KEY}`,
},
});
console.log(res.status, await res.json());
import os
import requests
res = requests.get(
"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/deliveries",
headers={"Authorization": f"Bearer {os.environ['KILBY_API_KEY']}"},
)
print(res.status_code, res.json())
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.kindpublic_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.
No endpoint matches. Try a resource name such as services, a method such as POST, or a path.