{"components":{"responses":{"Forbidden":{"content":{"application/json":{"example":{"error":{"code":"forbidden","message":"This API key is read-only, or its creator's role in the workspace does not allow changes."}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The key's role does not allow this request."},"InvalidRequest":{"content":{"application/json":{"example":{"error":{"code":"invalid_request","message":"Port must be a number between 1 and 65535."}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A field is missing or not valid. The message says which."},"NotFound":{"content":{"application/json":{"example":{"error":{"code":"not_found","message":"Service not found."}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The resource does not exist in this workspace."},"RateLimited":{"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit reached: 300 requests per minute per key."}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Too many requests. Wait for the time in the Retry-After header."},"Unauthorized":{"content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"This API key is not valid or was revoked."}},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"There is no API key, or it is not valid, was revoked or has expired."}},"schemas":{"Autoscaling":{"additionalProperties":false,"description":"Instances follow CPU use between a minimum and a maximum.","properties":{"max":{"description":"At most this many instances. Allowed: 2 to 10, at least min.","type":"integer"},"min":{"description":"At least this many instances. Allowed: 1 to 10.","type":"integer"},"target_cpu_percent":{"description":"Add instances above this average CPU use, remove them below it. Allowed: 10 to 95.","type":"integer"}},"required":["min","max","target_cpu_percent"],"type":"object"},"Backup":{"additionalProperties":false,"description":"One base backup of a database.","properties":{"created_at":{"format":"date-time","type":"string"},"finished_at":{"format":"date-time","type":["string","null"]},"id":{"format":"uuid","type":"string"},"message":{"type":"string"},"name":{"type":"string"},"requested_by":{"description":"Who asked for a manual backup.","type":"string"},"started_at":{"format":"date-time","type":["string","null"]},"status":{"enum":["queued","running","succeeded","failed"],"type":"string"},"type":{"enum":["scheduled","manual","initial"],"type":"string"}},"required":["id","name","type","status","message","created_at","started_at","finished_at"],"type":"object"},"Build":{"additionalProperties":false,"description":"One build of a service from Git.","properties":{"commit":{"$ref":"#/components/schemas/Commit"},"created_at":{"format":"date-time","type":"string"},"created_by":{"description":"Who started it, for a manual build.","type":"string"},"diagnosis":{"description":"Why it failed and what to change, when Kilby can tell.","oneOf":[{"$ref":"#/components/schemas/Diagnosis"},{"type":"null"}]},"error":{"description":"One sentence when it failed.","type":"string"},"finished_at":{"format":"date-time","type":["string","null"]},"id":{"format":"uuid","type":"string"},"image_digest":{"description":"The digest of the image it pushed.","type":"string"},"number":{"description":"1, 2, 3 within the service. A build can be addressed by its number.","type":"integer"},"stage":{"description":"The stage it is in, or failed in.","enum":["clone","detect","build","push","release","health","live"],"type":"string"},"stages":{"description":"Every stage with its own status and times.","items":{"$ref":"#/components/schemas/BuildStage"},"type":"array"},"started_at":{"format":"date-time","type":["string","null"]},"status":{"enum":["queued","running","succeeded","failed","canceled"],"type":"string"},"trigger":{"description":"What started it.","enum":["push","manual","rebuild"],"type":"string"}},"required":["id","number","trigger","status","stage","commit","stages","diagnosis","created_at","started_at","finished_at"],"type":"object"},"BuildLogLine":{"additionalProperties":false,"description":"One line of a build's log.","properties":{"at":{"format":"date-time","type":"string"},"level":{"enum":["info","warn","error"],"type":"string"},"seq":{"description":"Increases by one per line. Pass the last one as after to continue.","type":"integer"},"stage":{"type":"string"},"text":{"type":"string"}},"required":["seq","at","stage","level","text"],"type":"object"},"BuildPlan":{"additionalProperties":false,"description":"What Kilby understood about a repository: how it builds and runs it.","properties":{"build_command":{"type":"string"},"candidates":{"description":"Other buildable folders, in a monorepo.","items":{"additionalProperties":false,"properties":{"build_command":{"type":"string"},"dockerfile_path":{"type":"string"},"framework":{"type":"string"},"label":{"type":"string"},"root_dir":{"type":"string"},"runtime":{"type":"string"}},"required":["root_dir","runtime","framework","label","build_command","dockerfile_path"],"type":"object"},"type":"array"},"dockerfile_path":{"description":"Only for strategy dockerfile, relative to root_dir.","type":"string"},"env":{"description":"Variables the code reads, found in files such as .env.example.","items":{"additionalProperties":false,"properties":{"build":{"description":"Offered as a build variable.","type":"boolean"},"example":{"type":"string"},"name":{"type":"string"},"secret":{"description":"Looks like a secret: its value is not shown.","type":"boolean"}},"required":["name","example","secret"],"type":"object"},"type":"array"},"framework":{"description":"For example next, vite, express, fastapi or flask. Empty when none was recognised.","type":"string"},"health_path":{"description":"Empty when there is no good guess.","type":"string"},"install_command":{"type":"string"},"kind":{"description":"A suggestion for the service type.","enum":["web","worker"],"type":"string"},"notes":{"description":"What was found and why, in plain sentences.","items":{"type":"string"},"type":"array"},"output_dir":{"description":"The folder that holds the build output.","type":"string"},"package_manager":{"description":"For example npm, pnpm, pip or uv.","type":"string"},"plan_id":{"description":"The instance type Kilby suggests.","enum":["starter","standard","pro"],"type":"string"},"port":{"description":"0 for a worker.","type":"integer"},"root_dir":{"description":"The folder that is built. Empty is the repository root.","type":"string"},"root_route":{"description":"The code routes /, and no health route was found: the dashboard offers / as the health check. Only present when true.","type":"boolean"},"runtime":{"enum":["node","python","go","static","docker"],"type":"string"},"start_command":{"type":"string"},"strategy":{"description":"Whether Kilby builds your Dockerfile or writes one.","enum":["dockerfile","generated"],"type":"string"},"version":{"description":"The runtime version the image uses.","type":"string"},"warnings":{"description":"What might go wrong.","items":{"type":"string"},"type":"array"}},"required":["root_dir","strategy","runtime","framework","dockerfile_path","install_command","build_command","start_command","port","health_path","plan_id","env","notes","warnings","candidates"],"type":"object"},"BuildStage":{"additionalProperties":false,"description":"One stage of a build.","properties":{"finished_at":{"format":"date-time","type":["string","null"]},"name":{"enum":["clone","detect","build","push","release","health","live"],"type":"string"},"note":{"description":"A short remark, such as how many bytes were pushed.","type":"string"},"started_at":{"format":"date-time","type":["string","null"]},"status":{"enum":["pending","running","succeeded","failed","skipped","canceled"],"type":"string"}},"required":["name","status","started_at","finished_at"],"type":"object"},"Commit":{"additionalProperties":false,"description":"A commit that was built.","properties":{"author":{"type":"string"},"branch":{"type":"string"},"message":{"description":"The first line of the commit message.","type":"string"},"sha":{"description":"The full commit id.","type":"string"}},"required":["sha","message","author","branch"],"type":"object"},"DNSCapturedRecord":{"additionalProperties":false,"description":"A record the domain answered before the move, as its current name servers answered it.","properties":{"missing":{"description":"This zone does not answer the same values yet.","type":"boolean"},"name":{"type":"string"},"reason":{"description":"Why that name was looked at.","type":"string"},"source":{"description":"What suggested it: `Scan`, `Zone file`, or another source.","type":"string"},"ttl":{"type":"integer"},"type":{"type":"string"},"values":{"items":{"type":"string"},"type":"array"},"waived":{"description":"Marked as not wanted: it does not block the move.","type":"boolean"}},"required":["name","type","ttl","values","source","reason","waived","missing"],"type":"object"},"DNSOwnershipRecord":{"additionalProperties":false,"description":"The record that proves a domain is the workspace's. Kilby looks for it at the name servers the registry delegates the domain to today.","properties":{"name":{"description":"The full name, such as `_kilby-challenge.example.com`. Most DNS providers want it relative to the domain: `_kilby-challenge`.","type":"string"},"type":{"enum":["TXT"],"type":"string"},"value":{"description":"`kilby-verify=` and this zone's token.","type":"string"}},"required":["name","type","value"],"type":"object"},"DNSRecord":{"additionalProperties":false,"description":"A DNS record to create at your DNS provider.","properties":{"name":{"type":"string"},"purpose":{"description":"route sends visitors to Kilby, ownership proves you own the domain, certificate lets Kilby issue the certificate before the domain points to Kilby.","enum":["route","ownership","certificate"],"type":"string"},"type":{"enum":["CNAME","A","AAAA","TXT"],"type":"string"},"value":{"type":"string"}},"required":["type","name","value","purpose"],"type":"object"},"DNSRecordSet":{"additionalProperties":false,"description":"Every value of one name and type in a zone.","properties":{"managed_by_domain":{"description":"The custom domain Kilby keeps this record for (Configure automatically); it cannot be changed by hand. null for your own records.","format":"uuid","type":["string","null"]},"name":{"description":"Relative to the zone: `@` for the domain itself, `www`, `_dmarc`.","type":"string"},"ttl":{"description":"Seconds, 60 to 86400.","type":"integer"},"type":{"description":"ALIAS points to Kilby's load balancer and works on the domain itself.","enum":["A","AAAA","CNAME","MX","TXT","CAA","SRV","ALIAS"],"type":"string"},"values":{"description":"MX: `10 mail.example.com`. SRV: `10 5 5060 sip.example.com`. CAA: `0 issue \"letsencrypt.org\"`. ALIAS: `kilby`.","items":{"type":"string"},"type":"array"}},"required":["name","type","ttl","values","managed_by_domain"],"type":"object"},"DNSZone":{"additionalProperties":false,"description":"A domain hosted in DNS AI.","properties":{"captured":{"description":"Records the domain answered before the move and Kilby verified.","type":"integer"},"created_at":{"format":"date-time","type":"string"},"delegated_name_servers":{"description":"What the registry said at the last check.","items":{"type":"string"},"type":"array"},"dnssec_at_registrar":{"description":"The registry holds a DS record for the domain. Kilby does not sign zones yet, so moving stays blocked.","type":"boolean"},"id":{"format":"uuid","type":"string"},"missing":{"description":"Captured records this zone does not answer the same yet (not counting those marked as not wanted).","type":"integer"},"name":{"description":"The domain, such as `example.com`.","type":"string"},"name_servers":{"description":"The four name servers to give the registrar.","items":{"type":"string"},"type":"array"},"not_ready_reasons":{"description":"Why ready_to_switch is false.","items":{"type":"string"},"type":"array"},"ownership_record":{"description":"While the zone is `verifying`: the record to create at the domain's current DNS provider to prove it is yours. null once proven.","oneOf":[{"$ref":"#/components/schemas/DNSOwnershipRecord"},{"type":"null"}]},"publish_error":{"description":"Why the latest version is not published yet, if it failed.","type":"string"},"published":{"description":"Kilby's name servers answer the latest version.","type":"boolean"},"ready_to_switch":{"description":"Nothing captured is missing, the latest version is published and DNSSEC is off at the registrar: the name servers can move.","type":"boolean"},"record_sets":{"type":"integer"},"status":{"description":"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.","enum":["verifying","creating","pending","active","elsewhere","deleting"],"type":"string"},"status_message":{"description":"Why, when the status needs explaining.","type":"string"},"updated_at":{"format":"date-time","type":"string"},"version":{"description":"The records' version: every change adds one.","type":"integer"}},"required":["id","name","status","status_message","name_servers","delegated_name_servers","dnssec_at_registrar","version","published","publish_error","ready_to_switch","not_ready_reasons","record_sets","captured","missing","created_at","updated_at","ownership_record"],"type":"object"},"Database":{"additionalProperties":false,"description":"A managed Postgres database.","properties":{"autogrow":{"description":"true when the disk grows by itself when it reaches 90%.","type":"boolean"},"autogrow_max_gb":{"description":"The largest size the disk may grow to. 0 when it was never turned on.","type":"integer"},"created_at":{"format":"date-time","type":"string"},"database":{"description":"The database name.","type":"string"},"disk_checked_at":{"description":"When the disk was last measured.","format":"date-time","type":"string"},"disk_used_percent":{"description":"How full the disk was when it was last measured. Only there while `autogrow` is on and the database has been measured.","type":"integer"},"engine":{"description":"Always postgres.","enum":["postgres"],"type":"string"},"environment":{"$ref":"#/components/schemas/EnvironmentRef","description":"Where the database is listed: its environment and the project of that environment."},"high_availability":{"description":"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.","type":"boolean"},"host":{"description":"The host name other services in the workspace connect to.","type":"string"},"id":{"format":"uuid","type":"string"},"internal_url":{"description":"A connection URL that includes the password. Only in the answers that create a database and in GET /databases/{id} for keys that may see secrets.","type":"string"},"name":{"type":"string"},"plan":{"enum":["starter","standard","pro"],"type":"string"},"port":{"type":"integer"},"read_only_host":{"description":"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.","type":"string"},"standby":{"additionalProperties":false,"description":"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.","properties":{"checked_at":{"description":"When Kilby last looked.","format":"date-time","type":"string"},"last_failover":{"additionalProperties":false,"description":"The last time the primary changed hands.","properties":{"at":{"format":"date-time","type":"string"},"from":{"type":"string"},"planned":{"description":"true for a switchover Kilby's operator made to update the database, false for a failover after a failure.","type":"boolean"},"to":{"type":"string"}},"required":["at","from","to","planned"],"type":"object"},"out_of_sync_since":{"description":"Present while the standby is not in sync.","format":"date-time","type":"string"},"primary_instance":{"description":"The pod that is the primary.","type":"string"},"primary_zone":{"description":"The availability zone of the primary's node.","type":"string"},"standby_instance":{"description":"The pod that is the standby. Empty while it is being created.","type":"string"},"standby_zone":{"description":"The availability zone of the standby's node. When it is the same as the primary's, a zone outage takes both.","type":"string"},"state":{"description":"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.","enum":["creating","in_sync","catching_up","down","unknown"],"type":"string"}},"required":["state","primary_instance","standby_instance"],"type":"object"},"status":{"enum":["creating","available","updating","failed","deleting"],"type":"string"},"status_message":{"type":"string"},"storage_gb":{"description":"The size of the disk now, in GB.","type":"integer"},"synchronous_replication":{"description":"true when each commit waits for the standby. Only with high availability.","type":"boolean"},"user":{"description":"The user name.","type":"string"},"version":{"description":"The major version.","type":"string"}},"required":["id","name","engine","version","plan","storage_gb","status","status_message","host","port","database","user","created_at","autogrow","autogrow_max_gb","high_availability","synchronous_replication"],"type":"object"},"DatabaseImport":{"additionalProperties":false,"description":"One copy of another Postgres database into a Kilby database. It has no URL: the source URL is write-only.","properties":{"created_at":{"format":"date-time","type":"string"},"database_id":{"description":"The database the data is copied into.","format":"uuid","type":"string"},"finished_at":{"format":"date-time","type":["string","null"]},"id":{"format":"uuid","type":"string"},"kind":{"description":"`import` for a URL that was sent, `sync` for a copy from the saved URL.","enum":["import","sync"],"type":"string"},"message":{"description":"While it runs, what it is doing. When it failed, why, and whether anything changed.","type":"string"},"output":{"description":"The end of what the copy printed, with the source URL and both passwords removed.","type":"string"},"requested_by":{"description":"Who asked for it; empty if the account no longer exists.","type":"string"},"skipped_extensions":{"description":"Extensions of the source that were not created, because only a superuser may create them.","items":{"type":"string"},"type":"array"},"source":{"description":"The source's host, port and database name. Never the user or the password.","type":"string"},"source_bytes":{"description":"The size of the source database, in bytes.","type":["integer","null"]},"source_version":{"description":"The source's Postgres version, such as `16.4`, once the copy has connected to it.","type":["string","null"]},"started_at":{"format":"date-time","type":["string","null"]},"status":{"enum":["queued","running","succeeded","failed"],"type":"string"},"tables":{"description":"How many tables this database has after the copy.","type":["integer","null"]},"target_bytes":{"description":"The size of this database after the copy, in bytes.","type":["integer","null"]}},"required":["id","database_id","kind","status","message","source","requested_by","source_version","source_bytes","target_bytes","tables","skipped_extensions","output","created_at","started_at","finished_at"],"type":"object"},"Delivery":{"additionalProperties":false,"description":"One attempt series to deliver an event to a webhook endpoint.","properties":{"attempts":{"type":"integer"},"created_at":{"format":"date-time","type":"string"},"duration_ms":{"type":["integer","null"]},"error":{"description":"What went wrong, in one sentence.","type":"string"},"event_id":{"format":"uuid","type":"string"},"event_type":{"type":"string"},"id":{"format":"uuid","type":"string"},"last_attempt_at":{"format":"date-time","type":["string","null"]},"next_attempt_at":{"description":"When Kilby tries again. Only while status is pending.","format":"date-time","type":"string"},"response_code":{"description":"The status code your endpoint answered.","type":["integer","null"]},"status":{"enum":["pending","succeeded","failed","canceled"],"type":"string"}},"required":["id","event_id","event_type","status","attempts","response_code","duration_ms","created_at","last_attempt_at"],"type":"object"},"Deploy":{"additionalProperties":false,"description":"One deploy of a service.","properties":{"created_at":{"format":"date-time","type":"string"},"finished_at":{"format":"date-time","type":["string","null"]},"id":{"format":"uuid","type":"string"},"image":{"description":"The image it ran.","type":"string"},"message":{"description":"Why it failed, in one sentence. Empty otherwise.","type":"string"},"pre_deploy":{"description":"The run of the service's pre-deploy command for this deploy. null when the deploy had none.","oneOf":[{"$ref":"#/components/schemas/PreDeploy"},{"type":"null"}]},"status":{"enum":["queued","deploying","live","failed","superseded","canceled"],"type":"string"},"title":{"description":"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.","type":"string"},"trigger":{"description":"What started it.","enum":["create","update","manual","resume","rollback","hook","git"],"type":"string"}},"required":["id","image","trigger","status","message","created_at","finished_at","title","pre_deploy"],"type":"object"},"DeployHook":{"additionalProperties":false,"description":"The deploy hook of a service. The URL is only in the answer that creates it.","properties":{"created_at":{"format":"date-time","type":"string"},"last_used_at":{"format":"date-time","type":["string","null"]},"prefix":{"description":"The start of the token, so you can recognise it.","type":"string"},"url":{"description":"The secret URL. Only present when the hook was just created.","format":"uri","type":"string"}},"required":["prefix","created_at","last_used_at"],"type":"object"},"DeployRecord":{"additionalProperties":false,"description":"A deploy, with the deploy it rolled back to when it is a rollback.","properties":{"created_at":{"format":"date-time","type":"string"},"environment_restored":{"description":"Only in the answer to a rollback: whether the environment variables of the earlier deploy were restored.","type":"boolean"},"finished_at":{"format":"date-time","type":["string","null"]},"id":{"format":"uuid","type":"string"},"image":{"type":"string"},"message":{"type":"string"},"reason":{"description":"Why a failed deploy failed.","enum":["crash","oom","probe","quota","image","timeout","predeploy"],"type":"string"},"rollback_of":{"description":"The deploy whose settings this one restores.","format":"uuid","type":"string"},"status":{"enum":["queued","deploying","live","failed","superseded","canceled"],"type":"string"},"title":{"description":"What a list shows for the deploy: \"Rollback to ...\" for a rollback. See Deploy.","type":"string"},"trigger":{"enum":["create","update","manual","resume","rollback","hook","git"],"type":"string"}},"required":["id","image","trigger","status","message","created_at","finished_at","title"],"type":"object"},"Diagnosis":{"additionalProperties":false,"description":"Why a build failed, in plain English.","properties":{"code":{"description":"A stable machine name, for example no_dockerfile.","type":"string"},"detail":{"description":"A few sentences: why, and what to check.","type":"string"},"fixes":{"description":"Changes that may solve it.","items":{"$ref":"#/components/schemas/Fix"},"type":"array"},"title":{"description":"One sentence: what went wrong.","type":"string"}},"required":["code","title","detail","fixes"],"type":"object"},"Disk":{"additionalProperties":false,"description":"A 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.","properties":{"mount_path":{"description":"Where it appears inside the container, for example /data.","type":"string"},"size_gb":{"description":"Size in GB. It can grow, once every 6 hours, but not shrink. Allowed: 1 to 50.","type":"integer"}},"required":["mount_path","size_gb"],"type":"object"},"DiskSnapshot":{"additionalProperties":false,"description":"A snapshot of a service's disk: a copy of the whole disk at one moment, taken while the service ran (crash-consistent).","properties":{"created_at":{"description":"When the snapshot started. It shows the disk as it was then.","format":"date-time","type":"string"},"expires_at":{"description":"When the schedule deletes it. null for a manual snapshot.","format":"date-time","type":["string","null"]},"id":{"description":"The snapshot's id, such as snap-0a1b2c3d4e5f67890. Use it to restore.","type":"string"},"progress_percent":{"description":"How far an in-progress snapshot is.","type":"integer"},"size_gb":{"description":"The size of the disk, in GB.","type":"integer"},"status":{"description":"Only a completed snapshot can be restored.","enum":["completed","in_progress","failed"],"type":"string"},"type":{"description":"daily and weekly snapshots are taken by the schedule and deleted when they expire; manual ones are never deleted by it.","enum":["daily","weekly","manual"],"type":"string"}},"required":["id","created_at","size_gb","status","progress_percent","type","expires_at"],"type":"object"},"Domain":{"additionalProperties":false,"description":"A custom domain of a web service.","properties":{"apex":{"description":"true for a root domain such as example.com, which needs A records.","type":"boolean"},"certificate_expires_at":{"format":"date-time","type":["string","null"]},"certificate_validation":{"description":"How Let's Encrypt checks the domain: http on the domain itself, dns through its _acme-challenge record.","enum":["http","dns"],"type":"string"},"created_at":{"format":"date-time","type":"string"},"dns_records":{"description":"The records that make the domain work.","items":{"$ref":"#/components/schemas/DNSRecord"},"type":"array"},"hostname":{"type":"string"},"id":{"format":"uuid","type":"string"},"last_checked_at":{"format":"date-time","type":["string","null"]},"next_check_at":{"description":"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.","format":"date-time","type":"string"},"redirect_to":{"description":"The domain of the same service this one redirects to, or null when it serves the service.","type":["string","null"]},"routed_at":{"description":"When the domain was first seen pointing to Kilby. Null while it is pending, or active but its visitors still go elsewhere.","format":"date-time","type":["string","null"]},"service_id":{"format":"uuid","type":"string"},"status":{"enum":["pending_dns","verifying","issuing_certificate","active","error","deleting"],"type":"string"},"status_message":{"description":"What to fix, in one sentence.","type":"string"},"verified_at":{"format":"date-time","type":["string","null"]}},"required":["id","service_id","hostname","apex","status","status_message","dns_records","verified_at","certificate_expires_at","certificate_validation","routed_at","redirect_to","last_checked_at","created_at"],"type":"object"},"EnvironmentRef":{"additionalProperties":false,"description":"Where a resource is listed: an environment and its project.","properties":{"default":{"description":"true for Production of the Default project, where everything that was never placed is.","type":"boolean"},"id":{"description":"The environment's id.","format":"uuid","type":"string"},"name":{"description":"The environment's name, such as Production.","type":"string"},"project":{"additionalProperties":false,"description":"The project the environment belongs to.","properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"}},"required":["id","name","default","project"],"type":"object"},"Error":{"additionalProperties":false,"description":"Every error has this shape. Branch on code, show message to people.","properties":{"error":{"additionalProperties":false,"properties":{"code":{"description":"A stable machine-readable name, such as invalid_request or forbidden.","enum":["bad_request","unauthorized","key_expired","forbidden","two_factor_required","not_found","conflict","not_connected","invalid_request","rate_limited","internal","github_unavailable","unavailable"],"type":"string"},"message":{"description":"A sentence for people. It may change; do not match on it.","type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"Fix":{"additionalProperties":false,"description":"A proposed change to one setting of the service.","properties":{"field":{"description":"The setting to change, such as root_dir, dockerfile_path or port.","type":"string"},"label":{"type":"string"},"value":{"type":"string"}},"required":["label","field","value"],"type":"object"},"GitCommit":{"additionalProperties":false,"description":"A commit of a branch.","properties":{"at":{"format":"date-time","type":"string"},"author":{"type":"string"},"message":{"description":"The first line of the commit message.","type":"string"},"sha":{"type":"string"},"url":{"description":"The commit on GitHub.","format":"uri","type":"string"}},"required":["sha","message","author","url","at"],"type":"object"},"GitInstallation":{"additionalProperties":false,"description":"A GitHub account (person or organisation) connected to the workspace.","properties":{"account":{"description":"The GitHub login.","type":"string"},"id":{"description":"Use it as installation_id and installation.","type":"integer"},"linked_at":{"format":"date-time","type":"string"},"linked_by":{"description":"Who connected it to this workspace.","type":"string"},"repository_selection":{"description":"Whether the GitHub App can read all of the account's repositories or only selected ones.","enum":["all","selected"],"type":"string"},"suspended":{"description":"true while GitHub has suspended the installation.","type":"boolean"},"type":{"enum":["User","Organization"],"type":"string"}},"required":["id","account","type","repository_selection","suspended","linked_by","linked_at"],"type":"object"},"GitRepo":{"additionalProperties":false,"description":"A repository the connected account lets Kilby read.","properties":{"default_branch":{"type":"string"},"full_name":{"description":"owner/name.","type":"string"},"id":{"type":"integer"},"installation_id":{"type":"integer"},"owner":{"type":"string"},"private":{"type":"boolean"},"pushed_at":{"description":"The latest push.","format":"date-time","type":"string"}},"required":["id","full_name","private","default_branch","pushed_at","installation_id","owner"],"type":"object"},"KeyValue":{"additionalProperties":false,"description":"A managed Key Value instance.","properties":{"created_at":{"format":"date-time","type":"string"},"disk_gb":{"description":"The disk the data is written to. It only grows.","type":"integer"},"environment":{"$ref":"#/components/schemas/EnvironmentRef","description":"Where the instance is listed: its environment and the project of that environment."},"eviction_policy":{"description":"What happens when the data reaches max_memory_mb: allkeys-lru removes the keys used least recently, noeviction refuses writes.","enum":["allkeys-lru","noeviction"],"type":"string"},"host":{"description":"The host name other services in the workspace connect to.","type":"string"},"id":{"format":"uuid","type":"string"},"internal_url":{"description":"A redis:// connection URL that includes the password. Only in the answer that creates an instance, and for keys that may see secrets.","type":"string"},"max_memory_mb":{"description":"The most data it holds: 75% of the memory. The rest is for the server itself.","type":"integer"},"memory_mb":{"description":"The memory the instance reserves.","type":"integer"},"name":{"description":"Unique in the workspace. The instance is reached at kv-\u003cname\u003e.","type":"string"},"plan":{"description":"The size, by memory.","enum":["256mb","1gb","4gb"],"type":"string"},"port":{"description":"Always 6379.","type":"integer"},"status":{"enum":["creating","available","updating","failed","deleting"],"type":"string"},"status_message":{"type":"string"}},"required":["id","name","plan","memory_mb","max_memory_mb","disk_gb","eviction_policy","status","status_message","host","port","created_at"],"type":"object"},"LogLine":{"additionalProperties":false,"description":"One line of a service's stored log.","properties":{"instance":{"description":"The short name of the instance that printed it. Empty for a line Kilby wrote.","type":"string"},"kilby":{"description":"true for a line Kilby wrote itself, such as how many lines were not stored.","type":"boolean"},"level":{"description":"`error`, `warn`, `info` or `debug`, guessed from the text.","enum":["error","warn","info","debug"],"type":"string"},"message":{"description":"The text, up to 16 KB; a longer line is cut and says so.","type":"string"},"time":{"description":"When the container printed it.","format":"date-time","type":"string"}},"required":["time","message","level"],"type":"object"},"LogStream":{"additionalProperties":false,"description":"A 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.","properties":{"created_at":{"format":"date-time","type":"string"},"disabled_reason":{"description":"Why Kilby turned it off; empty otherwise.","type":"string"},"enabled":{"description":"Whether lines are forwarded. A destination turned off keeps its settings.","type":"boolean"},"endpoint":{"description":"The address: an https URL, or host:port for syslog. Empty for Datadog, where the site picks it.","type":"string"},"id":{"format":"uuid","type":"string"},"kind":{"description":"The provider.","enum":["datadog","https","syslog","loki","betterstack"],"type":"string"},"last_error":{"description":"Why the last delivery failed, in one sentence; empty while it works.","type":"string"},"last_success_at":{"description":"When a batch was last delivered.","format":"date-time","type":["string","null"]},"last_test":{"description":"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.","type":["object","null"]},"min_level":{"description":"The lowest level forwarded.","enum":["debug","info","warn","error"],"type":"string"},"name":{"description":"Unique in the workspace.","type":"string"},"options":{"description":"The provider's non-secret settings: `site` and `tags` (Datadog), `header`, `format`, `gzip` and `tls` (HTTPS), `facility` and `tls` (syslog), `user` and `tls` (Loki).","type":"object"},"secret":{"description":"`set` says whether a credential is stored and `last4` is its last four characters. The credential itself is never returned.","type":"object"},"services":{"description":"The services forwarded. An empty list is every service.","items":{"format":"uuid","type":"string"},"type":"array"},"state":{"description":"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.","enum":["healthy","failing","disabled","waiting"],"type":"string"},"today":{"description":"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).","type":"object"},"updated_at":{"format":"date-time","type":"string"}},"required":["id","name","kind","enabled","state","created_at"],"type":"object"},"MetricPoint":{"additionalProperties":false,"description":"CPU and memory at one moment, averaged over the range's step.","properties":{"cpu_limit":{"description":"Cores the instance type allows.","type":"number"},"cpu_peak":{"type":["number","null"]},"cpu_used":{"description":"Cores, average over the step.","type":["number","null"]},"instances":{"type":"number"},"memory_limit_mb":{"type":"number"},"memory_peak_mb":{"type":["number","null"]},"memory_used_mb":{"type":["number","null"]},"time":{"format":"date-time","type":"string"}},"required":["time","instances","cpu_used","cpu_peak","cpu_limit","memory_used_mb","memory_peak_mb","memory_limit_mb"],"type":"object"},"PreDeploy":{"additionalProperties":false,"description":"The pre-deploy command of one deploy: what ran before the new version started.","properties":{"command":{"description":"The command, as it was when the deploy was queued.","type":"string"},"exit_code":{"description":"The command's exit code. null when it did not get to run, or was stopped at the limit.","type":["integer","null"]},"finished_at":{"format":"date-time","type":["string","null"]},"message":{"description":"What happened, in one sentence, when it did not succeed. Empty otherwise.","type":"string"},"output":{"description":"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 ***.","type":"string"},"started_at":{"format":"date-time","type":["string","null"]},"status":{"description":"`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.","enum":["running","succeeded","failed","timeout","skipped","canceled"],"type":"string"}},"required":["command","status","message","started_at","finished_at","exit_code","output"],"type":"object"},"Preview":{"additionalProperties":false,"description":"One pull request of a service and what became of its preview.","properties":{"branch":{"description":"The pull request's head branch.","type":"string"},"commit":{"description":"The latest commit Kilby was told about, or empty.","type":"string"},"created_at":{"format":"date-time","type":"string"},"ended_at":{"description":"When it ended; null while it is open.","format":"date-time","type":["string","null"]},"expires_at":{"description":"When Kilby removes it if no new commit comes.","format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"pull_request":{"description":"The pull request's number.","type":"integer"},"reason":{"description":"Why, for every state but active.","type":"string"},"service_id":{"description":"The preview's own service, while it has one.","format":"uuid","type":["string","null"]},"state":{"description":"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.","enum":["active","refused","closed","expired","removed"],"type":"string"},"status":{"description":"The preview service's status while it is active (building, deploying, live, failed), else empty.","type":"string"},"title":{"type":"string"},"updated_at":{"format":"date-time","type":"string"},"url":{"description":"The preview's address while it is active, else empty.","type":"string"}},"required":["id","pull_request","title","branch","commit","state","reason","service_id","url","status","expires_at","created_at","updated_at","ended_at"],"type":"object"},"PreviewSettings":{"additionalProperties":false,"description":"What a service's previews are made with.","properties":{"copy_secrets":{"description":"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).","type":"boolean"},"enabled":{"description":"Every pull request into the service's branch gets a preview.","type":"boolean"},"plan":{"description":"The instance type of each preview.","enum":["starter","standard","pro"],"type":"string"},"run_pre_deploy":{"description":"Previews run the service's pre-deploy command.","type":"boolean"},"variables":{"description":"The names of the variables previews get on top of the copied ones. Their values are never returned.","items":{"type":"string"},"type":"array"}},"required":["enabled","copy_secrets","run_pre_deploy","plan","variables"],"type":"object"},"Project":{"additionalProperties":false,"description":"A named group of environments.","properties":{"counts":{"additionalProperties":false,"description":"How many resources it holds in all its environments, by kind.","properties":{"cron_jobs":{"type":"integer"},"databases":{"type":"integer"},"key_values":{"type":"integer"},"services":{"description":"Web, private and worker services.","type":"integer"}},"required":["services","cron_jobs","databases","key_values"],"type":"object"},"created_at":{"format":"date-time","type":"string"},"default":{"description":"true for the Default project, which holds everything that was never placed. It can be renamed but not deleted.","type":"boolean"},"environments":{"description":"In order.","items":{"$ref":"#/components/schemas/ProjectEnvironment"},"type":"array"},"id":{"format":"uuid","type":"string"},"name":{"description":"Unique in the workspace, without regard to capitals. Up to 40 characters, no slash.","type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["id","name","default","environments","counts","created_at","updated_at"],"type":"object"},"ProjectEnvironment":{"additionalProperties":false,"description":"An environment of a project, with what it holds.","properties":{"counts":{"additionalProperties":false,"description":"How many resources it holds, by kind.","properties":{"cron_jobs":{"type":"integer"},"databases":{"type":"integer"},"key_values":{"type":"integer"},"services":{"description":"Web, private and worker services.","type":"integer"}},"required":["services","cron_jobs","databases","key_values"],"type":"object"},"created_at":{"format":"date-time","type":"string"},"default":{"description":"true for Production of the Default project: it holds everything that was never placed, and it cannot be deleted.","type":"boolean"},"id":{"format":"uuid","type":"string"},"name":{"description":"Unique in its project, without regard to capitals.","type":"string"},"position":{"description":"Where it sits among the project's environments, from 0.","type":"integer"},"project":{"additionalProperties":false,"description":"The project it belongs to.","properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"resources":{"description":"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.","items":{"type":"object"},"type":"array"},"updated_at":{"format":"date-time","type":"string"}},"required":["id","name","project","default","position","counts","created_at","updated_at"],"type":"object"},"PublicCommit":{"additionalProperties":false,"description":"The commit a public repository's archive is of.","properties":{"how":{"description":"How Kilby learned the commit: the archive's header, or the archive's folder name. Left out when unknown.","type":"string"},"known":{"description":"false when the archive does not say which commit it is of: Kilby shows it as unknown and cannot tell when it changes.","type":"boolean"},"sha":{"description":"40 hex characters, or empty when the host's archive does not say.","type":"string"},"short":{"description":"The first 7 characters.","type":"string"},"url":{"description":"The commit on the host's website. Empty when unknown.","format":"uri","type":"string"}},"required":["sha","short","known","url"],"type":"object"},"RegistryCredential":{"additionalProperties":false,"description":"Credentials for a private image registry. The password is never returned.","properties":{"created_at":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"registry":{"description":"The registry host, such as ghcr.io.","type":"string"},"updated_at":{"format":"date-time","type":"string"},"used_by":{"description":"The services that pull with these credentials.","items":{"$ref":"#/components/schemas/ServiceLink"},"type":"array"},"username":{"type":"string"}},"required":["id","name","registry","username","used_by","created_at","updated_at"],"type":"object"},"RequestPoint":{"additionalProperties":false,"description":"What a web service served during one step of the range.","properties":{"error_rate":{"description":"5xx divided by all responses, 0 to 1. null without requests.","type":["number","null"]},"latency_ms":{"additionalProperties":false,"description":"Latency percentiles of the step, in milliseconds. null where too few requests were served.","properties":{"min_samples":{"description":"p50 and p95 are null below this.","type":"integer"},"min_samples_p99":{"description":"p99 is null below this.","type":"integer"},"p50":{"type":["number","null"]},"p95":{"type":["number","null"]},"p99":{"type":["number","null"]},"samples":{"description":"Requests the percentiles are drawn from.","type":"integer"}},"required":["p50","p95","p99","samples","min_samples","min_samples_p99"],"type":"object"},"requests":{"description":"Responses in the step, all classes.","type":"integer"},"requests_per_second":{"description":"Average over the step. null where Kilby could not have counted yet, which is not zero.","type":["number","null"]},"status":{"additionalProperties":false,"description":"Responses per status class.","properties":{"1xx":{"type":"integer"},"2xx":{"type":"integer"},"3xx":{"type":"integer"},"4xx":{"type":"integer"},"5xx":{"type":"integer"}},"required":["1xx","2xx","3xx","4xx","5xx"],"type":"object"},"time":{"description":"The start of the step.","format":"date-time","type":"string"}},"required":["time","requests","requests_per_second","status","error_rate","latency_ms"],"type":"object"},"RestoredDisk":{"additionalProperties":false,"description":"A disk made from a snapshot. It waits until a new service is started on it in the dashboard.","properties":{"created_at":{"description":"When the restore was asked for.","format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"message":{"description":"Why a restore failed. Empty otherwise.","type":"string"},"name":{"description":"The name of the disk in the workspace.","type":"string"},"service":{"description":"The service that uses the disk; null while it is free.","oneOf":[{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},{"type":"null"}]},"size_gb":{"type":"integer"},"snapshot_created_at":{"description":"The moment the disk shows.","format":"date-time","type":"string"},"snapshot_id":{"description":"The snapshot it was made from.","type":"string"},"status":{"description":"ready once the disk can be mounted.","enum":["starting","creating","ready","failed","deleting"],"type":"string"}},"required":["id","name","status","message","size_gb","snapshot_id","snapshot_created_at","created_at","service"],"type":"object"},"RollbackDeploy":{"additionalProperties":false,"description":"The deploy a rollback would go back to.","properties":{"created_at":{"format":"date-time","type":"string"},"finished_at":{"format":"date-time","type":["string","null"]},"id":{"format":"uuid","type":"string"},"image":{"description":"The exact image it ran.","type":"string"},"status":{"type":"string"},"trigger":{"type":"string"}},"required":["id","image","trigger","status","created_at","finished_at"],"type":"object"},"RollbackEnvironment":{"additionalProperties":false,"description":"Which environment variables a rollback would add, remove or change, by name.","properties":{"added":{"description":"Names set by the earlier deploy and not set now.","items":{"type":"string"},"type":"array"},"changed":{"description":"Names set in both with different values.","items":{"type":"string"},"type":"array"},"if_kept":{"description":"What happens with restore_env false.","type":"string"},"if_restored":{"description":"What happens with restore_env true.","type":"string"},"note":{"description":"Why nothing is restored, when that is so.","type":"string"},"readable":{"description":"The stored copies could be opened. false: nothing is compared or restored.","type":"boolean"},"recorded":{"description":"The deploy remembers its variables. false: they stay as they are now.","type":"boolean"},"removed":{"description":"Names set now and not set by the earlier deploy.","items":{"type":"string"},"type":"array"},"restore_default":{"description":"The variables are restored when restore_env is left out.","type":"boolean"},"unchanged":{"description":"How many variables are the same.","type":"integer"}},"required":["recorded","readable","restore_default","added","removed","changed","unchanged"],"type":"object"},"RollbackPreview":{"additionalProperties":false,"description":"What a rollback would change. Variable values are never in it.","properties":{"blocked_reason":{"description":"Why it cannot go ahead.","type":"string"},"can_roll_back":{"description":"false when the rollback cannot go ahead; blocked_reason says why.","type":"boolean"},"deploy":{"$ref":"#/components/schemas/RollbackDeploy","description":"The deploy it would go back to."},"environment":{"$ref":"#/components/schemas/RollbackEnvironment","description":"The environment variables that would change: names only."},"generation":{"description":"The version of the service this preview was made from.","type":"integer"},"notes":{"description":"What else happens, in sentences.","items":{"type":"string"},"type":"array"},"settings":{"description":"Image, start command, port or schedule, instance type, health check path, instances and the disk, in this order.","items":{"$ref":"#/components/schemas/RollbackSetting"},"type":"array"},"strategy":{"description":"How the service is replaced.","enum":["rolling_update","recreate","next_run"],"type":"string"}},"required":["deploy","can_roll_back","generation","settings","environment","strategy","notes"],"type":"object"},"RollbackSetting":{"additionalProperties":false,"description":"One setting of the service, now and after the rollback.","properties":{"after":{"description":"What it has after the rollback.","type":"string"},"changes":{"description":"The two differ.","type":"boolean"},"current":{"description":"What the service has now.","type":"string"},"field":{"description":"image, command, port, schedule, plan, health, instances or disk.","enum":["image","command","port","schedule","plan","health","instances","disk"],"type":"string"},"kept":{"description":"A rollback leaves it as it is.","type":"boolean"},"label":{"type":"string"},"note":{"description":"Why it is kept, or what is not known.","type":"string"}},"required":["field","label","current","after","changes","kept"],"type":"object"},"Run":{"additionalProperties":false,"description":"One run of a cron job.","properties":{"finished_at":{"format":"date-time","type":["string","null"]},"manual":{"description":"true when someone started it with the trigger endpoint.","type":"boolean"},"message":{"description":"Why it failed, in one sentence. Empty otherwise.","type":"string"},"name":{"description":"The run's name. Pass it to nothing: it is only for reading.","type":"string"},"started_at":{"format":"date-time","type":"string"},"status":{"enum":["running","succeeded","failed"],"type":"string"}},"required":["name","status","message","manual","started_at","finished_at"],"type":"object"},"Service":{"additionalProperties":false,"description":"A web service, private service, background worker or cron job.","properties":{"auto_concurrency":{"description":"Whether Kilby sets `WEB_CONCURRENCY` for the service from its instance type. Always false for workers and cron jobs.","type":"boolean"},"autoscaling":{"description":"null when the number of instances is fixed.","oneOf":[{"$ref":"#/components/schemas/Autoscaling"},{"type":"null"}]},"command":{"description":"Replaces the image's start command. Only present when set.","type":"string"},"created_at":{"format":"date-time","type":"string"},"disk":{"description":"null when the service has no disk.","oneOf":[{"$ref":"#/components/schemas/Disk"},{"type":"null"}]},"environment":{"$ref":"#/components/schemas/EnvironmentRef","description":"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."},"health_check_path":{"description":"An HTTP path a deploy must answer before it goes live. Empty: the port only has to accept connections.","type":"string"},"id":{"description":"The service's id. Use it in the paths of every other endpoint.","format":"uuid","type":"string"},"image":{"description":"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.","type":"string"},"instances":{"description":"The number of instances, or the minimum when autoscaling.","type":"integer"},"instances_desired":{"description":"Instances Kilby is trying to run.","type":"integer"},"instances_running":{"description":"Instances that are ready now.","type":"integer"},"internal_address":{"description":"host:port for other services in the same workspace. Only present when the service has a port.","type":"string"},"maintenance":{"description":"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`).","type":"boolean"},"maintenance_message":{"description":"The message the maintenance page shows, plain text of up to 280 characters. It is kept while maintenance mode is off.","type":"string"},"name":{"description":"Unique within the workspace. It is also the service's internal host name.","type":"string"},"plan":{"description":"The instance type.","enum":["starter","standard","pro"],"type":"string"},"port":{"description":"The port the service listens on. null for workers and cron jobs.","type":["integer","null"]},"pre_deploy_command":{"description":"The command that runs once before every deploy. Empty when there is none.","type":"string"},"pre_deploy_timeout_seconds":{"description":"The most time that command may take.","type":"integer"},"primary_domain":{"description":"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.","type":"string"},"primary_domain_choice":{"description":"Web services: the address chosen as primary with `PATCH /services/{id}/primary-domain`, or null when none was chosen.","type":["string","null"]},"primary_domain_note":{"description":"Web services, only when the chosen domain is not used: why (removed, redirecting, without a certificate, not pointing to Kilby).","type":"string"},"read_only_root":{"description":"Whether the container's root filesystem is read-only, with a writable `/tmp`. Off unless it was switched on.","type":"boolean"},"registry_credential_id":{"description":"The registry credentials used to pull the image, or null for a public image.","format":"uuid","type":["string","null"]},"render_compat":{"description":"Whether Kilby also sets Render's variables (`RENDER=true`, `RENDER_EXTERNAL_HOSTNAME`...) with this service's values.","type":"boolean"},"schedule":{"description":"Five cron fields, in UTC. Only present on cron jobs.","type":"string"},"source":{"description":"Where a service built from Git comes from. null for a service that runs an image.","oneOf":[{"$ref":"#/components/schemas/Source"},{"type":"null"}]},"status":{"description":"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.","enum":["pending","building","deploying","live","scheduled","failed","suspended","deleting"],"type":"string"},"status_message":{"description":"Why the service is in this status, in one sentence, when that helps. Empty otherwise.","type":"string"},"stop_first":{"description":"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.","type":"boolean"},"suspended":{"description":"true while the service is suspended.","type":"boolean"},"type":{"description":"What kind of service it is.","enum":["web","private","worker","cron"],"type":"string"},"updated_at":{"format":"date-time","type":"string"},"url":{"description":"The Kilby address of a web service (`https://\u003cname\u003e-\u003csuffix\u003e.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.","format":"uri","type":"string"}},"required":["id","name","type","image","port","plan","status","status_message","suspended","created_at","updated_at","registry_credential_id","health_check_path","instances","autoscaling","disk","instances_running","instances_desired","pre_deploy_command","pre_deploy_timeout_seconds","source","auto_concurrency","render_compat","stop_first","read_only_root","maintenance","maintenance_message"],"type":"object"},"ServiceLink":{"additionalProperties":false,"description":"A service, by id and name.","properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"SlackDestination":{"additionalProperties":false,"description":"A Slack channel that receives events as messages. It has no URL: the webhook URL is write-only.","properties":{"channel":{"description":"A label you typed, for example `#deploys`. Display only: the message goes to the channel the webhook was created for.","type":"string"},"created_at":{"format":"date-time","type":"string"},"disabled_reason":{"description":"Why Kilby turned it off. Absent when it was never turned off by Kilby.","type":"string"},"enabled":{"type":"boolean"},"events":{"description":"The event types it receives.","items":{"type":"string"},"type":"array"},"id":{"format":"uuid","type":"string"},"last_delivery":{"description":"The newest message, or null when none was sent.","oneOf":[{"$ref":"#/components/schemas/SlackLastDelivery"},{"type":"null"}]},"name":{"description":"Unique within the workspace, up to 60 characters.","type":"string"},"state":{"description":"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.","enum":["untested","healthy","failing","disabled","sending"],"type":"string"},"state_detail":{"description":"The state in one sentence, with the reason when it is failing or disabled.","type":"string"},"updated_at":{"format":"date-time","type":"string"},"url_hint":{"description":"The host and the shape of the URL with every identifier and the secret cut out, such as `hooks.slack.com/services/T…/B…/****`.","type":"string"}},"required":["id","name","channel","url_hint","events","enabled","state","state_detail","last_delivery","created_at","updated_at"],"type":"object"},"SlackLastDelivery":{"additionalProperties":false,"description":"The newest message sent to a Slack destination.","properties":{"at":{"format":"date-time","type":["string","null"]},"error":{"description":"What went wrong, in one sentence.","type":"string"},"response_code":{"description":"The status code Slack answered.","type":["integer","null"]},"status":{"enum":["pending","succeeded","failed","canceled"],"type":"string"}},"required":["status","response_code","at"],"type":"object"},"Source":{"additionalProperties":false,"description":"Where a service built from Git comes from.","properties":{"auto_check":{"description":"public_git only: Kilby checks for new commits every 15 minutes and builds them. Off by default.","type":"boolean"},"auto_deploy":{"description":"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).","type":"boolean"},"branch":{"description":"The branch Kilby builds.","type":"string"},"build_plan":{"$ref":"#/components/schemas/BuildPlan","description":"The plan builds use: commands, port and runtime."},"dockerfile_path":{"description":"The Dockerfile to use, relative to root_dir. Empty: Kilby decides.","type":"string"},"host":{"description":"public_git only: github.com, gitlab.com or bitbucket.org (the hosts this Kilby allows).","type":"string"},"installation_id":{"description":"The GitHub connection of this workspace that can read the repository.","type":"integer"},"kind":{"description":"git for a repository reached through the GitHub connection, public_git for a public repository built from its archive.","enum":["git","public_git"],"type":"string"},"latest_build":{"$ref":"#/components/schemas/Build","description":"The most recent build. Only present in the answer to creating a service."},"ref":{"description":"public_git only: the branch, tag or commit that is built. HEAD is the repository's default branch.","type":"string"},"repo":{"description":"owner/name.","type":"string"},"root_dir":{"description":"The folder of the repository that is built. Empty is the root.","type":"string"},"url":{"description":"public_git only: the repository's address.","format":"uri","type":"string"},"version":{"description":"Changes whenever the source settings do. Send it back in PATCH /services/{id} to refuse the change if someone edited them meanwhile.","type":"string"}},"required":["kind","installation_id","repo","branch","root_dir","dockerfile_path","auto_deploy","version"],"type":"object"},"SourceEdit":{"additionalProperties":false,"description":"The source settings to change, in the body of PATCH /services/{id}. Everything is optional: what you leave out stays.","properties":{"auto_check":{"description":"public_git only: check for new commits every 15 minutes.","type":"boolean"},"auto_deploy":{"description":"Build and deploy on a push that changes a file in the service's folder. Not for a public_git service: it has no push webhook.","type":"boolean"},"branch":{"description":"The branch to build and follow. Kilby checks it can read it.","type":"string"},"build_command":{"description":"An empty string clears it.","type":"string"},"build_env":{"additionalProperties":{"type":["string","null"]},"description":"Build variables to set. They merge into the current ones, and null removes one. Needs the secrets permission.","type":"object"},"build_plan":{"$ref":"#/components/schemas/BuildPlan","description":"A whole plan, as returned by GET /git/plan or GET /git/public/plan."},"dockerfile_path":{"description":"A Dockerfile, relative to root_dir. An empty string goes back to the default.","type":"string"},"health_path":{"description":"The health check path, as for health_check_path.","type":"string"},"install_command":{"type":"string"},"plan":{"description":"The instance type from the next deploy. A service that was never built cannot change it.","enum":["starter","standard","pro"],"type":"string"},"port":{"description":"A number, or a number written as a string. A service built from Git has one port.","type":"integer"},"root_dir":{"description":"The folder to build. Kilby reads the new folder again and takes its plan; commands in the same request win over it.","type":"string"},"start_command":{"type":"string"},"version":{"description":"The source.version you read. If the settings changed since, the answer is 409 and nothing is written.","type":"string"}},"type":"object"},"SourceInput":{"additionalProperties":false,"description":"Where to build a service from, in the body of POST /services.","properties":{"auto_check":{"default":false,"description":"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.","type":"boolean"},"auto_deploy":{"default":true,"description":"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).","type":"boolean"},"branch":{"description":"The branch to build and to follow.","type":"string"},"build_env":{"additionalProperties":{"type":"string"},"description":"Variables available while building (not at runtime). Their values are stored encrypted and never returned.","type":"object"},"build_plan":{"description":"The build plan the detector proposed, to build exactly what was shown. Leave it out to let Kilby detect it.","type":"object"},"dockerfile_path":{"description":"A Dockerfile to use, relative to root_dir. Empty: Kilby uses the Dockerfile it finds, or writes one.","type":"string"},"installation_id":{"description":"kind git: the GitHub connection of this workspace that can read the repository.","type":"integer"},"kind":{"description":"git for a repository the GitHub connection can read, public_git for a public repository built from its archive (no GitHub connection).","enum":["git","public_git"],"type":"string"},"ref":{"description":"kind public_git: the branch, tag or commit to build.","type":"string"},"repo":{"description":"kind git: owner/name.","type":"string"},"root_dir":{"description":"The folder to build, for a monorepo. Empty is the repository root.","type":"string"},"url":{"description":"kind public_git: the https address of the repository, on one of the hosts this Kilby allows. Required for public_git.","format":"uri","type":"string"}},"required":["kind"],"type":"object"},"Template":{"additionalProperties":false,"description":"A template of the gallery: what it creates, what it costs and what to do after it is deployed.","properties":{"after_deploy":{"description":"What to do once it runs: the first login, where the data lives, how other services reach it.","items":{"type":"string"},"type":"array"},"available":{"description":"false when this Kilby cannot deploy it yet, for example a template that needs a GPU.","type":"boolean"},"category":{"description":"AI apps, Vector databases, Automation, Web or Data.","type":"string"},"description":{"description":"A few sentences.","type":"string"},"estimated_monthly_cents":{"description":"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.","type":"integer"},"homepage":{"description":"The project's own page.","format":"uri","type":"string"},"id":{"description":"Stable. Use it in the paths of the other template endpoints.","type":"string"},"inputs":{"description":"The values it asks for, with `name`, `label`, `help`, `required`, `secret` and `default`. Send them in `inputs` when you deploy.","items":{"type":"object"},"type":"array"},"notes":{"description":"What to know before deploying, said plainly.","items":{"type":"string"},"type":"array"},"resources":{"description":"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).","items":{"type":"object"},"type":"array"},"summary":{"description":"One sentence.","type":"string"},"title":{"type":"string"},"unavailable_reason":{"description":"Why it cannot be deployed. Only present when `available` is false.","type":"string"}},"required":["id","title","summary","description","category","homepage","available","estimated_monthly_cents","resources","inputs","notes","after_deploy"],"type":"object"},"UsageFigures":{"additionalProperties":false,"description":"What was used, in hours.","properties":{"disk_gb_months":{"type":"number"},"instance_hours":{"description":"Hours instances ran that are billed: `instance_seconds` divided by 3600, to four decimals. The dashboard writes it with two.","type":"number"},"instance_seconds":{"description":"Seconds instances ran that are billed, the integer behind `instance_hours`. The invoice, the Billing page and the Usage page show the same seconds.","type":"integer"},"memory_gb_hours":{"description":"Memory of the instance type multiplied by the time it ran.","type":"number"},"used_memory_gb_hours":{"description":"Memory actually used. null until live metrics exist.","type":["number","null"]},"used_vcpu_hours":{"description":"CPU actually used. null until live metrics exist.","type":["number","null"]},"vcpu_hours":{"description":"CPU of the instance type multiplied by the time it ran.","type":"number"}},"required":["instance_seconds","instance_hours","vcpu_hours","memory_gb_hours","disk_gb_months","used_vcpu_hours","used_memory_gb_hours"],"type":"object"},"UsageResource":{"additionalProperties":false,"description":"The usage of one service, cron job or database.","properties":{"deleted":{"description":"true when the resource no longer exists but used something in the month.","type":"boolean"},"disk_gb_months":{"type":"number"},"id":{"format":"uuid","type":"string"},"instance_hours":{"type":"number"},"instance_seconds":{"type":"integer"},"memory_gb_hours":{"type":"number"},"name":{"type":"string"},"plan":{"type":"string"},"type":{"type":"string"},"used_memory_gb_hours":{"type":["number","null"]},"used_vcpu_hours":{"type":["number","null"]},"vcpu_hours":{"type":"number"}},"required":["id","name","type","plan","deleted","instance_seconds","instance_hours","vcpu_hours","memory_gb_hours","disk_gb_months","used_vcpu_hours","used_memory_gb_hours"],"type":"object"},"Webhook":{"additionalProperties":false,"description":"A webhook endpoint that receives signed events.","properties":{"created_at":{"format":"date-time","type":"string"},"description":{"type":"string"},"disabled_reason":{"description":"Why Kilby turned it off.","type":"string"},"enabled":{"type":"boolean"},"events":{"description":"The event types it receives.","items":{"type":"string"},"type":"array"},"id":{"format":"uuid","type":"string"},"secret":{"description":"The signing secret. Only in the answers that create the endpoint or roll the secret.","type":"string"},"updated_at":{"format":"date-time","type":"string"},"url":{"description":"Keys that cannot manage webhooks see only the host.","format":"uri","type":"string"}},"required":["id","url","description","events","enabled","created_at","updated_at"],"type":"object"}},"securitySchemes":{"bearerAuth":{"bearerFormat":"kby_…","description":"A Kilby API key, created under API keys in the dashboard. It is shown once, when it is created.","scheme":"bearer","type":"http"}}},"info":{"contact":{"name":"Neuramorphic","url":"https://onkilby.com"},"description":"The REST API of Neuramorphic Kilby. Every request carries an API key created in the dashboard under API keys: `Authorization: Bearer kby_…`. A key works in one workspace and acts with its role (viewer, developer or admin); each operation says which permission it needs in `x-kilby-permission`. Requests and responses are JSON. Errors always have the shape `{\"error\": {\"code\", \"message\"}}`. This document is generated from the same catalog as the human reference at https://onkilby.com/api/docs, so the two cannot disagree.","summary":"Deploy and run services, cron jobs and Postgres databases.","title":"Kilby API","version":"1"},"openapi":"3.1.0","paths":{"/billing":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"getBilling","responses":{"200":{"content":{"application/json":{"example":{"mode":"off","billed":false,"plan":{"id":"beta","name":"Beta","summary":"Free during the beta.","fee_cents":0,"contact_us":false,"support":"Email","limits":{"services":5,"cron_jobs":5,"databases":2,"cpu":2,"memory_gb":4,"storage_gb":50,"members":0,"custom_domains":20,"included_build_minutes":500,"included_bandwidth_gb":25}},"status":"ok","limits":{"services":5,"cron_jobs":5,"databases":2,"cpu":2,"memory_gb":4,"storage_gb":50,"members":0,"custom_domains":20,"included_build_minutes":500,"included_bandwidth_gb":25},"usage":{"services":3,"cron_jobs":1,"databases":1,"cpu":1.5,"memory_gb":3,"storage_gb":10,"members":2},"month":{"start":"2026-11-01T00:00:00Z","end":"2026-12-01T00:00:00Z","build_minutes_used":42,"bandwidth_metered":true,"bandwidth_bytes":1234567890,"bandwidth_billed_from":null}},"schema":{"additionalProperties":false,"properties":{"billed":{"description":"false in the beta and while billing is off.","type":"boolean"},"limits":{"additionalProperties":false,"description":"The limits that apply now.","properties":{"cpu":{"type":"number"},"cron_jobs":{"type":"integer"},"custom_domains":{"type":"integer"},"databases":{"type":"integer"},"included_bandwidth_gb":{"type":"integer"},"included_build_minutes":{"type":"integer"},"members":{"type":"integer"},"memory_gb":{"type":"number"},"services":{"type":"integer"},"storage_gb":{"type":"integer"}},"required":["services","cron_jobs","databases","cpu","memory_gb","storage_gb","members","custom_domains","included_build_minutes","included_bandwidth_gb"],"type":"object"},"mode":{"description":"How the platform bills.","enum":["off","fake","stripe"],"type":"string"},"month":{"additionalProperties":false,"description":"The current month, UTC.","properties":{"bandwidth_billed_from":{"description":"The first day (YYYY-MM-DD) whose outbound bandwidth is billed; `null`: not billed. Only when `bandwidth_metered`.","type":["string","null"]},"bandwidth_bytes":{"description":"What the workspace's web services sent this month so far, in bytes. Only when `bandwidth_metered`.","type":"integer"},"bandwidth_metered":{"description":"Whether outbound bandwidth is measured on this Kilby.","type":"boolean"},"build_minutes_used":{"type":"integer"},"end":{"format":"date-time","type":"string"},"start":{"format":"date-time","type":"string"}},"required":["start","end","build_minutes_used","bandwidth_metered"],"type":"object"},"plan":{"additionalProperties":false,"description":"The workspace's plan.","properties":{"contact_us":{"description":"true for Enterprise: the fee and limits are agreed with Kilby.","type":"boolean"},"fee_cents":{"description":"The monthly fee of the workspace, in US cents. 0 for Hobby and the beta.","type":"integer"},"id":{"description":"`hobby`, `pro`, `scale`, `enterprise` or `beta`.","enum":["beta","hobby","pro","scale","enterprise"],"type":"string"},"limits":{"additionalProperties":false,"description":"What the plan allows. `members: 0` means unlimited.","properties":{"cpu":{"description":"Cores across all running instances.","type":"number"},"cron_jobs":{"type":"integer"},"custom_domains":{"type":"integer"},"databases":{"type":"integer"},"included_bandwidth_gb":{"type":"integer"},"included_build_minutes":{"type":"integer"},"members":{"type":"integer"},"memory_gb":{"type":"number"},"services":{"description":"Web services, private services and workers.","type":"integer"},"storage_gb":{"description":"Databases and service disks together.","type":"integer"}},"required":["services","cron_jobs","databases","cpu","memory_gb","storage_gb","members","custom_domains","included_build_minutes","included_bandwidth_gb"],"type":"object"},"name":{"type":"string"},"summary":{"description":"One line about who the plan is for.","type":"string"},"support":{"type":"string"}},"required":["id","name","fee_cents","limits"],"type":"object"},"status":{"description":"`grace` while a payment is overdue; `suspended` when services were suspended for it.","enum":["ok","grace","suspended"],"type":"string"},"usage":{"additionalProperties":false,"description":"What the workspace holds now.","properties":{"cpu":{"type":"number"},"cron_jobs":{"type":"integer"},"databases":{"type":"integer"},"members":{"type":"integer"},"memory_gb":{"type":"number"},"services":{"type":"integer"},"storage_gb":{"type":"integer"}},"required":["services","cron_jobs","databases","cpu","memory_gb","storage_gb","members"],"type":"object"}},"required":["mode","billed","plan","status","limits","usage","month"],"type":"object"}}},"description":"The plan."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Read the plan and the limits","tags":["Billing and pricing"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/billing\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/billing\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/billing\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/billing\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/billing/invoices":{"get":{"description":"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.\n\nPermission: `workspace`.","operationId":"listInvoices","parameters":[{"description":"How many invoices. Allowed: 1 to 60.","in":"query","name":"limit","required":false,"schema":{"default":12,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"invoices":[{"id":"@invoice","number":"KB-202610-00002","period":"2026-10","status":"paid","status_label":"Paid","total_cents":11156,"paid_cents":11156,"refunded_cents":0,"issued_at":"2026-11-13T14:05:00Z"}]},"schema":{"additionalProperties":false,"properties":{"invoices":{"items":{"type":"object"},"type":"array"}},"required":["invoices"],"type":"object"}}},"description":"The invoices."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`forbidden`: Invoices are for the owner and admins of the workspace; an API key cannot read them."},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List invoices","tags":["Billing and pricing"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/billing/invoices\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/billing/invoices\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/billing/invoices\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/billing/invoices\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/blueprints":{"get":{"description":"The workspace's blueprints with their status.\n\nPermission: `view`.","operationId":"listBlueprints","responses":{"200":{"content":{"application/json":{"example":{"blueprints":[{"id":"@blueprint","name":"acme-platform","status":"in_sync","status_message":"","repository":"acme/monorepo","branch":"main","path":"kilby.yaml","auto_sync":true,"commit":"f32ca27a9d1b4c0e8d5a7b6c3e2f1a09b8c7d6e5","last_sync_at":"2026-11-13T14:05:00Z","created_at":"2026-11-13T14:05:00Z","resources":[{"kind":"database","name":"main","id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","status":"created","error":""},{"kind":"service","name":"web","id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","status":"created","error":""}]}]},"schema":{"additionalProperties":false,"properties":{"blueprints":{"description":"Each shaped like Read a blueprint, without its last three fields.","items":{"type":"object"},"type":"array"}},"required":["blueprints"],"type":"object"}}},"description":"The blueprints."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List blueprints","tags":["Blueprints"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/blueprints\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/blueprints\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/blueprints\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/blueprints\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nNeeds: `deploy` and `secrets`\n\nPermission: `deploy`.","operationId":"createBlueprint","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"With one variable","value":{"plan_id":"@plan","inputs":{"web":{"STRIPE_KEY":"your-key"}}}}},"schema":{"additionalProperties":false,"properties":{"build_inputs":{"additionalProperties":{"type":"object"},"description":"The same for build variables.","type":"object"},"inputs":{"additionalProperties":{"type":"object"},"description":"The values of the `sync: false` variables, by service name. They go to that service's encrypted variables and nowhere else.","type":"object"},"plan_id":{"description":"The `id` of a plan from Plan a blueprint.","type":"string"}},"required":["plan_id"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"example":{"id":"@blueprint","name":"acme-platform","status":"applying","status_message":"","repository":"acme/monorepo","branch":"main","path":"kilby.yaml","auto_sync":true,"commit":"f32ca27a9d1b4c0e8d5a7b6c3e2f1a09b8c7d6e5","last_sync_at":"2026-11-13T14:05:00Z","created_at":"2026-11-13T14:05:00Z","resources":[{"kind":"database","name":"main","id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","status":"created","error":""},{"kind":"service","name":"web","id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","status":"created","error":""}]},"schema":{"additionalProperties":false,"properties":{"auto_sync":{"description":"Whether a push that changes the file is applied without asking, when the changes are safe.","type":"boolean"},"branch":{"type":"string"},"commit":{"description":"The commit whose file was last applied.","type":"string"},"created_at":{"format":"date-time","type":"string"},"drift":{"description":"Only when you read one blueprint: managed fields changed by hand since the last sync, with `kind`, `name`, `field`, `applied` and `live`.","items":{"type":"object"},"type":"array"},"id":{"format":"uuid","type":"string"},"inputs_needed":{"description":"Only when you read one blueprint: `sync: false` variables nobody has entered yet, with `service` and `key`.","items":{"type":"object"},"type":"array"},"last_sync_at":{"format":"date-time","type":"string"},"name":{"type":"string"},"path":{"description":"The file in the repository.","type":"string"},"pending_changes":{"description":"Only when you read one blueprint: changes waiting for approval, with `kind`, `name`, `action`, `fields`, `needs_approval` and `reason`.","items":{"type":"object"},"type":"array"},"repository":{"type":"string"},"resources":{"description":"What the blueprint manages: `kind` (`service` or `database`), `name`, `id`, `status` (`created`, `creating`, `failed` or `deleting`) and `error`.","items":{"type":"object"},"type":"array"},"status":{"description":"Where the blueprint stands.","enum":["new","in_sync","changes_pending","waiting_approval","failed","applying"],"type":"string"},"status_message":{"description":"Why it failed or what it waits for.","type":"string"}},"required":["id","name","status","repository","branch","path","auto_sync","created_at","resources"],"type":"object"}}},"description":"The blueprint, applying in the background."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The plan is unknown, expired or belongs to another workspace."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`plan_changed`: The workspace changed since the plan: make a new one and look at it."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The plan is invalid or has blocked resources."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Create a blueprint","tags":["Blueprints"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/blueprints\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"plan_id\": \"@plan\", \"inputs\": {\"web\": {\"STRIPE_KEY\": \"your-key\"}}}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/blueprints\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"plan_id\": \"@plan\", \"inputs\": {\"web\": {\"STRIPE_KEY\": \"your-key\"}}}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/blueprints\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"plan_id\": \"@plan\", \"inputs\": {\"web\": {\"STRIPE_KEY\": \"your-key\"}}},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"plan_id\": \"@plan\", \"inputs\": {\"web\": {\"STRIPE_KEY\": \"your-key\"}}}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/blueprints\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/blueprints/plan":{"post":{"description":"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.\n\nPermission: `deploy`.","operationId":"planBlueprint","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"From a repository","value":{"repo":"acme/monorepo","branch":"main","path":"kilby.yaml"}},"example2":{"summary":"From the file","value":{"yaml":"version: 1\nname: demo\nservices:\n  - name: web\n    type: web\n    repo: acme/monorepo\n"}}},"schema":{"additionalProperties":false,"properties":{"adopt":{"description":"Existing resources to take under management, written `service api` or `database main`.","items":{"type":"string"},"type":"array"},"branch":{"type":"string"},"installation_id":{"description":"The GitHub connection; found among the workspace's own when left out.","type":"integer"},"path":{"default":"kilby.yaml","description":"The file in the repository.","type":"string"},"repo":{"description":"The repository, written owner/name.","type":"string"},"yaml":{"description":"The file itself instead of `repo`. Allowed: up to 256 KB.","type":"string"}},"type":"object"}}},"description":"Send `repo` or `yaml`, not both.","required":false},"responses":{"200":{"content":{"application/json":{"example":{"id":"@plan","expires_at":"2026-11-13T14:05:00Z","commit":{"sha":"f32ca27a9d1b4c0e8d5a7b6c3e2f1a09b8c7d6e5","message":"Add a worker","author":"Ada Lovelace"},"plan":{"name":"acme-platform","valid":true,"counts":{"Create":3,"Update":0,"Unchanged":0,"Delete":0,"Blocked":0,"NeedsApproval":0},"resources":[{"ref":{"kind":"service","name":"web"},"action":"create","monthly_usd":9}],"inputs":[{"resource":"web","key":"STRIPE_KEY","set":false}],"cost":{"monthly_usd":32.3,"max_monthly_usd":32.3},"findings":[]}},"schema":{"additionalProperties":false,"properties":{"commit":{"description":"The commit the file was read at.","type":"object"},"expires_at":{"format":"date-time","type":"string"},"id":{"description":"Use it as `plan_id` to create the blueprint.","type":"string"},"plan":{"description":"`name`, `valid`, `counts`, `resources` (each with `action`: `create`, `update`, `unchanged`, `delete` or `blocked`, and its field `diffs`), `inputs`, `cost`, `usage` and `findings`.","type":"object"}},"required":["id","expires_at","plan"],"type":"object"}}},"description":"The plan."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The file could not be read, is over 256 KB, or the repository is not reachable."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: Too many plans in a short time."}},"summary":"Plan a blueprint","tags":["Blueprints"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/blueprints/plan\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"repo\": \"acme/monorepo\", \"branch\": \"main\", \"path\": \"kilby.yaml\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/blueprints/plan\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"repo\": \"acme/monorepo\", \"branch\": \"main\", \"path\": \"kilby.yaml\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/blueprints/plan\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"repo\": \"acme/monorepo\", \"branch\": \"main\", \"path\": \"kilby.yaml\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"repo\": \"acme/monorepo\", \"branch\": \"main\", \"path\": \"kilby.yaml\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/blueprints/plan\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/blueprints/{id}":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"getBlueprint","parameters":[{"description":"The blueprint's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"@blueprint","name":"acme-platform","status":"in_sync","status_message":"","repository":"acme/monorepo","branch":"main","path":"kilby.yaml","auto_sync":true,"commit":"f32ca27a9d1b4c0e8d5a7b6c3e2f1a09b8c7d6e5","last_sync_at":"2026-11-13T14:05:00Z","created_at":"2026-11-13T14:05:00Z","pending_changes":[],"drift":[],"inputs_needed":[],"resources":[{"kind":"database","name":"main","id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","status":"created","error":""},{"kind":"service","name":"web","id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","status":"created","error":""}]},"schema":{"additionalProperties":false,"properties":{"auto_sync":{"description":"Whether a push that changes the file is applied without asking, when the changes are safe.","type":"boolean"},"branch":{"type":"string"},"commit":{"description":"The commit whose file was last applied.","type":"string"},"created_at":{"format":"date-time","type":"string"},"drift":{"description":"Only when you read one blueprint: managed fields changed by hand since the last sync, with `kind`, `name`, `field`, `applied` and `live`.","items":{"type":"object"},"type":"array"},"id":{"format":"uuid","type":"string"},"inputs_needed":{"description":"Only when you read one blueprint: `sync: false` variables nobody has entered yet, with `service` and `key`.","items":{"type":"object"},"type":"array"},"last_sync_at":{"format":"date-time","type":"string"},"name":{"type":"string"},"path":{"description":"The file in the repository.","type":"string"},"pending_changes":{"description":"Only when you read one blueprint: changes waiting for approval, with `kind`, `name`, `action`, `fields`, `needs_approval` and `reason`.","items":{"type":"object"},"type":"array"},"repository":{"type":"string"},"resources":{"description":"What the blueprint manages: `kind` (`service` or `database`), `name`, `id`, `status` (`created`, `creating`, `failed` or `deleting`) and `error`.","items":{"type":"object"},"type":"array"},"status":{"description":"Where the blueprint stands.","enum":["new","in_sync","changes_pending","waiting_approval","failed","applying"],"type":"string"},"status_message":{"description":"Why it failed or what it waits for.","type":"string"}},"required":["id","name","status","repository","branch","path","auto_sync","created_at","resources"],"type":"object"}}},"description":"The blueprint."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Read a blueprint","tags":["Blueprints"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/blueprints/{id}/approve":{"post":{"description":"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.\n\nNeeds: `deploy` and `secrets`\n\nPermission: `deploy`.","operationId":"approveBlueprint","parameters":[{"description":"The blueprint's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Approve a sync","value":{"sync_id":"@sync"}}},"schema":{"additionalProperties":false,"properties":{"sync_id":{"description":"The id of a sync whose status is `waiting_approval`.","type":"string"}},"required":["sync_id"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"example":{"id":"@blueprint","status":"applying"},"schema":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"status":{"description":"`applying`.","type":"string"}},"required":["id","status"],"type":"object"}}},"description":"Applying in the background."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The sync is not waiting any more: it was approved, rejected or replaced by a newer file."},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Approve a sync","tags":["Blueprints"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/approve\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sync_id\": \"@sync\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/approve\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"sync_id\": \"@sync\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/approve\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"sync_id\": \"@sync\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"sync_id\": \"@sync\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/approve\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/blueprints/{id}/sync":{"post":{"description":"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.\n\nNeeds: `deploy` and `secrets`\n\nPermission: `deploy`.","operationId":"syncBlueprint","parameters":[{"description":"The blueprint's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"@blueprint","status":"applying"},"schema":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"status":{"description":"`applying`.","type":"string"}},"required":["id","status"],"type":"object"}}},"description":"Syncing in the background."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Sync a blueprint now","tags":["Blueprints"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/sync\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/sync\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/sync\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/sync\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/blueprints/{id}/syncs":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"listBlueprintSyncs","parameters":[{"description":"The blueprint's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"How many syncs. Allowed: 1 to 100.","in":"query","name":"limit","required":false,"schema":{"type":"integer"}},{"description":"Pass `next_before` of the previous answer to read older syncs.","in":"query","name":"before","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"syncs":[{"id":"@sync","number":2,"trigger":"push","status":"applied","commit":"f32ca27a9d1b4c0e8d5a7b6c3e2f1a09b8c7d6e5","message":"Add a worker","counts":{"Create":1},"results":[{"kind":"service","name":"worker","action":"create","status":"created","message":"","notes":[]}],"error":"","approved_by":"","created_at":"2026-11-13T14:05:00Z","finished_at":"2026-11-13T14:05:00Z"}]},"schema":{"additionalProperties":false,"properties":{"next_before":{"description":"Present when there are older syncs.","type":"string"},"syncs":{"items":{"type":"object"},"type":"array"}},"required":["syncs"],"type":"object"}}},"description":"The syncs."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List the syncs of a blueprint","tags":["Blueprints"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/syncs\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/syncs\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/syncs\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/blueprints/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/syncs\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/databases":{"get":{"description":"The workspace's databases. The connection URL, which holds the password, is not in the list: use Get a database.\n\nPermission: `view`.","operationId":"listDatabases","responses":{"200":{"content":{"application/json":{"example":{"databases":[{"id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","name":"main","engine":"postgres","version":"17","plan":"starter","storage_gb":5,"status":"available","status_message":"","host":"db-main-rw","port":5432,"database":"app","user":"app","created_at":"2026-11-12T22:40:11Z","environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"autogrow":false,"autogrow_max_gb":0,"high_availability":false,"synchronous_replication":false}]},"schema":{"additionalProperties":false,"properties":{"databases":{"items":{"$ref":"#/components/schemas/Database"},"type":"array"}},"required":["databases"],"type":"object"}}},"description":"The databases."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List databases","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/databases\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/databases\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/databases\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nDatabases are in beta. Where backups are available, a database is backed up continuously; List backups says whether yours is.\n\nPermission: `deploy`.","operationId":"createDatabase","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Starter database","value":{"name":"main","version":"17","plan":"starter","storage_gb":5}},"example2":{"summary":"Database with a standby","value":{"name":"main","plan":"standard","storage_gb":10,"high_availability":true}}},"schema":{"additionalProperties":false,"properties":{"autogrow":{"default":false,"description":"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.","type":"boolean"},"autogrow_max_gb":{"description":"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.","type":"integer"},"environment":{"description":"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.","type":"string"},"high_availability":{"default":false,"description":"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.","type":"boolean"},"name":{"description":"Unique in the workspace. Allowed: 3 to 30 characters: lowercase letters, digits and hyphens, starting with a letter.","type":"string"},"plan":{"default":"starter","description":"The instance type.","enum":["starter","standard","pro"],"type":"string"},"storage_gb":{"default":5,"description":"The size of the disk, in GB.","enum":[1,5,10,20],"type":"integer"},"synchronous_replication":{"default":false,"description":"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.","type":"boolean"},"version":{"default":"17","description":"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.","type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","name":"main","engine":"postgres","version":"17","plan":"starter","storage_gb":5,"status":"creating","status_message":"Setting up the primary","host":"db-main-rw","port":5432,"database":"app","user":"app","internal_url":"postgresql://app:Zq7xV2mKd9PtR4wB@db-main-rw:5432/app","created_at":"2026-11-12T22:40:11Z","environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"autogrow":false,"autogrow_max_gb":0,"high_availability":false,"synchronous_replication":false},"schema":{"$ref":"#/components/schemas/Database"}}},"description":"The new database, with its connection URL."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A field is not valid, the name is taken, or the workspace's database or disk limit would be exceeded."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Create a database","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/databases\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"main\", \"version\": \"17\", \"plan\": \"starter\", \"storage_gb\": 5}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"name\": \"main\", \"version\": \"17\", \"plan\": \"starter\", \"storage_gb\": 5}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/databases\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"name\": \"main\", \"version\": \"17\", \"plan\": \"starter\", \"storage_gb\": 5},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"name\": \"main\", \"version\": \"17\", \"plan\": \"starter\", \"storage_gb\": 5}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/databases\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/databases/{id}":{"delete":{"description":"Deletes the database and its data. This cannot be undone, but the backups of a deleted database stay restorable for 30 days: see Restore a database.\n\nPermission: `deploy`.","operationId":"deleteDatabase","parameters":[{"description":"The database's id.","example":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","status":"deleting"},"schema":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"status":{"description":"Always deleting.","type":"string"}},"required":["id","status"],"type":"object"}}},"description":"The database is being deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete a database","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"},"get":{"description":"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.\n\nPermission: `view`.","operationId":"getDatabase","parameters":[{"description":"The database's id.","example":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","name":"main","engine":"postgres","version":"17","plan":"starter","storage_gb":5,"status":"available","status_message":"","host":"db-main-rw","port":5432,"database":"app","user":"app","internal_url":"postgresql://app:Zq7xV2mKd9PtR4wB@db-main-rw:5432/app","created_at":"2026-11-12T22:40:11Z","environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"autogrow":false,"autogrow_max_gb":0,"high_availability":false,"synchronous_replication":false},"schema":{"$ref":"#/components/schemas/Database"}}},"description":"The database."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a database","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"patch":{"description":"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`.\n\n**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.\n\nA 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.\n\nWhile a database has a standby, Get a database also returns `standby`:\n\n```json\n{\n  \"standby\": {\n    \"state\": \"in_sync\",\n    \"primary_instance\": \"db-main-1\",\n    \"standby_instance\": \"db-main-2\",\n    \"primary_zone\": \"us-east-2a\",\n    \"standby_zone\": \"us-east-2b\",\n    \"last_failover\": {\"at\": \"2026-11-13T22:41:09Z\", \"from\": \"db-main-2\", \"to\": \"db-main-1\", \"planned\": false}\n  }\n}\n```\n\nA standby counts as a second database against the workspace's CPU, memory and disk limits; the refusal says which limit.\n\nPermission: `deploy`.","operationId":"updateDatabase","parameters":[{"description":"The database's id.","example":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Turn on high availability","value":{"high_availability":true}},"example2":{"summary":"Turn it off","value":{"high_availability":false}},"example3":{"summary":"Synchronous replication","value":{"high_availability":true,"synchronous_replication":true}},"example4":{"summary":"Grow the disk","value":{"storage_gb":10}},"example5":{"summary":"Move it to another environment","value":{"environment":"Checkout app/Staging"}}},"schema":{"additionalProperties":false,"properties":{"environment":{"description":"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.","type":"string"},"high_availability":{"description":"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.","type":"boolean"},"plan":{"description":"The instance type.","enum":["starter","standard","pro"],"type":"string"},"storage_gb":{"description":"The size of the disk, in GB. It can grow but not shrink.","enum":[1,5,10,20],"type":"integer"},"synchronous_replication":{"description":"Each commit waits for the standby. Only with high_availability.","type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","name":"main","engine":"postgres","version":"17","plan":"starter","storage_gb":5,"status":"updating","status_message":"","host":"db-main-rw","port":5432,"database":"app","user":"app","internal_url":"postgresql://app:Zq7xV2mKd9PtR4wB@db-main-rw:5432/app","created_at":"2026-11-12T22:40:11Z","environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"autogrow":false,"autogrow_max_gb":0,"high_availability":true,"synchronous_replication":false},"schema":{"$ref":"#/components/schemas/Database"}}},"description":"The database, now `updating`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The database is not available yet, so its high availability cannot change."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_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)."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Update a database","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"high_availability\": true}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"high_availability\": true}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"high_availability\": True},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"high_availability\": true}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/databases/{id}/autogrow":{"put":{"description":"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.\n\nOff by default. Where this Kilby does not have it yet, the answer is a 422.\n\nPermission: `deploy`.","operationId":"setDatabaseAutogrow","parameters":[{"description":"The database's id.","example":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Turn it on","value":{"enabled":true,"max_gb":20}},"example2":{"summary":"Turn it off","value":{"enabled":false}}},"schema":{"additionalProperties":false,"properties":{"enabled":{"description":"true to grow the disk by itself, false to stop.","type":"boolean"},"max_gb":{"description":"The largest size the disk may grow to. Required when `enabled` is true.","type":"integer"}},"required":["enabled"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","name":"main","engine":"postgres","version":"17","plan":"starter","storage_gb":5,"status":"available","status_message":"","host":"db-main-rw","port":5432,"database":"app","user":"app","created_at":"2026-11-12T22:40:11Z","environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"autogrow":true,"autogrow_max_gb":20,"high_availability":false,"synchronous_replication":false},"schema":{"$ref":"#/components/schemas/Database"}}},"description":"The database with its new setting."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: `max_gb` is missing, not more than the disk, or more than the workspace's disk limit leaves; or growing the disk by itself is not available yet."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Grow the disk automatically","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PUT \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/autogrow\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"enabled\": true, \"max_gb\": 20}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/autogrow\", {\n  method: \"PUT\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"enabled\": true, \"max_gb\": 20}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.put(\n    \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/autogrow\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"enabled\": True, \"max_gb\": 20},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"enabled\": true, \"max_gb\": 20}`)\n\treq, err := http.NewRequest(\"PUT\", \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/autogrow\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/databases/{id}/backups":{"get":{"description":"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.\n\n`status` is `healthy`, `starting`, `setting_up`, `failing` or `off`.\n\nPermission: `view`.","operationId":"listBackups","parameters":[{"description":"The database's id.","example":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"enabled":true,"status":"healthy","message":"","retention_days":7,"daily_backup_time":"03:17 UTC","last_backup_at":"2026-11-13T03:19:40Z","recovery_window":{"first":"2026-11-06T03:17:02Z","latest":"2026-11-13T14:02:11Z"},"backups":[{"id":"4b1f6c2d-8e3a-4f70-9a15-0c7d2e9b8a61","name":"db-main-daily-20261113031700","type":"scheduled","status":"succeeded","message":"","created_at":"2026-11-13T03:17:00Z","started_at":"2026-11-13T03:17:02Z","finished_at":"2026-11-13T03:19:40Z"}]},"schema":{"additionalProperties":false,"properties":{"backups":{"items":{"$ref":"#/components/schemas/Backup"},"type":"array"},"daily_backup_time":{"description":"When the daily base backup runs.","type":"string"},"enabled":{"type":"boolean"},"last_backup_at":{"format":"date-time","type":["string","null"]},"message":{"description":"What is wrong, when status is failing.","type":"string"},"recovery_window":{"additionalProperties":false,"description":"The range you can restore to.","properties":{"first":{"format":"date-time","type":["string","null"]},"latest":{"format":"date-time","type":["string","null"]}},"required":["first","latest"],"type":"object"},"restored_from":{"additionalProperties":false,"description":"Present when this database was created by a restore.","properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"target_time":{"description":"null: the latest point","format":"date-time","type":["string","null"]}},"required":["id","name","target_time"],"type":"object"},"retention_days":{"description":"How far back the database can be restored.","type":"integer"},"status":{"enum":["healthy","starting","setting_up","failing","off"],"type":"string"}},"required":["enabled","status","message","retention_days","daily_backup_time","last_backup_at","recovery_window","backups"],"type":"object"}}},"description":"The backup status."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List backups","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nPermission: `deploy`.","operationId":"startBackup","parameters":[{"description":"The database's id.","example":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"4b1f6c2d-8e3a-4f70-9a15-0c7d2e9b8a62","name":"db-main-manual-1794524411","type":"manual","status":"queued","message":"","created_at":"2026-11-13T14:05:00Z","started_at":null,"finished_at":null,"requested_by":"Ada Lovelace"},"schema":{"$ref":"#/components/schemas/Backup"}}},"description":"The queued backup."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: Backups are not set up for this database yet, it is not available, another backup is in progress, or 6 were taken today."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Take a backup now","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/backups\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/databases/{id}/import-source":{"delete":{"description":"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.\n\nPermission: `secrets`.","operationId":"forgetDatabaseImportSource","parameters":[{"description":"The database's id.","example":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Deleted. There is no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Forget the saved source","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/import-source\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/import-source\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status); // 204: nothing to read\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/import-source\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code)  # 204: nothing to read\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/import-source\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"secrets"}},"/databases/{id}/imports":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"listDatabaseImports","parameters":[{"description":"The database's id.","example":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"imports":[{"id":"3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b","database_id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","kind":"import","status":"succeeded","message":"","source":"dpg-d1abc2defg3h4i-a.oregon-postgres.render.com:5432/shop","requested_by":"Ada Lovelace","source_version":"16.4","source_bytes":152043520,"target_bytes":148897792,"tables":23,"skipped_extensions":["pg_stat_statements"],"output":"Connecting to the source database…\nConnecting to this database…\nCopying the data…\nUpdating the planner's statistics…\nDone.","created_at":"2026-11-13T14:05:00Z","started_at":"2026-11-13T14:05:04Z","finished_at":"2026-11-13T14:06:41Z"}],"saved_source":{"source":"dpg-d1abc2defg3h4i-a.oregon-postgres.render.com:5432/shop","saved_at":"2026-11-13T14:05:00Z","expires_at":"2026-11-20T14:05:00Z"}},"schema":{"additionalProperties":false,"properties":{"imports":{"description":"Up to 20, newest first.","items":{"$ref":"#/components/schemas/DatabaseImport"},"type":"array"},"saved_source":{"description":"null when no source URL is saved.","oneOf":[{"additionalProperties":false,"properties":{"expires_at":{"description":"When Kilby deletes it: 7 days after it was last used.","format":"date-time","type":"string"},"saved_at":{"format":"date-time","type":"string"},"source":{"description":"Host, port and database name.","type":"string"}},"required":["source","saved_at","expires_at"],"type":"object"},{"type":"null"}]}},"required":["imports","saved_source"],"type":"object"}}},"description":"The imports."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List imports","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nSend `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.\n\nThe 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.\n\nKilby 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.\n\nPermission: `secrets`.","operationId":"startDatabaseImport","parameters":[{"description":"The database's id.","example":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Import","value":{"source_url":"postgresql://shop_user:password@dpg-d1abc2defg3h4i-a.oregon-postgres.render.com/shop"}},"example2":{"summary":"Sync again","value":{}}},"schema":{"additionalProperties":false,"properties":{"source_url":{"description":"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.","type":"string"}},"type":"object"}}},"description":"Leave the body out to sync again from the saved URL.","required":false},"responses":{"202":{"content":{"application/json":{"example":{"id":"3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b","database_id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","kind":"import","status":"queued","message":"","source":"dpg-d1abc2defg3h4i-a.oregon-postgres.render.com:5432/shop","requested_by":"Ada Lovelace","source_version":null,"source_bytes":null,"target_bytes":null,"tables":null,"skipped_extensions":[],"output":"","created_at":"2026-11-13T14:05:00Z","started_at":null,"finished_at":null},"schema":{"$ref":"#/components/schemas/DatabaseImport"}}},"description":"The queued import."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: An import into this database is already queued or running, or there is no saved URL to sync from."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_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."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Import from another Postgres","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"source_url\": \"postgresql://shop_user:password@dpg-d1abc2defg3h4i-a.oregon-postgres.render.com/shop\"\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"source_url\": \"postgresql://shop_user:password@dpg-d1abc2defg3h4i-a.oregon-postgres.render.com/shop\"\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"source_url\": \"postgresql://shop_user:password@dpg-d1abc2defg3h4i-a.oregon-postgres.render.com/shop\"\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"source_url\": \"postgresql://shop_user:password@dpg-d1abc2defg3h4i-a.oregon-postgres.render.com/shop\"\n}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"secrets"}},"/databases/{id}/imports/{import_id}":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"getDatabaseImport","parameters":[{"description":"The database's id.","example":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"The import's id.","example":"3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b","in":"path","name":"import_id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b","database_id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","kind":"import","status":"succeeded","message":"","source":"dpg-d1abc2defg3h4i-a.oregon-postgres.render.com:5432/shop","requested_by":"Ada Lovelace","source_version":"16.4","source_bytes":152043520,"target_bytes":148897792,"tables":23,"skipped_extensions":["pg_stat_statements"],"output":"Connecting to the source database…\nConnecting to this database…\nCopying the data…\nUpdating the planner's statistics…\nDone.","created_at":"2026-11-13T14:05:00Z","started_at":"2026-11-13T14:05:04Z","finished_at":"2026-11-13T14:06:41Z"},"schema":{"$ref":"#/components/schemas/DatabaseImport"}}},"description":"The import."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The database has no import with that id."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get an import","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports/3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports/3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports/3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/imports/3f7c2a9e-5b1d-4e60-8a24-9c0d1e2f3a4b\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/databases/{id}/restore":{"post":{"description":"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.\n\nThe `{id}` may also be that of a database deleted in the last 30 days.\n\nPermission: `deploy`.","operationId":"restoreDatabase","parameters":[{"description":"The database's id.","example":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Restore to a moment","value":{"name":"main-restore","target_time":"2026-11-13T09:30:00Z"}}},"schema":{"additionalProperties":false,"properties":{"name":{"description":"The new database's name. Allowed: 3 to 30 characters.","type":"string"},"plan":{"description":"The instance type. Defaults to the source's.","enum":["starter","standard","pro"],"type":"string"},"storage_gb":{"description":"The size of the disk, in GB. Defaults to the source's; it cannot be smaller.","enum":[1,5,10,20],"type":"integer"},"target_time":{"description":"The moment to restore, in RFC 3339, UTC. Leave it out, or send latest, for the latest point.","type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"database":{"id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","name":"main-restore","engine":"postgres","version":"17","plan":"starter","storage_gb":5,"status":"creating","status_message":"","host":"db-main-restore-rw","port":5432,"database":"app","user":"app","internal_url":"postgresql://app:Zq7xV2mKd9PtR4wB@db-main-rw:5432/app","created_at":"2026-11-12T22:40:11Z","environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"autogrow":false,"autogrow_max_gb":0,"high_availability":false,"synchronous_replication":false},"restored_from":{"id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","name":"main","target_time":"2026-11-13T09:30:00Z"}},"schema":{"additionalProperties":false,"properties":{"database":{"$ref":"#/components/schemas/Database","description":"The new database, with its own internal_url."},"restored_from":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"target_time":{"description":"null: the latest point","format":"date-time","type":["string","null"]}},"required":["id","name","target_time"],"type":"object"}},"required":["database","restored_from"],"type":"object"}}},"description":"The new database and where it comes from."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: No database with backups to restore from has that id."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: Backups are off, there is nothing to restore from yet, or the backups are kept somewhere this platform cannot restore from."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: target_time is outside the recovery window, or a field is not valid."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Restore a database","tags":["Databases"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/restore\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"main-restore\", \"target_time\": \"2026-11-13T09:30:00Z\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/restore\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"name\": \"main-restore\", \"target_time\": \"2026-11-13T09:30:00Z\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/restore\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"name\": \"main-restore\", \"target_time\": \"2026-11-13T09:30:00Z\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"name\": \"main-restore\", \"target_time\": \"2026-11-13T09:30:00Z\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/databases/0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e/restore\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/dns/zones":{"get":{"description":"The workspace's zones, oldest first, and how many its plan allows.\n\nPermission: `view`.","operationId":"listDNSZones","responses":{"200":{"content":{"application/json":{"example":{"zones":[{"id":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","name":"example.com","status":"pending","status_message":"","name_servers":["ns-1093.awsdns-08.org","ns-1823.awsdns-35.co.uk","ns-282.awsdns-35.com","ns-841.awsdns-41.net"],"delegated_name_servers":["ns1.previous-host.example","ns2.previous-host.example"],"dnssec_at_registrar":false,"version":3,"published":true,"publish_error":"","ready_to_switch":true,"not_ready_reasons":[],"record_sets":4,"captured":4,"missing":0,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z","ownership_record":null}],"limit":10},"schema":{"additionalProperties":false,"properties":{"limit":{"description":"How many zones the workspace may hold, waiting ones included.","type":"integer"},"zones":{"items":{"$ref":"#/components/schemas/DNSZone"},"type":"array"}},"required":["zones","limit"],"type":"object"}}},"description":"The zones."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List zones","tags":["DNS AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/dns/zones\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/dns/zones\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/dns/zones\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/dns/zones\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nPermission: `workspace`.","operationId":"createDNSZone","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Create","value":{"name":"example.com"}}},"schema":{"additionalProperties":false,"properties":{"name":{"description":"The whole domain, as bought: `example.com`, not `www.example.com`.","type":"string"}},"type":"object"}}},"required":false},"responses":{"201":{"content":{"application/json":{"example":{"id":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","name":"example.com","status":"verifying","status_message":"_kilby-challenge.example.com does not answer with this zone's value yet. DNS changes can take a few minutes to show.","name_servers":[],"delegated_name_servers":[],"dnssec_at_registrar":false,"version":0,"published":true,"publish_error":"","ready_to_switch":false,"not_ready_reasons":["Prove the domain is yours first: create the ownership record."],"record_sets":0,"captured":0,"missing":0,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z","ownership_record":{"name":"_kilby-challenge.example.com","type":"TXT","value":"kilby-verify=d4f1a07c9e3b42h8k2m5q7s9"}},"schema":{"$ref":"#/components/schemas/DNSZone"}}},"description":"The new zone, `verifying`: waiting for its ownership record."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`limit_reached`: The workspace holds as many zones as its plan allows, or as many waiting ones."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: 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."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: Not a whole domain Kilby can host: a subdomain, a reserved domain, or not a domain name."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Create a zone","tags":["DNS AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/dns/zones\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"example.com\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/dns/zones\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"name\": \"example.com\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/dns/zones\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"name\": \"example.com\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"name\": \"example.com\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/dns/zones\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/dns/zones/{id}":{"delete":{"description":"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.\n\nPermission: `workspace`.","operationId":"deleteDNSZone","parameters":[{"description":"The zone's id.","example":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","name":"example.com","status":"pending","status_message":"","name_servers":["ns-1093.awsdns-08.org","ns-1823.awsdns-35.co.uk","ns-282.awsdns-35.com","ns-841.awsdns-41.net"],"delegated_name_servers":["ns1.previous-host.example","ns2.previous-host.example"],"dnssec_at_registrar":false,"version":3,"published":true,"publish_error":"","ready_to_switch":true,"not_ready_reasons":[],"record_sets":4,"captured":4,"missing":0,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z","ownership_record":null},"schema":{"$ref":"#/components/schemas/DNSZone"}}},"description":"The zone, now `deleting`."},"204":{"description":"The zone was still `verifying`: it is gone."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The workspace has no zone with that id."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete a zone","tags":["DNS AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status); // 204: nothing to read\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code)  # 204: nothing to read\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"},"get":{"description":"One zone and its record sets.\n\nPermission: `view`.","operationId":"getDNSZone","parameters":[{"description":"The zone's id.","example":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"zone":{"id":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","name":"example.com","status":"pending","status_message":"","name_servers":["ns-1093.awsdns-08.org","ns-1823.awsdns-35.co.uk","ns-282.awsdns-35.com","ns-841.awsdns-41.net"],"delegated_name_servers":["ns1.previous-host.example","ns2.previous-host.example"],"dnssec_at_registrar":false,"version":3,"published":true,"publish_error":"","ready_to_switch":true,"not_ready_reasons":[],"record_sets":4,"captured":4,"missing":0,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z","ownership_record":null},"records":[{"name":"@","type":"MX","ttl":3600,"values":["1 aspmx.l.google.com","5 alt1.aspmx.l.google.com"],"managed_by_domain":null},{"name":"@","type":"TXT","ttl":300,"values":["v=spf1 include:_spf.google.com ~all"],"managed_by_domain":null},{"name":"_dmarc","type":"TXT","ttl":300,"values":["v=DMARC1; p=quarantine"],"managed_by_domain":null},{"name":"www","type":"CNAME","ttl":300,"values":["site.previous-host.example"],"managed_by_domain":null}]},"schema":{"additionalProperties":false,"properties":{"records":{"items":{"$ref":"#/components/schemas/DNSRecordSet"},"type":"array"},"zone":{"$ref":"#/components/schemas/DNSZone"}},"required":["zone","records"],"type":"object"}}},"description":"The zone and its records."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The workspace has no zone with that id."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a zone","tags":["DNS AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/dns/zones/{id}/capture":{"post":{"description":"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.\n\nPermission: `workspace`.","operationId":"captureDNSRecords","parameters":[{"description":"The zone's id.","example":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Scan","value":{"source":"scan"}},"example2":{"summary":"Zone file","value":{"source":"zonefile","text":"$ORIGIN example.com.\nem123 3600 IN CNAME u123.wl.sendgrid.net.\n"}}},"schema":{"additionalProperties":false,"properties":{"source":{"description":"`scan` or `zonefile`.","type":"string"},"text":{"description":"The zone file, for `zonefile`.","type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"found":1,"unanswered":0,"warnings":[],"captured":[{"name":"_dmarc","type":"TXT","ttl":300,"values":["v=DMARC1; p=quarantine"],"source":"Scan","reason":"Mail: DMARC policy","waived":false,"missing":false}]},"schema":{"additionalProperties":false,"properties":{"captured":{"description":"Everything captured for this zone so far.","items":{"$ref":"#/components/schemas/DNSCapturedRecord"},"type":"array"},"found":{"description":"Record sets the current name servers answered.","type":"integer"},"unanswered":{"description":"Suggested records they did not answer: left out.","type":"integer"},"warnings":{"description":"Lines of a zone file that were skipped, and why.","items":{"type":"string"},"type":"array"}},"required":["found","unanswered","warnings","captured"],"type":"object"}}},"description":"What was found."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The workspace has no zone with that id."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: No such source, or the domain already uses Kilby's name servers, or its current name servers did not answer."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: Too many captures of this zone in the last hour."}},"summary":"Capture today's records","tags":["DNS AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/capture\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"source\": \"scan\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/capture\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"source\": \"scan\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/capture\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"source\": \"scan\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"source\": \"scan\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/capture\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/dns/zones/{id}/records":{"put":{"description":"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.\n\nPermission: `workspace`.","operationId":"putDNSRecordSet","parameters":[{"description":"The zone's id.","example":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"A CNAME","value":{"name":"www","type":"CNAME","ttl":300,"values":["site.previous-host.example"]}},"example2":{"summary":"Mail","value":{"name":"@","type":"MX","ttl":3600,"values":["1 aspmx.l.google.com","5 alt1.aspmx.l.google.com"]}}},"schema":{"additionalProperties":false,"properties":{"name":{"description":"Relative to the zone: `@`, `www`, `_dmarc`.","type":"string"},"replace":{"description":"To rename or retype a set: the name and type of the set it replaces, such as `www CNAME`.","type":"string"},"ttl":{"description":"Seconds, 60 to 86400. Default 300.","type":"integer"},"type":{"type":"string"},"values":{"description":"One or more values.","items":{"type":"string"},"type":"array"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"zone":{"id":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","name":"example.com","status":"pending","status_message":"","name_servers":["ns-1093.awsdns-08.org","ns-1823.awsdns-35.co.uk","ns-282.awsdns-35.com","ns-841.awsdns-41.net"],"delegated_name_servers":["ns1.previous-host.example","ns2.previous-host.example"],"dnssec_at_registrar":false,"version":3,"published":true,"publish_error":"","ready_to_switch":true,"not_ready_reasons":[],"record_sets":4,"captured":4,"missing":0,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z","ownership_record":null},"records":[{"name":"@","type":"MX","ttl":3600,"values":["1 aspmx.l.google.com","5 alt1.aspmx.l.google.com"],"managed_by_domain":null},{"name":"@","type":"TXT","ttl":300,"values":["v=spf1 include:_spf.google.com ~all"],"managed_by_domain":null},{"name":"_dmarc","type":"TXT","ttl":300,"values":["v=DMARC1; p=quarantine"],"managed_by_domain":null},{"name":"www","type":"CNAME","ttl":300,"values":["site.previous-host.example"],"managed_by_domain":null}]},"schema":{"additionalProperties":false,"properties":{"records":{"items":{"$ref":"#/components/schemas/DNSRecordSet"},"type":"array"},"zone":{"$ref":"#/components/schemas/DNSZone"}},"required":["zone","records"],"type":"object"}}},"description":"The zone and its records."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The workspace has no zone with that id."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_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."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Create or replace a record set","tags":["DNS AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PUT \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"www\",\n  \"type\": \"CNAME\",\n  \"ttl\": 300,\n  \"values\": [\"site.previous-host.example\"]\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records\", {\n  method: \"PUT\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"name\": \"www\",\n    \"type\": \"CNAME\",\n    \"ttl\": 300,\n    \"values\": [\"site.previous-host.example\"]\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.put(\n    \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"name\": \"www\",\n        \"type\": \"CNAME\",\n        \"ttl\": 300,\n        \"values\": [\"site.previous-host.example\"]\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"name\": \"www\",\n  \"type\": \"CNAME\",\n  \"ttl\": 300,\n  \"values\": [\"site.previous-host.example\"]\n}`)\n\treq, err := http.NewRequest(\"PUT\", \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/dns/zones/{id}/records/{type}/{name}":{"delete":{"description":"Removes every value of one name and type.\n\nPermission: `workspace`.","operationId":"deleteDNSRecordSet","parameters":[{"description":"The zone's id.","example":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"The record type.","example":"TXT","in":"path","name":"type","required":true,"schema":{"type":"string"}},{"description":"The name, relative to the zone (`@` for the domain itself).","example":"_dmarc","in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"zone":{"id":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","name":"example.com","status":"pending","status_message":"","name_servers":["ns-1093.awsdns-08.org","ns-1823.awsdns-35.co.uk","ns-282.awsdns-35.com","ns-841.awsdns-41.net"],"delegated_name_servers":["ns1.previous-host.example","ns2.previous-host.example"],"dnssec_at_registrar":false,"version":3,"published":true,"publish_error":"","ready_to_switch":true,"not_ready_reasons":[],"record_sets":4,"captured":4,"missing":0,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z","ownership_record":null},"records":[{"name":"@","type":"MX","ttl":3600,"values":["1 aspmx.l.google.com","5 alt1.aspmx.l.google.com"],"managed_by_domain":null},{"name":"@","type":"TXT","ttl":300,"values":["v=spf1 include:_spf.google.com ~all"],"managed_by_domain":null},{"name":"_dmarc","type":"TXT","ttl":300,"values":["v=DMARC1; p=quarantine"],"managed_by_domain":null},{"name":"www","type":"CNAME","ttl":300,"values":["site.previous-host.example"],"managed_by_domain":null}]},"schema":{"additionalProperties":false,"properties":{"records":{"items":{"$ref":"#/components/schemas/DNSRecordSet"},"type":"array"},"zone":{"$ref":"#/components/schemas/DNSZone"}},"required":["zone","records"],"type":"object"}}},"description":"The zone and its records."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The zone has no record set of that name and type."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The record is kept by Kilby for a custom domain."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete a record set","tags":["DNS AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records/TXT/_dmarc\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records/TXT/_dmarc\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records/TXT/_dmarc\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/records/TXT/_dmarc\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/dns/zones/{id}/verify":{"post":{"description":"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.\n\nPermission: `workspace`.","operationId":"verifyDNSZone","parameters":[{"description":"The zone's id.","example":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","name":"example.com","status":"verifying","status_message":"_kilby-challenge.example.com does not answer with this zone's value yet. DNS changes can take a few minutes to show.","name_servers":[],"delegated_name_servers":[],"dnssec_at_registrar":false,"version":0,"published":true,"publish_error":"","ready_to_switch":false,"not_ready_reasons":["Prove the domain is yours first: create the ownership record."],"record_sets":0,"captured":0,"missing":0,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z","ownership_record":{"name":"_kilby-challenge.example.com","type":"TXT","value":"kilby-verify=d4f1a07c9e3b42h8k2m5q7s9"}},"schema":{"$ref":"#/components/schemas/DNSZone"}}},"description":"The zone. Still `verifying` (with `status_message` saying what was found) until the record answers."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The workspace has no zone with that id."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Check the ownership record","tags":["DNS AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/verify\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/verify\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/verify\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/dns/zones/7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13/verify\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/domains/{id}":{"delete":{"description":"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.\n\nPermission: `deploy`.","operationId":"removeDomain","parameters":[{"description":"The domain's id.","example":"5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11","status":"deleting"},"schema":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"status":{"description":"Always deleting.","type":"string"}},"required":["id","status"],"type":"object"}}},"description":"The domain is being removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: Another domain redirects to this one."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Remove a domain","tags":["Domains"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"},"patch":{"description":"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.\n\nPermission: `deploy`.","operationId":"updateDomain","parameters":[{"description":"The domain's id.","example":"5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Send www to the root domain","value":{"redirect_to":"example.com"}},"example2":{"summary":"Serve the service again","value":{"redirect_to":null}}},"schema":{"additionalProperties":false,"properties":{"redirect_to":{"description":"Another domain of the service, or null.","type":["string","null"]}},"required":["redirect_to"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"id":"5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11","service_id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","hostname":"www.example.com","apex":false,"status":"pending_dns","status_message":"","dns_records":[{"type":"CNAME","name":"api.example.com","value":"my-api-x7k2.apps.kilby.neuramorphic.ai","purpose":"route"},{"type":"TXT","name":"_kilby-challenge.api.example.com","value":"kilby-verify=k3x9a1c7e5b2d804","purpose":"ownership"},{"type":"CNAME","name":"_acme-challenge.api.example.com","value":"k3x9a1c7e5b2d804.acme.kilby.neuramorphic.ai","purpose":"certificate"}],"verified_at":null,"certificate_expires_at":null,"certificate_validation":"http","routed_at":null,"redirect_to":"example.com","last_checked_at":null,"next_check_at":"2026-11-13T14:07:00Z","created_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/Domain"}}},"description":"The domain."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: redirect_to is missing, is not another domain of the service that serves it, or other domains redirect to this one."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Redirect a domain","tags":["Domains"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"redirect_to\": \"example.com\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"redirect_to\": \"example.com\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"redirect_to\": \"example.com\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"redirect_to\": \"example.com\"}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/domains/{id}/configure-dns":{"post":{"description":"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.\n\nPermission: `workspace`.","operationId":"configureDomainDNS","parameters":[{"description":"The domain's id.","example":"5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"zone":{"id":"7a1c3e5f-2b4d-4f60-9e81-a2c4e6f80b13","name":"example.com","status":"pending","status_message":"","name_servers":["ns-1093.awsdns-08.org","ns-1823.awsdns-35.co.uk","ns-282.awsdns-35.com","ns-841.awsdns-41.net"],"delegated_name_servers":["ns1.previous-host.example","ns2.previous-host.example"],"dnssec_at_registrar":false,"version":3,"published":true,"publish_error":"","ready_to_switch":true,"not_ready_reasons":[],"record_sets":4,"captured":4,"missing":0,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z","ownership_record":null},"records":[{"name":"@","type":"MX","ttl":3600,"values":["1 aspmx.l.google.com","5 alt1.aspmx.l.google.com"],"managed_by_domain":null},{"name":"@","type":"TXT","ttl":300,"values":["v=spf1 include:_spf.google.com ~all"],"managed_by_domain":null},{"name":"_dmarc","type":"TXT","ttl":300,"values":["v=DMARC1; p=quarantine"],"managed_by_domain":null},{"name":"www","type":"CNAME","ttl":300,"values":["site.previous-host.example"],"managed_by_domain":null}]},"schema":{"additionalProperties":false,"properties":{"records":{"items":{"$ref":"#/components/schemas/DNSRecordSet"},"type":"array"},"zone":{"$ref":"#/components/schemas/DNSZone"}},"required":["zone","records"],"type":"object"}}},"description":"The zone and its records."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The workspace has no domain with that id."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: No active zone of the workspace contains the domain."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Configure a custom domain from its zone","tags":["DNS AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/configure-dns\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/configure-dns\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/configure-dns\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/configure-dns\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/domains/{id}/verify":{"post":{"description":"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.\n\nPermission: `deploy`.","operationId":"verifyDomain","parameters":[{"description":"The domain's id.","example":"5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11","service_id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","hostname":"api.example.com","apex":false,"status":"verifying","status_message":"","dns_records":[{"type":"CNAME","name":"api.example.com","value":"my-api-x7k2.apps.kilby.neuramorphic.ai","purpose":"route"},{"type":"TXT","name":"_kilby-challenge.api.example.com","value":"kilby-verify=k3x9a1c7e5b2d804","purpose":"ownership"},{"type":"CNAME","name":"_acme-challenge.api.example.com","value":"k3x9a1c7e5b2d804.acme.kilby.neuramorphic.ai","purpose":"certificate"}],"verified_at":"2026-11-13T14:05:00Z","certificate_expires_at":null,"certificate_validation":"http","routed_at":null,"redirect_to":null,"last_checked_at":null,"next_check_at":"2026-11-13T14:07:00Z","created_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/Domain"}}},"description":"The domain after the check."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: The domain was checked a moment ago."}},"summary":"Check a domain's DNS now","tags":["Domains"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/verify\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/verify\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/verify\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/domains/5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11/verify\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/env-groups":{"get":{"description":"The workspace's groups with the names of their variables and the services that use each, never any value.\n\nPermission: `view`.","operationId":"listEnvGroups","responses":{"200":{"content":{"application/json":{"example":{"env_groups":[{"id":"c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c","name":"shared-keys","variables":["OPENAI_API_KEY","SENTRY_DSN"],"services":[{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api","position":1}],"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"}]},"schema":{"additionalProperties":false,"properties":{"env_groups":{"description":"Each shaped like Read an environment group.","items":{"type":"object"},"type":"array"}},"required":["env_groups"],"type":"object"}}},"description":"The groups, by name."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List environment groups","tags":["Environment groups"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/env-groups\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/env-groups\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/env-groups\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/env-groups\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby env-group list"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nPermission: `secrets`.","operationId":"createEnvGroup","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"With two variables","value":{"name":"shared-keys","env":{"OPENAI_API_KEY":"your-key","SENTRY_DSN":"https://example.invalid/1"}}},"example2":{"summary":"Empty","value":{"name":"flags"}}},"schema":{"additionalProperties":false,"properties":{"env":{"additionalProperties":{"type":"string"},"description":"Name to value. Allowed: 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.","type":"object"},"name":{"description":"Unique in the workspace. Allowed: 3 to 40 characters: lowercase letters, digits and single hyphens, starting with a letter.","type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"id":"c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c","name":"shared-keys","variables":["OPENAI_API_KEY","SENTRY_DSN"],"services":[],"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"},"schema":{"additionalProperties":false,"properties":{"created_at":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"services":{"description":"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).","items":{"type":"object"},"type":"array"},"updated_at":{"format":"date-time","type":"string"},"variables":{"description":"The names of the variables, sorted. Values are never returned.","items":{"type":"string"},"type":"array"}},"required":["id","name","variables","services","created_at","updated_at"],"type":"object"}}},"description":"The group."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The workspace already has a group with that name."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`too_large`: The request is larger than 512 KB."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The name or a variable is not valid, or the workspace has reached its limit of groups (20 by default)."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Create an environment group","tags":["Environment groups"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/env-groups\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"shared-keys\",\n  \"env\": {\n    \"OPENAI_API_KEY\": \"your-key\",\n    \"SENTRY_DSN\": \"https://example.invalid/1\"\n  }\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/env-groups\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"name\": \"shared-keys\",\n    \"env\": {\n      \"OPENAI_API_KEY\": \"your-key\",\n      \"SENTRY_DSN\": \"https://example.invalid/1\"\n    }\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/env-groups\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"name\": \"shared-keys\",\n        \"env\": {\n            \"OPENAI_API_KEY\": \"your-key\",\n            \"SENTRY_DSN\": \"https://example.invalid/1\"\n        }\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"name\": \"shared-keys\",\n  \"env\": {\n    \"OPENAI_API_KEY\": \"your-key\",\n    \"SENTRY_DSN\": \"https://example.invalid/1\"\n  }\n}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/env-groups\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby env-group create"}],"x-kilby-permission":"secrets"}},"/env-groups/{id}":{"delete":{"description":"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.\n\nPermission: `deploy`.","operationId":"deleteEnvGroup","parameters":[{"description":"The environment group's id.","example":"c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"`true` to delete a group that services use, unlinking them.","in":"query","name":"unlink","required":false,"schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"example":{"deleted":"shared-keys","unlinked":["my-api"],"restarted":["my-api"]},"schema":{"additionalProperties":false,"properties":{"deleted":{"description":"The group's name.","type":"string"},"restarted":{"description":"Those that were restarted.","items":{"type":"string"},"type":"array"},"unlinked":{"description":"The services that used it.","items":{"type":"string"},"type":"array"}},"required":["deleted","unlinked","restarted"],"type":"object"}}},"description":"What was deleted and which services were unlinked and restarted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such group in this workspace."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: Services still use the group, and `unlink=true` was not sent."},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete an environment group","tags":["Environment groups"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"},"get":{"description":"One group: the names of its variables, never their values, and the services that use it.\n\nPermission: `view`.","operationId":"getEnvGroup","parameters":[{"description":"The environment group's id.","example":"c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c","name":"shared-keys","variables":["OPENAI_API_KEY","SENTRY_DSN"],"services":[{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api","position":1}],"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"},"schema":{"additionalProperties":false,"properties":{"created_at":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"services":{"description":"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).","items":{"type":"object"},"type":"array"},"updated_at":{"format":"date-time","type":"string"},"variables":{"description":"The names of the variables, sorted. Values are never returned.","items":{"type":"string"},"type":"array"}},"required":["id","name","variables","services","created_at","updated_at"],"type":"object"}}},"description":"The group."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such group in this workspace."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Read an environment group","tags":["Environment groups"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"patch":{"description":"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.\n\nPermission: `secrets`.","operationId":"patchEnvGroup","parameters":[{"description":"The environment group's id.","example":"c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Set one and remove one","value":{"set":{"SENTRY_DSN":"https://example.invalid/2"},"unset":["OLD_FLAG"]}},"example2":{"summary":"Rename","value":{"name":"platform-keys"}}},"schema":{"additionalProperties":false,"properties":{"name":{"description":"A new name.","type":"string"},"set":{"additionalProperties":{"type":"string"},"description":"Name to value. Allowed: names of letters, digits and underscores up to 128 characters, values up to 8 KB, up to 100 variables per request.","type":"object"},"unset":{"description":"Names to remove.","items":{"type":"string"},"type":"array"}},"type":"object"}}},"description":"Every field is optional; `{}` changes nothing. Unknown fields, `null`, a value that is not a string and a name in both lists are refused.","required":false},"responses":{"200":{"content":{"application/json":{"example":{"id":"c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c","name":"shared-keys","variables":["OPENAI_API_KEY","SENTRY_DSN"],"added":[],"changed":["SENTRY_DSN"],"removed":["OLD_FLAG"],"restarted":["my-api"]},"schema":{"additionalProperties":false,"properties":{"added":{"items":{"type":"string"},"type":"array"},"changed":{"items":{"type":"string"},"type":"array"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"removed":{"items":{"type":"string"},"type":"array"},"restarted":{"description":"The names of the services that were restarted.","items":{"type":"string"},"type":"array"},"variables":{"items":{"type":"string"},"type":"array"}},"required":["id","name","variables","added","changed","removed","restarted"],"type":"object"}}},"description":"The names now set, what changed and which services restarted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such group in this workspace."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: Another group has that name."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`too_large`: The request is larger than 512 KB."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_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."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Change an environment group","tags":["Environment groups"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"set\": {\"SENTRY_DSN\": \"https://example.invalid/2\"},\n  \"unset\": [\"OLD_FLAG\"]\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"set\": {\"SENTRY_DSN\": \"https://example.invalid/2\"},\n    \"unset\": [\"OLD_FLAG\"]\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"set\": {\"SENTRY_DSN\": \"https://example.invalid/2\"},\n        \"unset\": [\"OLD_FLAG\"]\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"set\": {\"SENTRY_DSN\": \"https://example.invalid/2\"},\n  \"unset\": [\"OLD_FLAG\"]\n}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/env-groups/c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby env-group set"}],"x-kilby-permission":"secrets"}},"/git/branches":{"get":{"description":"The branches of a repository, the default one first.\n\nPermission: `view`.","operationId":"listGitBranches","parameters":[{"description":"The GitHub connection to read through: the id of an entry of List GitHub connections.","example":1001,"in":"query","name":"installation","required":true,"schema":{"type":"integer"}},{"description":"The repository, written owner/name.","example":"acme/express-api","in":"query","name":"repo","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"default":"main","branches":["main","staging"]},"schema":{"additionalProperties":false,"properties":{"branches":{"items":{"type":"string"},"type":"array"},"default":{"description":"The default branch.","type":"string"}},"required":["default","branches"],"type":"object"}}},"description":"The branches."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_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."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_connected`: GitHub is not turned on for this Kilby, or its App is not registered yet."},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`github_unavailable`: GitHub could not be reached or answered something Kilby could not read. Try again in a moment."}},"summary":"List branches","tags":["GitHub and Git"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/git/branches?installation=1001\u0026repo=acme%2Fexpress-api\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/git/branches?installation=1001\\u0026repo=acme%2Fexpress-api\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/git/branches?installation=1001\\u0026repo=acme%2Fexpress-api\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/git/branches?installation=1001\u0026repo=acme%2Fexpress-api\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/git/commit":{"get":{"description":"The commit a build of this branch would build now.\n\nPermission: `view`.","operationId":"getGitCommit","parameters":[{"description":"The GitHub connection to read through: the id of an entry of List GitHub connections.","example":1001,"in":"query","name":"installation","required":true,"schema":{"type":"integer"}},{"description":"The repository, written owner/name.","example":"acme/express-api","in":"query","name":"repo","required":true,"schema":{"type":"string"}},{"description":"The branch.","example":"main","in":"query","name":"branch","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"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"}},"schema":{"additionalProperties":false,"properties":{"commit":{"$ref":"#/components/schemas/GitCommit"}},"required":["commit"],"type":"object"}}},"description":"The commit."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_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."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_connected`: GitHub is not turned on for this Kilby, or its App is not registered yet."},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`github_unavailable`: GitHub could not be reached or answered something Kilby could not read. Try again in a moment."}},"summary":"Get the latest commit of a branch","tags":["GitHub and Git"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/git/commit?branch=main\u0026installation=1001\u0026repo=acme%2Fexpress-api\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/git/commit?branch=main\\u0026installation=1001\\u0026repo=acme%2Fexpress-api\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/git/commit?branch=main\\u0026installation=1001\\u0026repo=acme%2Fexpress-api\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/git/commit?branch=main\u0026installation=1001\u0026repo=acme%2Fexpress-api\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/git/installations":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"listGitInstallations","responses":{"200":{"content":{"application/json":{"example":{"mode":"live","state":"ready","connected":true,"installations":[{"id":1001,"account":"acme","type":"Organization","repository_selection":"all","suspended":false,"linked_by":"Ada Lovelace","linked_at":"2026-11-13T14:05:00Z"}]},"schema":{"additionalProperties":false,"properties":{"connected":{"description":"false until a platform admin has registered the GitHub App.","type":"boolean"},"installations":{"items":{"$ref":"#/components/schemas/GitInstallation"},"type":"array"},"mode":{"description":"How GitHub is wired on this server.","enum":["off","fake","live"],"type":"string"},"state":{"description":"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).","enum":["off","needs_app","ready"],"type":"string"}},"required":["mode","state","connected","installations"],"type":"object"}}},"description":"The connections."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List GitHub connections","tags":["GitHub and Git"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/git/installations\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/git/installations\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/git/installations\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/git/installations\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/git/plan":{"get":{"description":"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.\n\nWhen 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.\n\nPermission: `deploy`.","operationId":"getGitPlan","parameters":[{"description":"The GitHub connection to read through: the id of an entry of List GitHub connections.","example":1001,"in":"query","name":"installation","required":true,"schema":{"type":"integer"}},{"description":"The repository, written owner/name.","example":"acme/express-api","in":"query","name":"repo","required":true,"schema":{"type":"string"}},{"description":"The branch to analyse.","example":"main","in":"query","name":"branch","required":false,"schema":{"type":"string"}},{"description":"The folder to analyse, for a monorepo. Empty is the repository root.","in":"query","name":"root","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"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"},"schema":{"additionalProperties":false,"properties":{"branch":{"description":"The branch that was read.","type":"string"},"commit":{"$ref":"#/components/schemas/GitCommit","description":"The commit that was read."},"error":{"description":"null when the folder can be built.","oneOf":[{"additionalProperties":false,"properties":{"code":{"description":"A stable name, such as nothing_to_build, empty_repo, folder_not_found, unsupported_runtime, monorepo_root or invalid_manifest.","type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},{"type":"null"}]},"plan":{"$ref":"#/components/schemas/BuildPlan"},"repo":{"description":"owner/name.","type":"string"},"repo_url":{"description":"The repository on GitHub.","format":"uri","type":"string"}},"required":["plan","error","commit","repo","branch","repo_url"],"type":"object"}}},"description":"The plan, and why it cannot be built when it cannot."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_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."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_connected`: GitHub is not turned on for this Kilby, or its App is not registered yet."},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 20 analyses a minute for this person. The Retry-After header says how long to wait."},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`github_unavailable`: GitHub could not be reached or answered something Kilby could not read. Try again in a moment."}},"summary":"Analyse a repository","tags":["GitHub and Git"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/git/plan?branch=main\u0026installation=1001\u0026repo=acme%2Fexpress-api\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/git/plan?branch=main\\u0026installation=1001\\u0026repo=acme%2Fexpress-api\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/git/plan?branch=main\\u0026installation=1001\\u0026repo=acme%2Fexpress-api\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/git/plan?branch=main\u0026installation=1001\u0026repo=acme%2Fexpress-api\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/git/public/check":{"get":{"description":"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.\n\n`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.\n\nPermission: `deploy`.","operationId":"getPublicGitCheck","parameters":[{"description":"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.","example":"https://github.com/acme/express-api","in":"query","name":"url","required":true,"schema":{"type":"string"}},{"description":"The branch, tag or full commit id. Empty is the repository's default branch.","example":"main","in":"query","name":"ref","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"ok":true,"host":"github.com","repo":"acme/express-api","repo_url":"https://github.com/acme/express-api","ref":"main","default_branch":false,"root":"","commit":{"sha":"8a2e7d9a74a99a24383b37a774d17ddd931058c0","short":"8a2e7d9","known":true,"url":"https://github.com/acme/express-api/commit/8a2e7d9a74a99a24383b37a774d17ddd931058c0"}},"schema":{"additionalProperties":false,"properties":{"commit":{"$ref":"#/components/schemas/PublicCommit"},"default_branch":{"description":"The ref is the default branch.","type":"boolean"},"host":{"description":"For example github.com.","type":"string"},"ok":{"description":"Always true.","type":"boolean"},"ref":{"description":"The ref that was checked; HEAD is the default branch.","type":"string"},"repo":{"description":"The path on the host: owner/name, or group/subgroup/project on GitLab.","type":"string"},"repo_url":{"description":"The repository's page.","format":"uri","type":"string"},"root":{"description":"The folder a branch page's address named (https://github.com/acme/api/tree/main/apps/web), empty when it named none.","type":"string"}},"required":["ok","host","repo","repo_url","ref","default_branch","root","commit"],"type":"object"}}},"description":"The repository exists and is public."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_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."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_available`: Deploying from Git is not turned on for this Kilby yet, so nothing can be read."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_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."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_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."},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`host_unavailable`: The Git host did not answer or answered with an error. Try again in a few minutes."}},"summary":"Check a public repository","tags":["GitHub and Git"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/git/public/check?ref=main\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/git/public/check?ref=main\\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/git/public/check?ref=main\\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/git/public/check?ref=main\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/git/public/plan":{"get":{"description":"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.\n\nThe archive is read in memory under the same limits as a build's (size, number of files, links and paths); an archive that a build would refuse is refused here, with `error.code` `archive_refused` or `too_large`. An answer is kept for 60 seconds, and a person can ask for 10 new analyses a minute.\n\nPermission: `deploy`.","operationId":"getPublicGitPlan","parameters":[{"description":"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.","example":"https://github.com/acme/express-api","in":"query","name":"url","required":true,"schema":{"type":"string"}},{"description":"The branch, tag or full commit id. Empty is the repository's default branch.","example":"main","in":"query","name":"ref","required":false,"schema":{"type":"string"}},{"description":"The folder to analyse, for a monorepo. Empty is the repository root.","in":"query","name":"root","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"plan":{"root_dir":"","strategy":"generated","runtime":"node","framework":"express","dockerfile_path":"","install_command":"npm install","build_command":"","start_command":"npm start","port":3000,"health_path":"/healthz","plan_id":"starter","env":[{"name":"DATABASE_URL","example":"","secret":true},{"name":"LOG_LEVEL","example":"info","secret":false}],"notes":["We found an Express app and will build it with npm."],"warnings":["No lockfile found: builds may not be reproducible."],"candidates":[],"kind":"web","version":"22","package_manager":"npm"},"error":null,"source":"public_git","host":"github.com","repo":"acme/express-api","repo_url":"https://github.com/acme/express-api","ref":"main","default_branch":false,"commit":{"sha":"8a2e7d9a74a99a24383b37a774d17ddd931058c0","short":"8a2e7d9","known":true,"url":"https://github.com/acme/express-api/commit/8a2e7d9a74a99a24383b37a774d17ddd931058c0"}},"schema":{"additionalProperties":false,"properties":{"commit":{"$ref":"#/components/schemas/PublicCommit","description":"The commit the archive is of."},"default_branch":{"type":"boolean"},"error":{"description":"null when the folder can be built.","oneOf":[{"additionalProperties":false,"properties":{"code":{"description":"A stable name, such as nothing_to_build, empty_repo, monorepo_root, too_large or archive_refused.","type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},{"type":"null"}]},"host":{"type":"string"},"plan":{"$ref":"#/components/schemas/BuildPlan"},"ref":{"type":"string"},"repo":{"type":"string"},"repo_url":{"format":"uri","type":"string"},"source":{"description":"Always public_git.","type":"string"}},"required":["plan","error","source","host","repo","repo_url","ref","default_branch","commit"],"type":"object"}}},"description":"The plan, and why it cannot be built when it cannot."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_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."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_available`: Deploying from Git is not turned on for this Kilby yet, so nothing can be read."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_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."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_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."},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`host_unavailable`: The Git host did not answer or answered with an error. Try again in a few minutes."}},"summary":"Analyse a public repository","tags":["GitHub and Git"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/git/public/plan?ref=main\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/git/public/plan?ref=main\\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/git/public/plan?ref=main\\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/git/public/plan?ref=main\u0026url=https%3A%2F%2Fgithub.com%2Facme%2Fexpress-api\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/git/repos":{"get":{"description":"The repositories Kilby can read through one connection, most recently pushed first, at most 100. The list is kept for 20 seconds.\n\nPermission: `view`.","operationId":"listGitRepos","parameters":[{"description":"The GitHub connection to read through: the id of an entry of List GitHub connections.","example":1001,"in":"query","name":"installation","required":true,"schema":{"type":"integer"}},{"description":"Only repositories whose name contains this text.","example":"api","in":"query","name":"q","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"repos":[{"id":1000,"full_name":"acme/express-api","private":true,"default_branch":"main","pushed_at":"2026-11-13T14:05:00Z","installation_id":1001,"owner":"acme"}],"total":1,"truncated":false},"schema":{"additionalProperties":false,"properties":{"repos":{"items":{"$ref":"#/components/schemas/GitRepo"},"type":"array"},"total":{"description":"How many repositories the connection can read.","type":"integer"},"truncated":{"description":"true when there are more than were returned.","type":"boolean"}},"required":["repos","total","truncated"],"type":"object"}}},"description":"The repositories."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_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."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_connected`: GitHub is not turned on for this Kilby, or its App is not registered yet."},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`github_unavailable`: GitHub could not be reached or answered something Kilby could not read. Try again in a moment."}},"summary":"List repositories","tags":["GitHub and Git"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/git/repos?installation=1001\u0026q=api\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/git/repos?installation=1001\\u0026q=api\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/git/repos?installation=1001\\u0026q=api\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/git/repos?installation=1001\u0026q=api\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/hooks/deploy/{token}":{"post":{"description":"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).\n\nIt 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.","operationId":"callDeployHook","parameters":[{"description":"The secret part of the hook URL, starting with kdh_.","example":"kdh_3f9a1c7e5b2d8046","in":"path","name":"token","required":true,"schema":{"type":"string"}},{"description":"A new tag or digest of the service's own image repository.","example":"ghcr.io/acme/api:3f2a9c1","in":"query","name":"image","required":false,"schema":{"type":"string"}},{"description":"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. Allowed: up to 120 characters.","example":"Fix login redirect","in":"query","name":"title","required":false,"schema":{"type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"deploy":{"id":"5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d","status":"queued","image":"ghcr.io/acme/api:3f2a9c1","trigger":"hook","title":"Fix login redirect (3f2a9c1)"},"service":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api"}},"schema":{"additionalProperties":false,"properties":{"deploy":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"image":{"type":"string"},"status":{"description":"Always queued.","type":"string"},"title":{"description":"The tag it deployed, and your title when you sent one.","type":"string"},"trigger":{"description":"Always hook.","type":"string"}},"required":["id","status","image","trigger","title"],"type":"object"},"service":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"}},"required":["deploy","service"],"type":"object"}}},"description":"The deploy has been queued."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The hook does not exist or was revoked."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is suspended."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: image is not in the service's own repository, or the title is longer than 120 characters."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 10 deploys a minute for this hook, or 60 requests a minute from your address."}},"security":[],"summary":"Deploy with a deploy hook","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046?image=ghcr.io%2Facme%2Fapi%3A3f2a9c1\u0026title=Fix+login+redirect\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046?image=ghcr.io%2Facme%2Fapi%3A3f2a9c1\\u0026title=Fix+login+redirect\", {\n  method: \"POST\",\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046?image=ghcr.io%2Facme%2Fapi%3A3f2a9c1\\u0026title=Fix+login+redirect\",\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046?image=ghcr.io%2Facme%2Fapi%3A3f2a9c1\u0026title=Fix+login+redirect\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"none"},"servers":[{"description":"The site itself","url":"https://onkilby.com"}]},"/hooks/git/{token}":{"post":{"description":"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.\n\nIt 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.","operationId":"callGitHook","parameters":[{"description":"The secret part of the hook URL, starting with kgh_.","example":"kdh_3f9a1c7e5b2d8046","in":"path","name":"token","required":true,"schema":{"type":"string"}},{"description":"Build even when the commit did not change.","example":false,"in":"query","name":"force","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"example":{"status":"up_to_date","commit":{"sha":"8a2e7d9a74a99a24383b37a774d17ddd931058c0","known":true},"build":{"number":6,"status":"succeeded"},"service":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api"}},"schema":{"additionalProperties":false,"properties":{"build":{"additionalProperties":false,"description":"The build that has this commit.","properties":{"number":{"type":"integer"},"status":{"type":"string"}},"required":["number","status"],"type":"object"},"commit":{"additionalProperties":false,"properties":{"known":{"type":"boolean"},"sha":{"type":"string"}},"required":["sha","known"],"type":"object"},"service":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"status":{"description":"up_to_date.","type":"string"}},"required":["status","commit","build","service"],"type":"object"}}},"description":"Nothing new: the latest commit was already built (or is being built)."},"202":{"content":{"application/json":{"example":{"status":"queued","commit":{"sha":"8a2e7d9a74a99a24383b37a774d17ddd931058c0","known":true},"build":{"id":"5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24","number":7,"status":"queued","trigger":"hook"},"service":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api"}},"schema":{"additionalProperties":false,"properties":{"build":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"number":{"type":"integer"},"status":{"type":"string"},"trigger":{"description":"Always hook.","type":"string"}},"required":["id","number","status","trigger"],"type":"object"},"commit":{"additionalProperties":false,"properties":{"known":{"type":"boolean"},"sha":{"description":"Empty when the archive does not say.","type":"string"}},"required":["sha","known"],"type":"object"},"service":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"status":{"description":"queued.","type":"string"}},"required":["status","commit","build","service"],"type":"object"}}},"description":"A build was queued."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The hook does not exist or was revoked."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is suspended."},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_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."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: Deploying from Git is not turned on for this Kilby yet."}},"security":[],"summary":"Build the latest commit with a build hook","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/hooks/git/kdh_3f9a1c7e5b2d8046?force=1\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/hooks/git/kdh_3f9a1c7e5b2d8046?force=1\", {\n  method: \"POST\",\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/hooks/git/kdh_3f9a1c7e5b2d8046?force=1\",\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/hooks/git/kdh_3f9a1c7e5b2d8046?force=1\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"none"},"servers":[{"description":"The site itself","url":"https://onkilby.com"}]},"/images/check":{"post":{"description":"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.\n\nKilby 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`.\n\n`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.\n\nA 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.\n\nPermission: `deploy`.","operationId":"checkImage","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"A public image","value":{"image":"ghcr.io/acme/api:1.4"}},"example2":{"summary":"A private image","value":{"image":"ghcr.io/acme/private-api:2","registry_credential_id":"9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12"}}},"schema":{"additionalProperties":false,"properties":{"image":{"description":"The image reference, as in `image` of a service. Allowed: a registry reference, tag or digest.","type":"string"},"registry_credential_id":{"description":"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.","format":"uuid","type":["string","null"]}},"required":["image"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"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"},"schema":{"additionalProperties":false,"properties":{"blocking":{"description":"true for `not_found`, `bad_credentials` and `no_amd64`.","type":"boolean"},"checked_at":{"description":"When the registry was asked (an answer from the 60 second cache keeps its time).","format":"date-time","type":"string"},"digest":{"description":"The manifest the tag points to now. Only present when the image was found.","type":"string"},"image":{"description":"The reference with the defaults spelled out: Docker Hub shorthand, `library/`, and `latest` when you gave no tag.","type":"string"},"message":{"description":"One or two sentences for people, with what to do. It may change; branch on `state`.","type":"string"},"platforms":{"description":"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.","items":{"type":"string"},"type":"array"},"port":{"description":"The port Kilby fills into the form: only present when the image declares exactly one. A port below 1024 is fine for an image.","type":"integer"},"port_note":{"description":"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.","type":"string"},"ports":{"description":"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.","items":{"type":"integer"},"type":"array"},"registry":{"description":"The registry the image comes from.","type":"string"},"size_bytes":{"description":"The compressed size of the layers for `linux/amd64`. Only present when it could be read.","type":"integer"},"state":{"description":"What was found.","enum":["ok","not_found","needs_credentials","bad_credentials","no_amd64","unknown"],"type":"string"}},"required":["state","message","blocking","image","registry","platforms","ports","checked_at"],"type":"object"}}},"description":"What the registry said. `blocking` is true when saving a service with this image would be refused."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The registry credentials do not exist in this workspace."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The image is not a valid reference, or the registry is not allowed for services."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 40 checks a minute for one person, or 120 for the workspace."}},"summary":"Check a container image","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/images/check\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"image\": \"ghcr.io/acme/api:1.4\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/images/check\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"image\": \"ghcr.io/acme/api:1.4\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/images/check\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"image\": \"ghcr.io/acme/api:1.4\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"image\": \"ghcr.io/acme/api:1.4\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/images/check\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby images check"}],"x-kilby-permission":"deploy"}},"/key-values":{"get":{"description":"The workspace's Key Value instances. The connection URL, which holds the password, is not in the list: use Get the connection.\n\nPermission: `view`.","operationId":"listKeyValues","responses":{"200":{"content":{"application/json":{"example":{"key_values":[{"id":"a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73","name":"cache","plan":"1gb","memory_mb":1024,"max_memory_mb":768,"disk_gb":2,"eviction_policy":"allkeys-lru","status":"available","status_message":"","host":"kv-cache","port":6379,"created_at":"2026-11-12T22:40:11Z","environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}}}]},"schema":{"additionalProperties":false,"properties":{"key_values":{"items":{"$ref":"#/components/schemas/KeyValue"},"type":"array"}},"required":["key_values"],"type":"object"}}},"description":"The instances."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List Key Value instances","tags":["Key Value"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/key-values\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/key-values\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/key-values\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/key-values\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby kv list"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nData 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.\n\nPermission: `deploy`.","operationId":"createKeyValue","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"A cache","value":{"name":"cache","plan":"1gb","eviction_policy":"allkeys-lru"}},"example2":{"summary":"A queue","value":{"name":"queue","plan":"256mb","eviction_policy":"noeviction"}}},"schema":{"additionalProperties":false,"properties":{"environment":{"description":"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.","type":"string"},"eviction_policy":{"default":"allkeys-lru","description":"What happens when memory is full: allkeys-lru removes the keys used least recently (a cache), noeviction refuses writes (a queue).","enum":["allkeys-lru","noeviction"],"type":"string"},"name":{"description":"Unique in the workspace. Allowed: 3 to 30 characters: lowercase letters, digits and hyphens, starting with a letter.","type":"string"},"plan":{"default":"256mb","description":"The size, by memory.","enum":["256mb","1gb","4gb"],"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"id":"a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73","name":"cache","plan":"1gb","memory_mb":1024,"max_memory_mb":768,"disk_gb":2,"eviction_policy":"allkeys-lru","status":"creating","status_message":"Starting…","host":"kv-cache","port":6379,"internal_url":"redis://:Zq7xV2mKd9PtR4wB@kv-cache:6379","created_at":"2026-11-12T22:40:11Z","environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}}},"schema":{"$ref":"#/components/schemas/KeyValue"}}},"description":"The new instance, with its connection URL."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: Key Value is not turned on."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A field is not valid, the name is taken, or the workspace's instance, memory, CPU or disk limit would be exceeded."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Create a Key Value instance","tags":["Key Value"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/key-values\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"cache\", \"plan\": \"1gb\", \"eviction_policy\": \"allkeys-lru\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/key-values\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"name\": \"cache\", \"plan\": \"1gb\", \"eviction_policy\": \"allkeys-lru\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/key-values\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"name\": \"cache\", \"plan\": \"1gb\", \"eviction_policy\": \"allkeys-lru\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"name\": \"cache\", \"plan\": \"1gb\", \"eviction_policy\": \"allkeys-lru\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/key-values\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby kv create cache --plan 1gb"}],"x-kilby-permission":"deploy"}},"/key-values/{id}":{"delete":{"description":"Deletes the instance, its disk and everything on it. This cannot be undone and there is no backup to restore from.\n\nPermission: `deploy`.","operationId":"deleteKeyValue","parameters":[{"description":"The instance's id.","example":"a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73","status":"deleting"},"schema":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"status":{"description":"Always deleting.","type":"string"}},"required":["id","status"],"type":"object"}}},"description":"The instance is being deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete a Key Value instance","tags":["Key Value"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby kv delete cache"}],"x-kilby-permission":"deploy"},"get":{"description":"One instance with its status and address. It never includes the password: Get the connection does, for keys that may see secrets.\n\nPermission: `view`.","operationId":"getKeyValue","parameters":[{"description":"The instance's id.","example":"a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73","name":"cache","plan":"1gb","memory_mb":1024,"max_memory_mb":768,"disk_gb":2,"eviction_policy":"allkeys-lru","status":"available","status_message":"","host":"kv-cache","port":6379,"created_at":"2026-11-12T22:40:11Z","environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}}},"schema":{"$ref":"#/components/schemas/KeyValue"}}},"description":"The instance."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a Key Value instance","tags":["Key Value"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby kv info cache"}],"x-kilby-permission":"view"},"patch":{"description":"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.\n\nPermission: `deploy`.","operationId":"updateKeyValue","parameters":[{"description":"The instance's id.","example":"a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Make it bigger","value":{"plan":"4gb"}},"example2":{"summary":"Move it to another environment","value":{"environment":"Checkout app/Staging"}}},"schema":{"additionalProperties":false,"properties":{"environment":{"description":"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`.","type":"string"},"eviction_policy":{"description":"The new policy.","enum":["allkeys-lru","noeviction"],"type":"string"},"plan":{"description":"The new size.","enum":["256mb","1gb","4gb"],"type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"id":"a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73","name":"cache","plan":"4gb","memory_mb":1024,"max_memory_mb":768,"disk_gb":2,"eviction_policy":"allkeys-lru","status":"updating","status_message":"","host":"kv-cache","port":6379,"created_at":"2026-11-12T22:40:11Z","environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}}},"schema":{"$ref":"#/components/schemas/KeyValue"}}},"description":"The instance."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A field is not valid, nothing was sent, or the change would exceed the workspace's limits."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Change the size or the eviction policy","tags":["Key Value"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"plan\": \"4gb\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"plan\": \"4gb\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"plan\": \"4gb\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"plan\": \"4gb\"}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/key-values/{id}/connection":{"get":{"description":"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.\n\nPermission: `secrets`.","operationId":"getKeyValueConnection","parameters":[{"description":"The instance's id.","example":"a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"host":"kv-cache","port":6379,"password":"Zq7xV2mKd9PtR4wB","internal_url":"redis://:Zq7xV2mKd9PtR4wB@kv-cache:6379"},"schema":{"additionalProperties":false,"properties":{"host":{"type":"string"},"internal_url":{"description":"A redis:// URL with the password.","type":"string"},"password":{"type":"string"},"port":{"type":"integer"}},"required":["host","port","password","internal_url"],"type":"object"}}},"description":"The connection."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get the connection","tags":["Key Value"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73/connection\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73/connection\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73/connection\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/key-values/a8e2d4c6-1b3f-4057-9c8d-6e0f2a4b1d73/connection\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"secrets"}},"/log-streams":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"listLogStreams","responses":{"200":{"content":{"application/json":{"example":{"enabled":true,"limit":3,"log_streams":[{"id":"d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64","name":"Datadog production","kind":"datadog","enabled":true,"state":"healthy","created_at":"2026-11-13T14:05:00Z","endpoint":"","options":{"site":"eu1","tags":"env:prod,team:ai"},"services":[],"min_level":"info","secret":{"set":true,"last4":"c0de"},"last_success_at":"2026-11-13T14:05:00Z","last_error":"","disabled_reason":"","last_test":{"at":"2026-11-13T14:05:00Z","ok":true,"status":"Datadog answered HTTP 202."},"today":{"lines_sent":12408,"bytes_sent":1960112,"dropped":{"slow":0,"rate":0,"daily":0,"failed":0}},"updated_at":"2026-11-13T14:05:00Z"}]},"schema":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"limit":{"description":"How many log streams a workspace can have.","type":"integer"},"log_streams":{"items":{"$ref":"#/components/schemas/LogStream"},"type":"array"},"unavailable_reason":{"description":"Why forwarding is not available. Only when it is not.","type":"string"}},"required":["enabled","limit","log_streams"],"type":"object"}}},"description":"The log streams."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List log streams","tags":["Log streams"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/log-streams\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/log-streams\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/log-streams\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/log-streams\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby log-stream list"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nNeeds an admin key. A workspace can have up to three log streams.\n\nPermission: `workspace`.","operationId":"createLogStream","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Datadog","value":{"name":"Datadog production","kind":"datadog","secret":"0123456789abcdef0123456789abc0de","options":{"site":"eu1","tags":"env:prod,team:ai"},"min_level":"info"}},"example2":{"summary":"HTTPS endpoint","value":{"name":"Log sink","kind":"https","endpoint":"https://logs.example.com/ingest","secret":"example-bearer-token-0001","options":{"format":"ndjson","gzip":true},"services":["my-api"]}},"example3":{"summary":"Syslog over TLS","value":{"name":"Papertrail","kind":"syslog","endpoint":"logs.example.com:6514","options":{"facility":"local0"}}}},"schema":{"additionalProperties":false,"properties":{"enabled":{"default":true,"description":"Whether to forward lines.","type":"boolean"},"endpoint":{"description":"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. Allowed: up to 500 characters.","type":"string"},"kind":{"description":"The provider. It cannot be changed later.","enum":["datadog","https","syslog","loki","betterstack"],"type":"string"},"min_level":{"default":"debug","description":"The lowest level forwarded. The level is guessed from the line, like the Logs tab does.","enum":["debug","info","warn","error"],"type":"string"},"name":{"description":"A name for the destination, unique in the workspace. Allowed: 1 to 60 characters.","type":"string"},"options":{"description":"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.","type":"object"},"secret":{"description":"The API key or token: required for Datadog and Better Stack, optional for the others. It is stored encrypted and never returned. Allowed: 12 to 512 visible characters.","type":"string"},"services":{"description":"Service names or ids to forward. Empty or left out is every service. Allowed: up to 50 services of this workspace.","items":{"type":"string"},"type":"array"}},"required":["name","kind"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"id":"d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64","name":"Datadog production","kind":"datadog","enabled":true,"state":"healthy","created_at":"2026-11-13T14:05:00Z","endpoint":"","options":{"site":"eu1","tags":"env:prod,team:ai"},"services":[],"min_level":"info","secret":{"set":true,"last4":"c0de"},"last_success_at":"2026-11-13T14:05:00Z","last_error":"","disabled_reason":"","last_test":{"at":"2026-11-13T14:05:00Z","ok":true,"status":"Datadog answered HTTP 202."},"today":{"lines_sent":12408,"bytes_sent":1960112,"dropped":{"slow":0,"rate":0,"daily":0,"failed":0}},"updated_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/LogStream"}}},"description":"The log stream."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`forbidden`: The key is not an admin key."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The name is taken, or the workspace already has three log streams."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A field is not valid: a private or non-https address, a credential in the URL, a token that is too short, an unknown service."},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: Log forwarding is not available: log storage is off, or log streams are."}},"summary":"Add a log stream","tags":["Log streams"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/log-streams\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"Datadog production\",\n  \"kind\": \"datadog\",\n  \"secret\": \"0123456789abcdef0123456789abc0de\",\n  \"options\": {\"site\": \"eu1\", \"tags\": \"env:prod,team:ai\"},\n  \"min_level\": \"info\"\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/log-streams\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"name\": \"Datadog production\",\n    \"kind\": \"datadog\",\n    \"secret\": \"0123456789abcdef0123456789abc0de\",\n    \"options\": {\"site\": \"eu1\", \"tags\": \"env:prod,team:ai\"},\n    \"min_level\": \"info\"\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/log-streams\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"name\": \"Datadog production\",\n        \"kind\": \"datadog\",\n        \"secret\": \"0123456789abcdef0123456789abc0de\",\n        \"options\": {\"site\": \"eu1\", \"tags\": \"env:prod,team:ai\"},\n        \"min_level\": \"info\"\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"name\": \"Datadog production\",\n  \"kind\": \"datadog\",\n  \"secret\": \"0123456789abcdef0123456789abc0de\",\n  \"options\": {\"site\": \"eu1\", \"tags\": \"env:prod,team:ai\"},\n  \"min_level\": \"info\"\n}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/log-streams\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby log-stream add"}],"x-kilby-permission":"workspace"}},"/log-streams/{id}":{"delete":{"description":"Deletes the destination and its counters. Nothing more is sent to it. Logs already stored in Kilby are not touched.\n\nPermission: `workspace`.","operationId":"deleteLogStream","parameters":[{"description":"The log stream's id.","example":"d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Deleted. There is no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`forbidden`: The key is not an admin key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such log stream in this workspace."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete a log stream","tags":["Log streams"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status); // 204: nothing to read\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code)  # 204: nothing to read\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby log-stream rm"}],"x-kilby-permission":"workspace"},"get":{"description":"One log stream, with the same visibility rules as the list.\n\nPermission: `view`.","operationId":"getLogStream","parameters":[{"description":"The log stream's id.","example":"d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64","name":"Datadog production","kind":"datadog","enabled":true,"state":"healthy","created_at":"2026-11-13T14:05:00Z","endpoint":"","options":{"site":"eu1","tags":"env:prod,team:ai"},"services":[],"min_level":"info","secret":{"set":true,"last4":"c0de"},"last_success_at":"2026-11-13T14:05:00Z","last_error":"","disabled_reason":"","last_test":{"at":"2026-11-13T14:05:00Z","ok":true,"status":"Datadog answered HTTP 202."},"today":{"lines_sent":12408,"bytes_sent":1960112,"dropped":{"slow":0,"rate":0,"daily":0,"failed":0}},"updated_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/LogStream"}}},"description":"The log stream."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such log stream in this workspace."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Read a log stream","tags":["Log streams"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"patch":{"description":"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.\n\nPermission: `workspace`.","operationId":"patchLogStream","parameters":[{"description":"The log stream's id.","example":"d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Only errors and warnings","value":{"min_level":"warn"}},"example2":{"summary":"Turn it back on","value":{"enabled":true}}},"schema":{"additionalProperties":false,"properties":{"enabled":{"default":true,"description":"Whether to forward lines.","type":"boolean"},"endpoint":{"description":"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. Allowed: up to 500 characters.","type":"string"},"min_level":{"default":"debug","description":"The lowest level forwarded. The level is guessed from the line, like the Logs tab does.","enum":["debug","info","warn","error"],"type":"string"},"name":{"description":"A name for the destination, unique in the workspace. Allowed: 1 to 60 characters.","type":"string"},"options":{"description":"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.","type":"object"},"remove_secret":{"default":false,"description":"Remove the stored credential (not for Datadog or Better Stack).","type":"boolean"},"secret":{"description":"The API key or token: required for Datadog and Better Stack, optional for the others. It is stored encrypted and never returned. Allowed: 12 to 512 visible characters.","type":"string"},"services":{"description":"Service names or ids to forward. Empty or left out is every service. Allowed: up to 50 services of this workspace.","items":{"type":"string"},"type":"array"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"id":"d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64","name":"Datadog production","kind":"datadog","enabled":true,"state":"healthy","created_at":"2026-11-13T14:05:00Z","endpoint":"","options":{"site":"eu1","tags":"env:prod,team:ai"},"services":[],"min_level":"info","secret":{"set":true,"last4":"c0de"},"last_success_at":"2026-11-13T14:05:00Z","last_error":"","disabled_reason":"","last_test":{"at":"2026-11-13T14:05:00Z","ok":true,"status":"Datadog answered HTTP 202."},"today":{"lines_sent":12408,"bytes_sent":1960112,"dropped":{"slow":0,"rate":0,"daily":0,"failed":0}},"updated_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/LogStream"}}},"description":"The log stream."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`forbidden`: The key is not an admin key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such log stream in this workspace."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The name is taken, or the workspace already has three log streams."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A field is not valid: a private or non-https address, a credential in the URL, a token that is too short, an unknown service."},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: Log forwarding is not available: log storage is off, or log streams are."}},"summary":"Change a log stream","tags":["Log streams"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"min_level\": \"warn\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"min_level\": \"warn\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"min_level\": \"warn\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"min_level\": \"warn\"}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/log-streams/{id}/test":{"post":{"description":"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.\n\nPermission: `workspace`.","operationId":"testLogStream","parameters":[{"description":"The log stream's id.","example":"d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"ok":true,"status":202,"message":"Datadog answered HTTP 202."},"schema":{"additionalProperties":false,"properties":{"message":{"description":"One sentence.","type":"string"},"ok":{"type":"boolean"},"status":{"description":"The HTTP status the provider answered. Absent for syslog and when there was no answer.","type":"integer"}},"required":["ok","message"],"type":"object"}}},"description":"What happened."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`forbidden`: The key is not an admin key."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such log stream in this workspace."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 6 test lines a minute for this log stream."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: Log forwarding is not available."}},"summary":"Send a test line","tags":["Log streams"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64/test\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64/test\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64/test\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/log-streams/d4b7c2a9-6e1f-4a83-9c05-3b8e7f1a2d64/test\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby log-stream test"}],"x-kilby-permission":"workspace"}},"/notifications":{"get":{"description":"Which events Kilby emails to the members of the workspace. Emails go to every member. To receive events in your own systems, use webhooks instead.\n\nPermission: `view`.","operationId":"getNotifications","responses":{"200":{"content":{"application/json":{"example":{"email":{"deploy.failed":true,"cron.run.failed":true,"service.suspended":true,"database.failed":true,"shell.opened":true}},"schema":{"additionalProperties":false,"properties":{"email":{"additionalProperties":{"type":"boolean"},"type":"object"}},"required":["email"],"type":"object"}}},"description":"Per event type: true when it is emailed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get email notifications","tags":["Workspaces"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/notifications\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/notifications\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/notifications\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/notifications\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"patch":{"description":"Turns emails on or off per event type. Types you leave out keep their setting.\n\nNeeds: An admin key, created by an admin or the owner of the workspace.\n\nPermission: `workspace`.","operationId":"updateNotifications","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Stop emailing failed cron runs","value":{"email":{"cron.run.failed":false}}}},"schema":{"additionalProperties":false,"properties":{"email":{"additionalProperties":{"type":"boolean"},"description":"Event type to on or off. Only the types listed by GET /notifications can be emailed.","type":"object"}},"required":["email"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"email":{"deploy.failed":true,"cron.run.failed":false,"service.suspended":true,"database.failed":true,"shell.opened":true}},"schema":{"additionalProperties":false,"properties":{"email":{"additionalProperties":{"type":"boolean"},"type":"object"}},"required":["email"],"type":"object"}}},"description":"The settings now."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A type cannot be emailed."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Change email notifications","tags":["Workspaces"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/notifications\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": {\"cron.run.failed\": false}}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/notifications\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"email\": {\"cron.run.failed\": false}}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/notifications\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"email\": {\"cron.run.failed\": False}},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"email\": {\"cron.run.failed\": false}}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/notifications\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/openapi.json":{"get":{"description":"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.\n\nUse 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`.","operationId":"getOpenAPI","responses":{"200":{"content":{"application/json":{"example":{"openapi":"3.1.0","info":{"title":"Kilby API","version":"1"},"paths":{}},"schema":{"type":"object"}}},"description":"The OpenAPI document."},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"summary":"Download the OpenAPI description","tags":["API description"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/openapi.json\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/openapi.json\");\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/openapi.json\",\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/openapi.json\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"none"}},"/previews/{id}":{"delete":{"description":"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.\n\nPermission: `deploy`.","operationId":"deletePreview","parameters":[{"description":"The preview's id.","example":"5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350","pull_request":42,"title":"Add the search page","branch":"search-page","commit":"8a2e7d9a74a99a24383b37a774d17ddd931058c0","state":"active","reason":"","service_id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","url":"https://my-api-pr-42-x7k2.apps.kilby.neuramorphic.ai","status":"live","expires_at":"2026-11-13T14:05:00Z","created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z","ended_at":null},"schema":{"$ref":"#/components/schemas/Preview"}}},"description":"The preview, now `removed`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The workspace has no preview with that id."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The preview was already removed, closed or expired."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Remove a preview","tags":["Pull request previews"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/previews/5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/previews/5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/previews/5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/previews/5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/pricing":{"get":{"description":"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.","operationId":"getPricing","responses":{"200":{"content":{"application/json":{"example":{"currency":"usd","billing":{"live":false,"period":"calendar month, UTC","proration":"by the second","rounding":"half up, once per invoice line","minimum_charge_cents":100,"bandwidth_metered":true,"bandwidth_billed_from":null},"tiers":[{"id":"pro","name":"Pro","summary":"For a team shipping a product. Unlimited members.","fee_cents":2500,"contact_us":false,"support":"Email","limits":{"services":25,"cron_jobs":25,"databases":10,"cpu":16,"memory_gb":32,"storage_gb":500,"members":0,"custom_domains":20,"included_build_minutes":500,"included_bandwidth_gb":25}}],"instances":[{"id":"starter","name":"Starter","cpu":0.5,"memory_gb":0.5,"service_cents_per_month":900,"postgres_cents_per_month":1400}],"prices":{"disk_cents_per_gb_month":25,"postgres_storage_cents_per_gb_month":30,"build_cents_per_minute":1,"cron_minimum_cents_per_month":100,"bandwidth_cents_per_gb":15}},"schema":{"additionalProperties":false,"properties":{"billing":{"additionalProperties":false,"description":"How the numbers are worked out.","properties":{"bandwidth_billed_from":{"description":"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.","type":["string","null"]},"bandwidth_metered":{"description":"Whether outbound bandwidth is measured on this Kilby. While false it is not charged.","type":"boolean"},"live":{"description":"true only when the platform bills real money. While false, nothing is charged.","type":"boolean"},"minimum_charge_cents":{"description":"An invoice below this is not charged.","type":"integer"},"period":{"type":"string"},"proration":{"type":"string"},"rounding":{"type":"string"}},"required":["live","period","proration","rounding","minimum_charge_cents","bandwidth_metered","bandwidth_billed_from"],"type":"object"},"currency":{"description":"Always `usd`.","type":"string"},"instances":{"description":"The instance types.","items":{"type":"object"},"type":"array"},"prices":{"description":"The other list prices, in US cents.","type":"object"},"tiers":{"description":"Hobby, Pro, Scale and Enterprise, each shaped like `plan` in Read the plan and the limits.","items":{"type":"object"},"type":"array"}},"required":["currency","billing","tiers","instances","prices"],"type":"object"}}},"description":"The price list."},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"summary":"Read the price list","tags":["Billing and pricing"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/pricing\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/pricing\");\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/pricing\",\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/pricing\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"none"}},"/projects":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"listProjects","responses":{"200":{"content":{"application/json":{"example":{"projects":[{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app","default":false,"environments":[{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app"},"default":false,"position":0,"counts":{"services":2,"cron_jobs":1,"databases":1,"key_values":0},"created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-12T22:40:11Z"},{"id":"d41f8b60-2e7a-4c93-a5b8-0f6e3d9c2a71","name":"Staging","project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app"},"default":false,"position":1,"counts":{"services":1,"cron_jobs":0,"databases":0,"key_values":0},"created_at":"2026-11-13T09:12:30Z","updated_at":"2026-11-13T09:12:30Z"}],"counts":{"services":3,"cron_jobs":1,"databases":1,"key_values":0},"created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-12T22:40:11Z"}]},"schema":{"additionalProperties":false,"properties":{"projects":{"items":{"$ref":"#/components/schemas/Project"},"type":"array"}},"required":["projects"],"type":"object"}}},"description":"The projects, the Default one first."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List projects","tags":["Projects"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/projects\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/projects\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/projects\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/projects\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby projects list"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nPermission: `deploy`.","operationId":"createProject","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"A project","value":{"name":"Checkout app"}}},"schema":{"additionalProperties":false,"properties":{"name":{"description":"Unique in the workspace, without regard to capitals. Allowed: 1 to 40 characters, no slash.","type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app","default":false,"environments":[{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app"},"default":false,"position":0,"counts":{"services":0,"cron_jobs":0,"databases":0,"key_values":0},"created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-12T22:40:11Z"}],"counts":{"services":0,"cron_jobs":0,"databases":0,"key_values":0},"created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-12T22:40:11Z"},"schema":{"$ref":"#/components/schemas/Project"}}},"description":"The project, with its Production environment."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The workspace already has a project with that name."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The name is not valid, or the workspace has reached its limit of projects."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Create a project","tags":["Projects"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/projects\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Checkout app\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/projects\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"name\": \"Checkout app\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/projects\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"name\": \"Checkout app\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"name\": \"Checkout app\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/projects\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby projects create"}],"x-kilby-permission":"deploy"}},"/projects/{id}":{"delete":{"description":"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.\n\nPermission: `workspace`.","operationId":"deleteProject","parameters":[{"description":"The project's id.","example":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"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.","example":"Default/Production","in":"query","name":"move_to","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"deleted":"Checkout app","moved":4,"moved_to":"Default / Production"},"schema":{"additionalProperties":false,"properties":{"deleted":{"description":"The project's name.","type":"string"},"moved":{"description":"How many resources were moved.","type":"integer"},"moved_to":{"description":"Where they went, as `project / environment`.","type":"string"}},"required":["deleted","moved"],"type":"object"}}},"description":"What was deleted and how many resources moved."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such project in this workspace."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: It still holds resources and `move_to` was not sent, or it is the Default project."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: `move_to` names no environment, or one inside the project."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete a project","tags":["Projects"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12?move_to=Default%2FProduction\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12?move_to=Default%2FProduction\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12?move_to=Default%2FProduction\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12?move_to=Default%2FProduction\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby projects delete"}],"x-kilby-permission":"workspace"},"get":{"description":"One project with its environments and what each holds, by name and id.\n\nPermission: `view`.","operationId":"getProject","parameters":[{"description":"The project's id.","example":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app","default":false,"environments":[{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app"},"default":false,"position":0,"counts":{"services":2,"cron_jobs":1,"databases":1,"key_values":0},"resources":[{"type":"web","id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api"},{"type":"database","id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","name":"main"}],"created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-12T22:40:11Z"}],"counts":{"services":2,"cron_jobs":1,"databases":1,"key_values":0},"created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-12T22:40:11Z"},"schema":{"$ref":"#/components/schemas/Project"}}},"description":"The project."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such project in this workspace."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a project","tags":["Projects"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby projects get"}],"x-kilby-permission":"view"},"patch":{"description":"Renames the project, the Default one included. Nothing that runs is touched.\n\nPermission: `deploy`.","operationId":"updateProject","parameters":[{"description":"The project's id.","example":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Rename","value":{"name":"Checkout"}}},"schema":{"additionalProperties":false,"properties":{"name":{"description":"The new name. Allowed: 1 to 40 characters, no slash.","type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app","default":false,"environments":[{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app"},"default":false,"position":0,"counts":{"services":2,"cron_jobs":1,"databases":1,"key_values":0},"resources":[{"type":"web","id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api"},{"type":"database","id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","name":"main"}],"created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-12T22:40:11Z"}],"counts":{"services":2,"cron_jobs":1,"databases":1,"key_values":0},"created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-12T22:40:11Z"},"schema":{"$ref":"#/components/schemas/Project"}}},"description":"The project."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such project in this workspace."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: Another project has that name."},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Rename a project","tags":["Projects"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Checkout\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"name\": \"Checkout\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"name\": \"Checkout\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"name\": \"Checkout\"}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby projects rename"}],"x-kilby-permission":"deploy"}},"/projects/{id}/environments":{"get":{"description":"The project's environments in order, with how many resources each holds.\n\nPermission: `view`.","operationId":"listEnvironments","parameters":[{"description":"The project's id.","example":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"environments":[{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app"},"default":false,"position":0,"counts":{"services":2,"cron_jobs":1,"databases":1,"key_values":0},"created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-12T22:40:11Z"}]},"schema":{"additionalProperties":false,"properties":{"environments":{"items":{"$ref":"#/components/schemas/ProjectEnvironment"},"type":"array"}},"required":["environments"],"type":"object"}}},"description":"The environments."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such project in this workspace."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List the environments of a project","tags":["Projects"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby projects environments"}],"x-kilby-permission":"view"},"post":{"description":"Adds an environment at the end of the project, for example Staging or Preview. A project can have up to 10.\n\nPermission: `deploy`.","operationId":"createEnvironment","parameters":[{"description":"The project's id.","example":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Staging","value":{"name":"Staging"}}},"schema":{"additionalProperties":false,"properties":{"name":{"description":"Unique in the project, without regard to capitals. Allowed: 1 to 40 characters, no slash.","type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"id":"d41f8b60-2e7a-4c93-a5b8-0f6e3d9c2a71","name":"Staging","project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app"},"default":false,"position":1,"counts":{"services":0,"cron_jobs":0,"databases":0,"key_values":0},"created_at":"2026-11-13T09:12:30Z","updated_at":"2026-11-13T09:12:30Z"},"schema":{"$ref":"#/components/schemas/ProjectEnvironment"}}},"description":"The environment."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such project in this workspace."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The project already has an environment with that name."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The name is not valid, or the project has reached its limit of environments."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Create an environment","tags":["Projects"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Staging\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"name\": \"Staging\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"name\": \"Staging\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"name\": \"Staging\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby projects add-environment"}],"x-kilby-permission":"deploy"}},"/projects/{id}/environments/{env}":{"delete":{"description":"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.\n\nPermission: `workspace`.","operationId":"deleteEnvironment","parameters":[{"description":"The project's id.","example":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"The environment's id.","example":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","in":"path","name":"env","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"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.","example":"Default/Production","in":"query","name":"move_to","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"deleted":"Checkout app / Staging","moved":1,"moved_to":"Checkout app / Production"},"schema":{"additionalProperties":false,"properties":{"deleted":{"description":"`project / environment`.","type":"string"},"moved":{"description":"How many resources were moved.","type":"integer"},"moved_to":{"description":"Where they went.","type":"string"}},"required":["deleted","moved"],"type":"object"}}},"description":"What was deleted and how many resources moved."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such project or environment in this workspace."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: It still holds resources and `move_to` was not sent, it is the default environment, or it is the last one of its project."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: `move_to` names no environment, or the one being deleted."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete an environment","tags":["Projects"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053?move_to=Default%2FProduction\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053?move_to=Default%2FProduction\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053?move_to=Default%2FProduction\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053?move_to=Default%2FProduction\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"},"get":{"description":"One environment with the resources it holds.\n\nPermission: `view`.","operationId":"getEnvironment","parameters":[{"description":"The project's id.","example":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"The environment's id.","example":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","in":"path","name":"env","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app"},"default":false,"position":0,"counts":{"services":2,"cron_jobs":0,"databases":1,"key_values":0},"resources":[{"type":"web","id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api"},{"type":"worker","id":"9b0e4c71-3d2a-4f58-8a61-c7d1e2f30b94","name":"queue-worker"},{"type":"database","id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","name":"main"}],"created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-12T22:40:11Z"},"schema":{"$ref":"#/components/schemas/ProjectEnvironment"}}},"description":"The environment."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such project or environment in this workspace."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get an environment","tags":["Projects"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"patch":{"description":"Renames the environment, the default one included. Nothing that runs is touched.\n\nPermission: `deploy`.","operationId":"updateEnvironment","parameters":[{"description":"The project's id.","example":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"The environment's id.","example":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","in":"path","name":"env","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Rename","value":{"name":"Prod"}}},"schema":{"additionalProperties":false,"properties":{"name":{"description":"The new name. Allowed: 1 to 40 characters, no slash.","type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Checkout app"},"default":false,"position":0,"counts":{"services":2,"cron_jobs":0,"databases":1,"key_values":0},"resources":[{"type":"web","id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api"},{"type":"worker","id":"9b0e4c71-3d2a-4f58-8a61-c7d1e2f30b94","name":"queue-worker"},{"type":"database","id":"0c4a3c1e-58a1-4c0a-9d6f-2f6a1c0f5b7e","name":"main"}],"created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-12T22:40:11Z"},"schema":{"$ref":"#/components/schemas/ProjectEnvironment"}}},"description":"The environment."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no such project or environment in this workspace."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: Another environment of the project has that name."},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Rename an environment","tags":["Projects"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Prod\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"name\": \"Prod\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"name\": \"Prod\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"name\": \"Prod\"}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/projects/2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12/environments/9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/registry-credentials":{"get":{"description":"The credentials Kilby uses to pull private images, and the services that use each. Passwords and tokens are never returned.\n\nPermission: `view`.","operationId":"listRegistryCredentials","responses":{"200":{"content":{"application/json":{"example":{"registry_credentials":[{"id":"9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12","name":"github-acme","registry":"ghcr.io","username":"octocat","used_by":[{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api"}],"created_at":"2026-11-13T10:02:41Z","updated_at":"2026-11-13T10:02:41Z"}]},"schema":{"additionalProperties":false,"properties":{"registry_credentials":{"items":{"$ref":"#/components/schemas/RegistryCredential"},"type":"array"}},"required":["registry_credentials"],"type":"object"}}},"description":"The credentials."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List registry credentials","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/registry-credentials\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/registry-credentials\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/registry-credentials\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/registry-credentials\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nPermission: `secrets`.","operationId":"createRegistryCredential","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"GitHub Container Registry","value":{"name":"github-acme","registry":"ghcr.io","username":"octocat","password":"ghp_xxxxxxxxxxxxxxxx"}}},"schema":{"additionalProperties":false,"properties":{"name":{"description":"A name for you to recognise them by. Unique in the workspace. Allowed: up to 60 characters.","type":"string"},"password":{"description":"The password or access token. It needs permission to read packages only. Allowed: up to 8 KB.","type":"string"},"registry":{"description":"The registry host. Allowed: a host such as ghcr.io, docker.io or registry.gitlab.com.","type":"string"},"username":{"description":"The registry user name. Allowed: up to 255 characters, no colon.","type":"string"}},"required":["name","registry","username","password"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"id":"9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12","name":"github-acme","registry":"ghcr.io","username":"octocat","used_by":[],"created_at":"2026-11-13T10:02:41Z","updated_at":"2026-11-13T10:02:41Z"},"schema":{"$ref":"#/components/schemas/RegistryCredential"}}},"description":"The credentials, without the password."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The workspace already has credentials with that name."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A field is not valid, or the registry is not allowed."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Add registry credentials","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/registry-credentials\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"github-acme\",\n  \"registry\": \"ghcr.io\",\n  \"username\": \"octocat\",\n  \"password\": \"ghp_xxxxxxxxxxxxxxxx\"\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/registry-credentials\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"name\": \"github-acme\",\n    \"registry\": \"ghcr.io\",\n    \"username\": \"octocat\",\n    \"password\": \"ghp_xxxxxxxxxxxxxxxx\"\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/registry-credentials\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"name\": \"github-acme\",\n        \"registry\": \"ghcr.io\",\n        \"username\": \"octocat\",\n        \"password\": \"ghp_xxxxxxxxxxxxxxxx\"\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"name\": \"github-acme\",\n  \"registry\": \"ghcr.io\",\n  \"username\": \"octocat\",\n  \"password\": \"ghp_xxxxxxxxxxxxxxxx\"\n}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/registry-credentials\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"secrets"}},"/registry-credentials/{id}":{"delete":{"description":"Deletes credentials that no service uses.\n\nPermission: `secrets`.","operationId":"deleteRegistryCredential","parameters":[{"description":"The registry credentials' id.","example":"9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Deleted. There is no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: A service still uses them. The message names the services."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete registry credentials","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status); // 204: nothing to read\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code)  # 204: nothing to read\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"secrets"},"patch":{"description":"Replaces the password or token, and the user name if you send one. Use it when a token expires: services pull with the new one from their next pull.\n\nPermission: `secrets`.","operationId":"updateRegistryCredential","parameters":[{"description":"The registry credentials' id.","example":"9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Replace the token","value":{"password":"ghp_yyyyyyyyyyyyyyyy"}}},"schema":{"additionalProperties":false,"properties":{"password":{"description":"The new password or token. Allowed: up to 8 KB.","type":"string"},"username":{"description":"A new user name. Leave it out to keep the current one.","type":"string"}},"required":["password"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"id":"9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12","name":"github-acme","registry":"ghcr.io","username":"octocat","used_by":[{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api"}],"created_at":"2026-11-13T10:02:41Z","updated_at":"2026-11-13T10:02:41Z"},"schema":{"$ref":"#/components/schemas/RegistryCredential"}}},"description":"The credentials."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The password is missing or not valid."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Replace a token","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"password\": \"ghp_yyyyyyyyyyyyyyyy\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"password\": \"ghp_yyyyyyyyyyyyyyyy\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"password\": \"ghp_yyyyyyyyyyyyyyyy\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"password\": \"ghp_yyyyyyyyyyyyyyyy\"}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/registry-credentials/9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"secrets"}},"/services":{"get":{"description":"Every web service, private service, background worker and cron job of the workspace, newest first. Databases are listed by List databases.\n\nPermission: `view`.","operationId":"listServices","responses":{"200":{"content":{"application/json":{"example":{"services":[{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api","type":"web","image":"ghcr.io/acme/api:1.4","port":8080,"plan":"starter","status":"live","status_message":"","suspended":false,"url":"https://my-api-x7k2.apps.kilby.neuramorphic.ai","internal_address":"my-api:8080","created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-13T14:05:00Z","registry_credential_id":null,"health_check_path":"/healthz","instances":2,"autoscaling":{"min":2,"max":4,"target_cpu_percent":70},"disk":null,"instances_running":2,"instances_desired":2,"pre_deploy_command":"","pre_deploy_timeout_seconds":600,"source":null,"environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"auto_concurrency":true,"render_compat":false,"stop_first":false,"read_only_root":false,"maintenance":false,"maintenance_message":"","primary_domain":"my-api-x7k2.apps.kilby.neuramorphic.ai","primary_domain_choice":null}]},"schema":{"additionalProperties":false,"properties":{"services":{"items":{"$ref":"#/components/schemas/Service"},"type":"array"}},"required":["services"],"type":"object"}}},"description":"The services."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List services","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby services list"}],"x-kilby-permission":"view"},"post":{"description":"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`.\n\nRun 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`.\n\nThe 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.\n\nPermission: `deploy`.","operationId":"createService","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Web service from an image","value":{"name":"my-api","type":"web","image":"ghcr.io/acme/api:1.4","port":8080,"plan":"starter","env":{"LOG_LEVEL":"info"}}},"example2":{"summary":"Web service from a GitHub repository","value":{"name":"my-api","type":"web","plan":"starter","source":{"kind":"git","installation_id":4242,"repo":"acme/express-api","branch":"main","root_dir":"","auto_deploy":true}}},"example3":{"summary":"Web service from a public repository","value":{"name":"my-api","type":"web","plan":"starter","source":{"kind":"public_git","url":"https://github.com/acme/express-api","ref":"main"}}},"example4":{"summary":"Cron job","value":{"name":"nightly-report","type":"cron","image":"ghcr.io/acme/jobs:1.4","command":"python report.py","schedule":"0 3 * * *","plan":"starter"}},"example5":{"summary":"Web service that migrates its database before each deploy","value":{"name":"my-api","type":"web","image":"ghcr.io/acme/api:1.4","port":8080,"pre_deploy_command":"python manage.py migrate","pre_deploy_timeout_seconds":600}},"example6":{"summary":"Private service with a disk","value":{"name":"vector-store","type":"private","image":"qdrant/qdrant:v1.15.0","port":6333,"health_check_path":"/readyz","disk":{"mount_path":"/qdrant/storage","size_gb":10}}}},"schema":{"additionalProperties":false,"properties":{"autoscaling":{"description":"Follow CPU use between a minimum and a maximum. Not for cron jobs.","oneOf":[{"$ref":"#/components/schemas/Autoscaling"},{"type":"null"}]},"command":{"description":"Replaces the image's own start command. Allowed: up to 2,000 characters.","type":"string"},"disk":{"description":"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.","oneOf":[{"$ref":"#/components/schemas/Disk"},{"type":"null"}]},"env":{"additionalProperties":{"type":"string"},"description":"Environment variables, name to value. Values are stored encrypted. Allowed: up to 100 variables, values up to 8 KB.","type":"object"},"environment":{"description":"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.","type":"string"},"health_check_path":{"description":"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. Allowed: starts with /, up to 200 characters.","type":"string"},"image":{"description":"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. Allowed: a registry reference, tag or digest.","type":"string"},"instances":{"default":1,"description":"A fixed number of instances. Send either instances or autoscaling, not both. Allowed: 1 to 10.","type":"integer"},"name":{"description":"Unique in the workspace. It becomes the service's internal host name, and part of its public address. Allowed: 3 to 40 characters: lowercase letters, digits and hyphens, starting with a letter. Not starting with db-.","type":"string"},"plan":{"default":"starter","description":"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.","enum":["starter","standard","pro"],"type":"string"},"port":{"description":"The port the service listens on. Required for web and private services. Allowed: 1 to 65535.","type":"integer"},"pre_deploy_command":{"description":"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. Allowed: up to 2,000 characters.","type":["string","null"]},"pre_deploy_timeout_seconds":{"default":600,"description":"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. Allowed: 10 to 1800.","type":["integer","null"]},"registry_credential_id":{"description":"Credentials to pull a private image with, from POST /registry-credentials. null, or an empty string, means a public image.","format":"uuid","type":["string","null"]},"schedule":{"description":"Five cron fields, in UTC. Required for a cron job, not allowed otherwise.","type":"string"},"source":{"$ref":"#/components/schemas/SourceInput","description":"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."},"type":{"default":"web","description":"What kind of service to create.","enum":["web","private","worker","cron"],"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api","type":"web","image":"ghcr.io/acme/api:1.4","port":8080,"plan":"starter","status":"deploying","status_message":"","suspended":false,"url":"https://my-api-x7k2.apps.kilby.neuramorphic.ai","internal_address":"my-api:8080","created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-13T14:05:00Z","registry_credential_id":null,"health_check_path":"","instances":1,"autoscaling":null,"disk":null,"instances_running":0,"instances_desired":1,"pre_deploy_command":"","pre_deploy_timeout_seconds":600,"source":null,"environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"auto_concurrency":true,"render_compat":false,"stop_first":false,"read_only_root":false,"maintenance":false,"maintenance_message":"","primary_domain":"my-api-x7k2.apps.kilby.neuramorphic.ai","primary_domain_choice":null},"schema":{"$ref":"#/components/schemas/Service"}}},"description":"The new service. For a service built from Git, `source.latest_build` holds the first build."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A field is not valid, a limit of the workspace would be exceeded, or the name is taken."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Create a service","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"my-api\",\n  \"type\": \"web\",\n  \"image\": \"ghcr.io/acme/api:1.4\",\n  \"port\": 8080,\n  \"plan\": \"starter\",\n  \"env\": {\"LOG_LEVEL\": \"info\"}\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"name\": \"my-api\",\n    \"type\": \"web\",\n    \"image\": \"ghcr.io/acme/api:1.4\",\n    \"port\": 8080,\n    \"plan\": \"starter\",\n    \"env\": {\"LOG_LEVEL\": \"info\"}\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"name\": \"my-api\",\n        \"type\": \"web\",\n        \"image\": \"ghcr.io/acme/api:1.4\",\n        \"port\": 8080,\n        \"plan\": \"starter\",\n        \"env\": {\"LOG_LEVEL\": \"info\"}\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"name\": \"my-api\",\n  \"type\": \"web\",\n  \"image\": \"ghcr.io/acme/api:1.4\",\n  \"port\": 8080,\n  \"plan\": \"starter\",\n  \"env\": {\"LOG_LEVEL\": \"info\"}\n}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}":{"delete":{"description":"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.\n\nPermission: `deploy`.","operationId":"deleteService","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","status":"deleting"},"schema":{"additionalProperties":false,"properties":{"id":{"format":"uuid","type":"string"},"status":{"description":"Always deleting.","type":"string"}},"required":["id","status"],"type":"object"}}},"description":"The service is being deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is already being deleted."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete a service","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby services delete my-api"}],"x-kilby-permission":"deploy"},"get":{"description":"One service with its status, address and how it runs.\n\nPermission: `view`.","operationId":"getService","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api","type":"web","image":"ghcr.io/acme/api:1.4","port":8080,"plan":"starter","status":"live","status_message":"","suspended":false,"url":"https://my-api-x7k2.apps.kilby.neuramorphic.ai","internal_address":"my-api:8080","created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-13T14:05:00Z","registry_credential_id":null,"health_check_path":"/healthz","instances":2,"autoscaling":{"min":2,"max":4,"target_cpu_percent":70},"disk":null,"instances_running":2,"instances_desired":2,"pre_deploy_command":"","pre_deploy_timeout_seconds":600,"source":null,"environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"auto_concurrency":true,"render_compat":false,"stop_first":false,"read_only_root":false,"maintenance":false,"maintenance_message":"","primary_domain":"my-api-x7k2.apps.kilby.neuramorphic.ai","primary_domain_choice":null},"schema":{"$ref":"#/components/schemas/Service"}}},"description":"The service."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a service","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby services get my-api"}],"x-kilby-permission":"view"},"patch":{"description":"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.\n\n`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.\n\nThe `type` of a service cannot change. Fields that do not apply to it, such as `port` on a worker, are refused.\n\nA 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.\n\nPermission: `deploy`.","operationId":"updateService","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Roll out a new image","value":{"image":"ghcr.io/acme/api:1.5"}},"example2":{"summary":"Pull with registry credentials","value":{"image":"ghcr.io/acme/api:1.5","registry_credential_id":"9e2f4b8a-1d3c-4f67-a0b5-7c6d8e9f0a12"}},"example3":{"summary":"Autoscale and add a health check","value":{"health_check_path":"/healthz","autoscaling":{"min":2,"max":4,"target_cpu_percent":70}}},"example4":{"summary":"Run migrations before each deploy","value":{"pre_deploy_command":"alembic upgrade head"}},"example5":{"summary":"Remove the pre-deploy command","value":{"pre_deploy_command":null}},"example6":{"summary":"Replace the environment","value":{"env":{"LOG_LEVEL":"info","DATABASE_URL":"postgresql://app:secret@db-main-rw:5432/app"}}},"example7":{"summary":"Change the folder of a Git service and rebuild","value":{"source":{"root_dir":"backend","port":8000},"rebuild":true}},"example8":{"summary":"Move it to another environment","value":{"environment":"Checkout app/Staging"}}},"schema":{"additionalProperties":false,"properties":{"auto_concurrency":{"description":"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.","type":"boolean"},"autoscaling":{"description":"Follow CPU use between a minimum and a maximum. Not for cron jobs.","oneOf":[{"$ref":"#/components/schemas/Autoscaling"},{"type":"null"}]},"command":{"description":"Replaces the start command. An empty string goes back to the image's own.","type":"string"},"disk":{"description":"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.","oneOf":[{"$ref":"#/components/schemas/Disk"},{"type":"null"}]},"env":{"additionalProperties":{"type":"string"},"description":"All environment variables. They replace the current ones as a whole.","type":"object"},"environment":{"description":"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.","type":"string"},"health_check_path":{"description":"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. Allowed: starts with /, up to 200 characters.","type":"string"},"image":{"description":"A new image or tag to deploy.","type":"string"},"instances":{"default":1,"description":"A fixed number of instances. Send either instances or autoscaling, not both. Allowed: 1 to 10.","type":"integer"},"plan":{"description":"A different instance type.","enum":["starter","standard","pro"],"type":"string"},"port":{"description":"A new port. Allowed: 1 to 65535.","type":"integer"},"pre_deploy_command":{"description":"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. Allowed: up to 2,000 characters.","type":["string","null"]},"pre_deploy_timeout_seconds":{"default":600,"description":"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. Allowed: 10 to 1800.","type":["integer","null"]},"read_only_root":{"description":"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.","type":"boolean"},"rebuild":{"description":"Build the latest commit once the changes are saved. Can be sent alone. Only for services built from Git.","type":"boolean"},"registry_credential_id":{"description":"Credentials to pull a private image with, from POST /registry-credentials. null, or an empty string, means a public image.","format":"uuid","type":["string","null"]},"render_compat":{"description":"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.","type":"boolean"},"schedule":{"description":"A new schedule, for a cron job.","type":"string"},"source":{"$ref":"#/components/schemas/SourceEdit","description":"For a service built from Git: change where and how it builds. Send it on its own, not together with the runtime settings above."},"stop_first":{"description":"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.","type":"boolean"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api","type":"web","image":"ghcr.io/acme/api:1.4","port":8080,"plan":"starter","status":"deploying","status_message":"","suspended":false,"url":"https://my-api-x7k2.apps.kilby.neuramorphic.ai","internal_address":"my-api:8080","created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-13T14:05:00Z","registry_credential_id":null,"health_check_path":"/healthz","instances":2,"autoscaling":{"min":2,"max":4,"target_cpu_percent":70},"disk":null,"instances_running":1,"instances_desired":2,"pre_deploy_command":"","pre_deploy_timeout_seconds":600,"source":null,"environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"auto_concurrency":true,"render_compat":false,"stop_first":false,"read_only_root":false,"maintenance":false,"maintenance_message":"","primary_domain":"my-api-x7k2.apps.kilby.neuramorphic.ai","primary_domain_choice":null},"schema":{"$ref":"#/components/schemas/Service"}}},"description":"The service after the change."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is built from Git and its first build has not finished yet, or `source.version` is out of date."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A field is not valid, or the change would exceed a limit of the workspace."},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`github_unavailable`: Kilby could not read the repository from GitHub to check the new source settings."}},"summary":"Change a service","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"image\": \"ghcr.io/acme/api:1.5\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"image\": \"ghcr.io/acme/api:1.5\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"image\": \"ghcr.io/acme/api:1.5\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"image\": \"ghcr.io/acme/api:1.5\"}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/build-env":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"getBuildEnv","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"names":["NEXT_PUBLIC_API_URL","NPM_TOKEN"]},"schema":{"additionalProperties":false,"properties":{"names":{"items":{"type":"string"},"type":"array"}},"required":["names"],"type":"object"}}},"description":"The names, sorted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The service is not built from Git."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List build variables","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"patch":{"description":"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.\n\nPermission: `secrets`.","operationId":"patchBuildEnv","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Set a registry token","value":{"set":{"NPM_TOKEN":"npm_xxxxxxxx"}}}},"schema":{"additionalProperties":false,"properties":{"set":{"additionalProperties":{"type":"string"},"description":"Name to value. Allowed: up to 20 variables in all, values up to 4,096 characters.","type":"object"},"unset":{"description":"Names to remove.","items":{"type":"string"},"type":"array"}},"type":"object"}}},"description":"Both fields are optional; `{}` changes nothing.","required":false},"responses":{"200":{"content":{"application/json":{"example":{"names":["NPM_TOKEN"],"added":["NPM_TOKEN"],"changed":[],"removed":[],"restarted":false},"schema":{"additionalProperties":false,"properties":{"added":{"items":{"type":"string"},"type":"array"},"changed":{"items":{"type":"string"},"type":"array"},"names":{"items":{"type":"string"},"type":"array"},"removed":{"items":{"type":"string"},"type":"array"},"restarted":{"type":"boolean"}},"required":["names","added","changed","removed","restarted"],"type":"object"}}},"description":"The names now set, and what changed. `restarted` is always false."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The service is not built from Git, or a name or value is not valid."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Change build variables","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"set\": {\"NPM_TOKEN\": \"npm_xxxxxxxx\"}}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"set\": {\"NPM_TOKEN\": \"npm_xxxxxxxx\"}}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"set\": {\"NPM_TOKEN\": \"npm_xxxxxxxx\"}},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"set\": {\"NPM_TOKEN\": \"npm_xxxxxxxx\"}}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby env set --build"}],"x-kilby-permission":"secrets"},"put":{"description":"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.\n\nPermission: `secrets`.","operationId":"setBuildEnv","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Set two variables","value":{"env":{"NEXT_PUBLIC_API_URL":"https://api.example.com","NPM_TOKEN":"npm_xxxxxxxx"}}}},"schema":{"additionalProperties":false,"properties":{"env":{"additionalProperties":{"type":"string"},"description":"Name to value. Allowed: up to 20 variables, values up to 4,096 characters, names of letters, digits and underscores.","type":"object"}},"required":["env"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"names":["NEXT_PUBLIC_API_URL","NPM_TOKEN"]},"schema":{"additionalProperties":false,"properties":{"names":{"items":{"type":"string"},"type":"array"}},"required":["names"],"type":"object"}}},"description":"The names that are set now."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The service is not built from Git, or a name or value is not valid."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Replace build variables","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PUT \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"env\": {\n    \"NEXT_PUBLIC_API_URL\": \"https://api.example.com\",\n    \"NPM_TOKEN\": \"npm_xxxxxxxx\"\n  }\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\", {\n  method: \"PUT\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"env\": {\n      \"NEXT_PUBLIC_API_URL\": \"https://api.example.com\",\n      \"NPM_TOKEN\": \"npm_xxxxxxxx\"\n    }\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.put(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"env\": {\n            \"NEXT_PUBLIC_API_URL\": \"https://api.example.com\",\n            \"NPM_TOKEN\": \"npm_xxxxxxxx\"\n        }\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"env\": {\n    \"NEXT_PUBLIC_API_URL\": \"https://api.example.com\",\n    \"NPM_TOKEN\": \"npm_xxxxxxxx\"\n  }\n}`)\n\treq, err := http.NewRequest(\"PUT\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/build-env\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"secrets"}},"/services/{id}/builds":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"listBuilds","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"How many builds to return. Allowed: 1 to 100.","example":20,"in":"query","name":"limit","required":false,"schema":{"default":20,"type":"integer"}},{"description":"Only builds with a number lower than this. Use the next_before of the previous page.","in":"query","name":"before","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"builds":[{"id":"5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24","number":4,"trigger":"push","status":"succeeded","stage":"live","commit":{"sha":"9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0","message":"Add the /v1/chat route","author":"Ada Lovelace","branch":"main"},"stages":[{"name":"clone","status":"succeeded","started_at":"2026-11-13T14:00:02Z","finished_at":"2026-11-13T14:00:05Z"},{"name":"detect","status":"succeeded","started_at":"2026-11-13T14:00:05Z","finished_at":"2026-11-13T14:00:06Z"},{"name":"build","status":"succeeded","started_at":"2026-11-13T14:00:06Z","finished_at":"2026-11-13T14:02:31Z"},{"name":"push","status":"succeeded","started_at":"2026-11-13T14:02:31Z","finished_at":"2026-11-13T14:02:48Z","note":"84 MB"},{"name":"release","status":"succeeded","started_at":"2026-11-13T14:02:48Z","finished_at":"2026-11-13T14:02:49Z"},{"name":"health","status":"succeeded","started_at":"2026-11-13T14:02:49Z","finished_at":"2026-11-13T14:03:11Z"},{"name":"live","status":"succeeded","started_at":"2026-11-13T14:03:11Z","finished_at":"2026-11-13T14:03:11Z"}],"diagnosis":null,"image_digest":"sha256:4b1f9c0e7d2a8356bc41e9d0f7a6c3258e1d4b97a0c6f3e5d28b71a94c60e3fd","created_by":"Ada Lovelace","created_at":"2026-11-13T14:00:01Z","started_at":"2026-11-13T14:00:02Z","finished_at":"2026-11-13T14:03:11Z"}],"next_before":null},"schema":{"additionalProperties":false,"properties":{"builds":{"items":{"$ref":"#/components/schemas/Build"},"type":"array"},"next_before":{"description":"The value to send as before for the next page. null on the last page.","type":["integer","null"]}},"required":["builds","next_before"],"type":"object"}}},"description":"A page of builds."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The service does not run an image built from Git."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List builds","tags":["Deploys and builds"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds?limit=20\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds?limit=20\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds?limit=20\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds?limit=20\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby builds list my-api"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nPermission: `deploy`.","operationId":"startBuild","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Build a commit","value":{"sha":"9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0"}}},"schema":{"additionalProperties":false,"properties":{"sha":{"description":"A commit to build, as a full or abbreviated commit id. Leave it out for the latest commit of the branch.","type":"string"}},"type":"object"}}},"description":"The body is optional.","required":false},"responses":{"202":{"content":{"application/json":{"example":{"id":"5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24","number":4,"trigger":"manual","status":"queued","stage":"clone","commit":{"sha":"9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0","message":"Add the /v1/chat route","author":"Ada Lovelace","branch":"main"},"stages":[{"name":"clone","status":"succeeded","started_at":"2026-11-13T14:00:02Z","finished_at":"2026-11-13T14:00:05Z"},{"name":"detect","status":"succeeded","started_at":"2026-11-13T14:00:05Z","finished_at":"2026-11-13T14:00:06Z"},{"name":"build","status":"succeeded","started_at":"2026-11-13T14:00:06Z","finished_at":"2026-11-13T14:02:31Z"},{"name":"push","status":"succeeded","started_at":"2026-11-13T14:02:31Z","finished_at":"2026-11-13T14:02:48Z","note":"84 MB"},{"name":"release","status":"succeeded","started_at":"2026-11-13T14:02:48Z","finished_at":"2026-11-13T14:02:49Z"},{"name":"health","status":"succeeded","started_at":"2026-11-13T14:02:49Z","finished_at":"2026-11-13T14:03:11Z"},{"name":"live","status":"succeeded","started_at":"2026-11-13T14:03:11Z","finished_at":"2026-11-13T14:03:11Z"}],"diagnosis":null,"image_digest":"sha256:4b1f9c0e7d2a8356bc41e9d0f7a6c3258e1d4b97a0c6f3e5d28b71a94c60e3fd","created_by":"Ada Lovelace","created_at":"2026-11-13T14:00:01Z","started_at":"2026-11-13T14:00:02Z","finished_at":"2026-11-13T14:03:11Z"},"schema":{"$ref":"#/components/schemas/Build"}}},"description":"The queued build."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is suspended, or a build is already running for it."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The service is not built from Git, or sha is not a commit id."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 30 builds were started by hand in the last hour."},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`github_unavailable`: Kilby could not read the latest commit from GitHub."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: Deploying from Git is not turned on."}},"summary":"Start a build","tags":["Deploys and builds"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sha\": \"9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"sha\": \"9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"sha\": \"9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"sha\": \"9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/builds/{build}":{"get":{"description":"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`.\n\nPermission: `view`.","operationId":"getBuild","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A build's id, or its number within the service (1, 2, 3).","example":"4","in":"path","name":"build","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24","number":5,"trigger":"push","status":"failed","stage":"build","commit":{"sha":"e4a7c1d93b0f4286a5d1c7e90b3f8a24d6c5b1e7","message":"Update the Dockerfile","author":"Ada Lovelace","branch":"main"},"stages":[{"name":"clone","status":"succeeded","started_at":"2026-11-13T15:10:02Z","finished_at":"2026-11-13T15:10:05Z"},{"name":"detect","status":"succeeded","started_at":"2026-11-13T15:10:05Z","finished_at":"2026-11-13T15:10:06Z"},{"name":"build","status":"failed","started_at":"2026-11-13T15:10:06Z","finished_at":"2026-11-13T15:10:19Z"}],"error":"The build failed.","diagnosis":{"code":"no_dockerfile","title":"There is no Dockerfile at Dockerfile.prod.","detail":"Kilby looked for Dockerfile.prod in the root of the repository and did not find it.","fixes":[{"label":"Use the Dockerfile at docker/Dockerfile","field":"dockerfile_path","value":"docker/Dockerfile"}]},"created_at":"2026-11-13T15:10:01Z","started_at":"2026-11-13T15:10:02Z","finished_at":"2026-11-13T15:10:19Z"},"schema":{"$ref":"#/components/schemas/Build"}}},"description":"The build."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a build","tags":["Deploys and builds"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby builds get my-api 5"}],"x-kilby-permission":"view"}},"/services/{id}/builds/{build}/analysis":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"getBuildAnalysis","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A build's id, or its number within the service (1, 2, 3).","example":"4","in":"path","name":"build","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"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."},"schema":{"additionalProperties":false,"properties":{"analysis":{"additionalProperties":false,"description":"The explanation, once `status` is `done`.","properties":{"cause":{"description":"Why, in a few sentences.","type":"string"},"confidence":{"description":"How sure the model says it is, 0 to 1.","type":"number"},"dropped":{"description":"Proposals Kilby removed because they did not pass its checks.","items":{"type":"string"},"type":"array"},"fixes":{"description":"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).","items":{"type":"object"},"type":"array"},"steps":{"description":"What to check.","items":{"type":"string"},"type":"array"},"title":{"description":"One sentence: what went wrong.","type":"string"}},"required":["title","cause","confidence","steps","fixes","dropped"],"type":"object"},"available":{"description":"Whether Kilby AI is configured on this server.","type":"boolean"},"created_at":{"format":"date-time","type":"string"},"depth":{"description":"`fast` is the quick model; `deep` is the thorough one.","enum":["fast","deep"],"type":"string"},"enabled":{"description":"Whether the workspace has turned Kilby AI on.","type":"boolean"},"error":{"additionalProperties":false,"description":"Why an analysis failed.","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"finished_at":{"format":"date-time","type":"string"},"generated_by":{"description":"Always `ai`: show it to people.","type":"string"},"id":{"description":"The analysis.","format":"uuid","type":"string"},"notice":{"description":"Text to show beside the analysis.","type":"string"},"prompt_version":{"type":"string"},"status":{"description":"`none` when nothing was asked yet.","enum":["none","queued","running","done","failed"],"type":"string"},"trigger":{"description":"`auto` when Kilby asked because no rule recognised the failure, `manual` when a person did.","enum":["auto","manual"],"type":"string"}},"required":["status","enabled","available","generated_by","notice"],"type":"object"}}},"description":"The analysis."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Read the analysis of a build","tags":["Kilby AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analysis\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analysis\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analysis\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analysis\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/services/{id}/builds/{build}/analyze":{"post":{"description":"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.\n\nPermission: `deploy`.","operationId":"analyzeBuild","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A build's id, or its number within the service (1, 2, 3).","example":"4","in":"path","name":"build","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"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."},"schema":{"additionalProperties":false,"properties":{"analysis":{"additionalProperties":false,"description":"The explanation, once `status` is `done`.","properties":{"cause":{"description":"Why, in a few sentences.","type":"string"},"confidence":{"description":"How sure the model says it is, 0 to 1.","type":"number"},"dropped":{"description":"Proposals Kilby removed because they did not pass its checks.","items":{"type":"string"},"type":"array"},"fixes":{"description":"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).","items":{"type":"object"},"type":"array"},"steps":{"description":"What to check.","items":{"type":"string"},"type":"array"},"title":{"description":"One sentence: what went wrong.","type":"string"}},"required":["title","cause","confidence","steps","fixes","dropped"],"type":"object"},"available":{"description":"Whether Kilby AI is configured on this server.","type":"boolean"},"created_at":{"format":"date-time","type":"string"},"depth":{"description":"`fast` is the quick model; `deep` is the thorough one.","enum":["fast","deep"],"type":"string"},"enabled":{"description":"Whether the workspace has turned Kilby AI on.","type":"boolean"},"error":{"additionalProperties":false,"description":"Why an analysis failed.","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"finished_at":{"format":"date-time","type":"string"},"generated_by":{"description":"Always `ai`: show it to people.","type":"string"},"id":{"description":"The analysis.","format":"uuid","type":"string"},"notice":{"description":"Text to show beside the analysis.","type":"string"},"prompt_version":{"type":"string"},"status":{"description":"`none` when nothing was asked yet.","enum":["none","queued","running","done","failed"],"type":"string"},"trigger":{"description":"`auto` when Kilby asked because no rule recognised the failure, `manual` when a person did.","enum":["auto","manual"],"type":"string"}},"required":["status","enabled","available","generated_by","notice"],"type":"object"}}},"description":"An answer already exists."},"202":{"content":{"application/json":{"example":{"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."},"schema":{"additionalProperties":false,"properties":{"analysis":{"additionalProperties":false,"description":"The explanation, once `status` is `done`.","properties":{"cause":{"description":"Why, in a few sentences.","type":"string"},"confidence":{"description":"How sure the model says it is, 0 to 1.","type":"number"},"dropped":{"description":"Proposals Kilby removed because they did not pass its checks.","items":{"type":"string"},"type":"array"},"fixes":{"description":"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).","items":{"type":"object"},"type":"array"},"steps":{"description":"What to check.","items":{"type":"string"},"type":"array"},"title":{"description":"One sentence: what went wrong.","type":"string"}},"required":["title","cause","confidence","steps","fixes","dropped"],"type":"object"},"available":{"description":"Whether Kilby AI is configured on this server.","type":"boolean"},"created_at":{"format":"date-time","type":"string"},"depth":{"description":"`fast` is the quick model; `deep` is the thorough one.","enum":["fast","deep"],"type":"string"},"enabled":{"description":"Whether the workspace has turned Kilby AI on.","type":"boolean"},"error":{"additionalProperties":false,"description":"Why an analysis failed.","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"finished_at":{"format":"date-time","type":"string"},"generated_by":{"description":"Always `ai`: show it to people.","type":"string"},"id":{"description":"The analysis.","format":"uuid","type":"string"},"notice":{"description":"Text to show beside the analysis.","type":"string"},"prompt_version":{"type":"string"},"status":{"description":"`none` when nothing was asked yet.","enum":["none","queued","running","done","failed"],"type":"string"},"trigger":{"description":"`auto` when Kilby asked because no rule recognised the failure, `manual` when a person did.","enum":["auto","manual"],"type":"string"}},"required":["status","enabled","available","generated_by","notice"],"type":"object"}}},"description":"Queued. Poll the analysis."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`ai_disabled`: The workspace has not turned Kilby AI on (Workspace settings, Kilby AI), or a platform admin has paused it."},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The build or deploy did not fail, so there is nothing to explain."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`ai_budget`: The workspace or the platform reached its daily allowance, or `ai_busy`: too many analyses are running. Both send `Retry-After`."}},"summary":"Explain a failed build","tags":["Kilby AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analyze\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analyze\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analyze\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/analyze\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/builds/{build}/cancel":{"post":{"description":"Stops a queued or running build. A build whose image is already being released cannot be canceled: roll back instead.\n\nPermission: `deploy`.","operationId":"cancelBuild","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A build's id, or its number within the service (1, 2, 3).","example":"4","in":"path","name":"build","required":true,"schema":{"type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24","number":4,"trigger":"push","status":"running","stage":"build","commit":{"sha":"9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0","message":"Add the /v1/chat route","author":"Ada Lovelace","branch":"main"},"stages":[{"name":"clone","status":"succeeded","started_at":"2026-11-13T14:00:02Z","finished_at":"2026-11-13T14:00:05Z"},{"name":"detect","status":"succeeded","started_at":"2026-11-13T14:00:05Z","finished_at":"2026-11-13T14:00:06Z"},{"name":"build","status":"succeeded","started_at":"2026-11-13T14:00:06Z","finished_at":"2026-11-13T14:02:31Z"},{"name":"push","status":"succeeded","started_at":"2026-11-13T14:02:31Z","finished_at":"2026-11-13T14:02:48Z","note":"84 MB"},{"name":"release","status":"succeeded","started_at":"2026-11-13T14:02:48Z","finished_at":"2026-11-13T14:02:49Z"},{"name":"health","status":"succeeded","started_at":"2026-11-13T14:02:49Z","finished_at":"2026-11-13T14:03:11Z"},{"name":"live","status":"succeeded","started_at":"2026-11-13T14:03:11Z","finished_at":"2026-11-13T14:03:11Z"}],"diagnosis":null,"image_digest":"sha256:4b1f9c0e7d2a8356bc41e9d0f7a6c3258e1d4b97a0c6f3e5d28b71a94c60e3fd","created_by":"Ada Lovelace","created_at":"2026-11-13T14:00:01Z","started_at":"2026-11-13T14:00:02Z","finished_at":"2026-11-13T14:03:11Z"},"schema":{"$ref":"#/components/schemas/Build"}}},"description":"The build, being canceled."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The build has finished, or its image is already being deployed."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Cancel a build","tags":["Deploys and builds"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/cancel\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/cancel\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/cancel\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/cancel\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby builds cancel my-api 4"}],"x-kilby-permission":"deploy"}},"/services/{id}/builds/{build}/logs":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"getBuildLogs","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A build's id, or its number within the service (1, 2, 3).","example":"4","in":"path","name":"build","required":true,"schema":{"type":"string"}},{"description":"Only lines with a higher seq. 0 starts from the beginning.","example":0,"in":"query","name":"after","required":false,"schema":{"default":0,"type":"integer"}},{"description":"The most lines to return. Allowed: 1 to 2000.","in":"query","name":"limit","required":false,"schema":{"default":500,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"lines":[{"seq":1,"at":"2026-11-13T14:00:02Z","stage":"clone","level":"info","text":"Cloning acme/express-api at 9c1d3fe"},{"seq":2,"at":"2026-11-13T14:00:05Z","stage":"detect","level":"info","text":"Found a Node.js project (Express)"}],"next_after":2,"done":false,"status":"running","stage":"detect"},"schema":{"additionalProperties":false,"properties":{"done":{"description":"true when the build ended and there is nothing more to read.","type":"boolean"},"lines":{"items":{"$ref":"#/components/schemas/BuildLogLine"},"type":"array"},"next_after":{"description":"Send this as after to continue.","type":"integer"},"stage":{"description":"The build's stage.","type":"string"},"status":{"description":"The build's status.","type":"string"}},"required":["lines","next_after","done","status","stage"],"type":"object"}}},"description":"A page of log lines."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Read a build's log","tags":["Deploys and builds"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/logs?after=0\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/logs?after=0\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/logs?after=0\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/logs?after=0\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby builds logs my-api 4"}],"x-kilby-permission":"view"}},"/services/{id}/builds/{build}/retry":{"post":{"description":"Builds the same commit again, as a new build with trigger `rebuild`. Use it after you fixed a setting, or when the failure was not about the code.\n\nPermission: `deploy`.","operationId":"retryBuild","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A build's id, or its number within the service (1, 2, 3).","example":"4","in":"path","name":"build","required":true,"schema":{"type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"5f1c9d7a-2b8e-4a63-b1f0-6c3d9e8a7b24","number":4,"trigger":"rebuild","status":"queued","stage":"clone","commit":{"sha":"9c1d3fe7a2b84d05c6e1f0a93b7d2c48e5f6a1b0","message":"Add the /v1/chat route","author":"Ada Lovelace","branch":"main"},"stages":[{"name":"clone","status":"succeeded","started_at":"2026-11-13T14:00:02Z","finished_at":"2026-11-13T14:00:05Z"},{"name":"detect","status":"succeeded","started_at":"2026-11-13T14:00:05Z","finished_at":"2026-11-13T14:00:06Z"},{"name":"build","status":"succeeded","started_at":"2026-11-13T14:00:06Z","finished_at":"2026-11-13T14:02:31Z"},{"name":"push","status":"succeeded","started_at":"2026-11-13T14:02:31Z","finished_at":"2026-11-13T14:02:48Z","note":"84 MB"},{"name":"release","status":"succeeded","started_at":"2026-11-13T14:02:48Z","finished_at":"2026-11-13T14:02:49Z"},{"name":"health","status":"succeeded","started_at":"2026-11-13T14:02:49Z","finished_at":"2026-11-13T14:03:11Z"},{"name":"live","status":"succeeded","started_at":"2026-11-13T14:03:11Z","finished_at":"2026-11-13T14:03:11Z"}],"diagnosis":null,"image_digest":"sha256:4b1f9c0e7d2a8356bc41e9d0f7a6c3258e1d4b97a0c6f3e5d28b71a94c60e3fd","created_by":"Ada Lovelace","created_at":"2026-11-13T14:00:01Z","started_at":"2026-11-13T14:00:02Z","finished_at":"2026-11-13T14:03:11Z"},"schema":{"$ref":"#/components/schemas/Build"}}},"description":"The new build."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The build is still in progress, or the service is suspended."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 30 builds were started by hand in the last hour."}},"summary":"Retry a build","tags":["Deploys and builds"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/retry\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/retry\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/retry\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/builds/4/retry\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby builds retry my-api 5"}],"x-kilby-permission":"deploy"}},"/services/{id}/deploy-hook":{"delete":{"description":"Revokes the hook. Its URL stops working immediately.\n\nPermission: `deploy`.","operationId":"deleteDeployHook","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Revoked. There is no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The service has no deploy hook."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Revoke a deploy hook","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status); // 204: nothing to read\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code)  # 204: nothing to read\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"},"get":{"description":"Whether the service has a deploy hook, and when it was last used. The URL itself is never shown again after it was created.\n\nPermission: `view`.","operationId":"getDeployHook","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"prefix":"kdh_3f9a","created_at":"2026-11-13T14:05:00Z","last_used_at":null},"schema":{"$ref":"#/components/schemas/DeployHook"}}},"description":"The hook, without its URL."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The service has no deploy hook."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a deploy hook","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nPermission: `deploy`.","operationId":"createDeployHook","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"201":{"content":{"application/json":{"example":{"url":"https://onkilby.com/hooks/deploy/kdh_3f9a1c7e5b2d8046a9e1c4f7b30d2685c1a7e9f4d6b8203a5","prefix":"kdh_3f9a","created_at":"2026-11-13T14:05:00Z","last_used_at":null},"schema":{"$ref":"#/components/schemas/DeployHook"}}},"description":"The hook, with its URL."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 20 hooks were created in the last hour."}},"summary":"Create a deploy hook","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploy-hook\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/deploys":{"get":{"description":"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`.\n\nWhen 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.\n\nPermission: `view`.","operationId":"listDeploys","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"deploys":[{"id":"5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d","image":"ghcr.io/acme/api:1.4","trigger":"update","status":"live","message":"","created_at":"2026-11-13T14:00:00Z","finished_at":"2026-11-13T14:01:12Z","title":"Instance type: Starter to Standard","pre_deploy":{"command":"python manage.py migrate","status":"succeeded","message":"","started_at":"2026-11-13T14:00:03Z","finished_at":"2026-11-13T14:00:21Z","exit_code":0,"output":"Applying orders.0007_add_index... OK"}},{"id":"8a0f6c2d-1b4e-4d97-a3c5-6e7f8091a2b3","image":"ghcr.io/acme/api:1.3","trigger":"create","status":"superseded","message":"","created_at":"2026-11-12T22:40:11Z","finished_at":"2026-11-12T22:41:30Z","title":"1.3","pre_deploy":null}]},"schema":{"additionalProperties":false,"properties":{"deploys":{"items":{"$ref":"#/components/schemas/Deploy"},"type":"array"}},"required":["deploys"],"type":"object"}}},"description":"The deploys."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List deploys","tags":["Deploys and builds"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nIf 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.\n\nTo deploy a different image or settings, use Change a service. To deploy from CI without an API key, see Deploy hooks.\n\nPermission: `deploy`.","operationId":"redeployService","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Redeploy without the pre-deploy command","value":{"skip_pre_deploy":true}}},"schema":{"additionalProperties":false,"properties":{"skip_pre_deploy":{"default":false,"description":"Deploy without running the pre-deploy command, this time only.","type":"boolean"}},"type":"object"}}},"required":false},"responses":{"202":{"content":{"application/json":{"example":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api","type":"web","image":"ghcr.io/acme/api:1.4","port":8080,"plan":"starter","status":"deploying","status_message":"","suspended":false,"url":"https://my-api-x7k2.apps.kilby.neuramorphic.ai","internal_address":"my-api:8080","created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-13T14:05:00Z","registry_credential_id":null,"health_check_path":"/healthz","instances":2,"autoscaling":{"min":2,"max":4,"target_cpu_percent":70},"disk":null,"instances_running":1,"instances_desired":2,"pre_deploy_command":"","pre_deploy_timeout_seconds":600,"source":null,"environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"auto_concurrency":true,"render_compat":false,"stop_first":false,"read_only_root":false,"maintenance":false,"maintenance_message":"","primary_domain":"my-api-x7k2.apps.kilby.neuramorphic.ai","primary_domain_choice":null},"schema":{"$ref":"#/components/schemas/Service"}}},"description":"The service, deploying."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is suspended or being deleted, or a service built from Git has no build yet."},"422":{"$ref":"#/components/responses/InvalidRequest"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Redeploy a service","tags":["Deploys and builds"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"skip_pre_deploy\": true}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"skip_pre_deploy\": true}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"skip_pre_deploy\": True},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"skip_pre_deploy\": true}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/deploys/{deploy}/analysis":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"getDeployAnalysis","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A deploy's id, from List deploys.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"deploy","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"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."},"schema":{"additionalProperties":false,"properties":{"analysis":{"additionalProperties":false,"description":"The explanation, once `status` is `done`.","properties":{"cause":{"description":"Why, in a few sentences.","type":"string"},"confidence":{"description":"How sure the model says it is, 0 to 1.","type":"number"},"dropped":{"description":"Proposals Kilby removed because they did not pass its checks.","items":{"type":"string"},"type":"array"},"fixes":{"description":"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).","items":{"type":"object"},"type":"array"},"steps":{"description":"What to check.","items":{"type":"string"},"type":"array"},"title":{"description":"One sentence: what went wrong.","type":"string"}},"required":["title","cause","confidence","steps","fixes","dropped"],"type":"object"},"available":{"description":"Whether Kilby AI is configured on this server.","type":"boolean"},"created_at":{"format":"date-time","type":"string"},"depth":{"description":"`fast` is the quick model; `deep` is the thorough one.","enum":["fast","deep"],"type":"string"},"enabled":{"description":"Whether the workspace has turned Kilby AI on.","type":"boolean"},"error":{"additionalProperties":false,"description":"Why an analysis failed.","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"finished_at":{"format":"date-time","type":"string"},"generated_by":{"description":"Always `ai`: show it to people.","type":"string"},"id":{"description":"The analysis.","format":"uuid","type":"string"},"notice":{"description":"Text to show beside the analysis.","type":"string"},"prompt_version":{"type":"string"},"status":{"description":"`none` when nothing was asked yet.","enum":["none","queued","running","done","failed"],"type":"string"},"trigger":{"description":"`auto` when Kilby asked because no rule recognised the failure, `manual` when a person did.","enum":["auto","manual"],"type":"string"}},"required":["status","enabled","available","generated_by","notice"],"type":"object"}}},"description":"The analysis."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Read the analysis of a deploy","tags":["Kilby AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analysis\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analysis\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analysis\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analysis\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/services/{id}/deploys/{deploy}/analyze":{"post":{"description":"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.\n\nPermission: `deploy`.","operationId":"analyzeDeploy","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A deploy's id, from List deploys.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"deploy","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"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."},"schema":{"additionalProperties":false,"properties":{"analysis":{"additionalProperties":false,"description":"The explanation, once `status` is `done`.","properties":{"cause":{"description":"Why, in a few sentences.","type":"string"},"confidence":{"description":"How sure the model says it is, 0 to 1.","type":"number"},"dropped":{"description":"Proposals Kilby removed because they did not pass its checks.","items":{"type":"string"},"type":"array"},"fixes":{"description":"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).","items":{"type":"object"},"type":"array"},"steps":{"description":"What to check.","items":{"type":"string"},"type":"array"},"title":{"description":"One sentence: what went wrong.","type":"string"}},"required":["title","cause","confidence","steps","fixes","dropped"],"type":"object"},"available":{"description":"Whether Kilby AI is configured on this server.","type":"boolean"},"created_at":{"format":"date-time","type":"string"},"depth":{"description":"`fast` is the quick model; `deep` is the thorough one.","enum":["fast","deep"],"type":"string"},"enabled":{"description":"Whether the workspace has turned Kilby AI on.","type":"boolean"},"error":{"additionalProperties":false,"description":"Why an analysis failed.","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"finished_at":{"format":"date-time","type":"string"},"generated_by":{"description":"Always `ai`: show it to people.","type":"string"},"id":{"description":"The analysis.","format":"uuid","type":"string"},"notice":{"description":"Text to show beside the analysis.","type":"string"},"prompt_version":{"type":"string"},"status":{"description":"`none` when nothing was asked yet.","enum":["none","queued","running","done","failed"],"type":"string"},"trigger":{"description":"`auto` when Kilby asked because no rule recognised the failure, `manual` when a person did.","enum":["auto","manual"],"type":"string"}},"required":["status","enabled","available","generated_by","notice"],"type":"object"}}},"description":"An answer already exists."},"202":{"content":{"application/json":{"example":{"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."},"schema":{"additionalProperties":false,"properties":{"analysis":{"additionalProperties":false,"description":"The explanation, once `status` is `done`.","properties":{"cause":{"description":"Why, in a few sentences.","type":"string"},"confidence":{"description":"How sure the model says it is, 0 to 1.","type":"number"},"dropped":{"description":"Proposals Kilby removed because they did not pass its checks.","items":{"type":"string"},"type":"array"},"fixes":{"description":"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).","items":{"type":"object"},"type":"array"},"steps":{"description":"What to check.","items":{"type":"string"},"type":"array"},"title":{"description":"One sentence: what went wrong.","type":"string"}},"required":["title","cause","confidence","steps","fixes","dropped"],"type":"object"},"available":{"description":"Whether Kilby AI is configured on this server.","type":"boolean"},"created_at":{"format":"date-time","type":"string"},"depth":{"description":"`fast` is the quick model; `deep` is the thorough one.","enum":["fast","deep"],"type":"string"},"enabled":{"description":"Whether the workspace has turned Kilby AI on.","type":"boolean"},"error":{"additionalProperties":false,"description":"Why an analysis failed.","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"finished_at":{"format":"date-time","type":"string"},"generated_by":{"description":"Always `ai`: show it to people.","type":"string"},"id":{"description":"The analysis.","format":"uuid","type":"string"},"notice":{"description":"Text to show beside the analysis.","type":"string"},"prompt_version":{"type":"string"},"status":{"description":"`none` when nothing was asked yet.","enum":["none","queued","running","done","failed"],"type":"string"},"trigger":{"description":"`auto` when Kilby asked because no rule recognised the failure, `manual` when a person did.","enum":["auto","manual"],"type":"string"}},"required":["status","enabled","available","generated_by","notice"],"type":"object"}}},"description":"Queued. Poll the analysis."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`ai_disabled`: The workspace has not turned Kilby AI on (Workspace settings, Kilby AI), or a platform admin has paused it."},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The build or deploy did not fail, so there is nothing to explain."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`ai_budget`: The workspace or the platform reached its daily allowance, or `ai_busy`: too many analyses are running. Both send `Retry-After`."}},"summary":"Explain a failed deploy","tags":["Kilby AI"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analyze\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analyze\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analyze\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/analyze\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/deploys/{deploy}/rollback-preview":{"get":{"description":"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.\n\n`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.\n\nPermission: `deploy`.","operationId":"previewRollback","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"The deploy to go back to, from List deploys.","example":"5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d","in":"path","name":"deploy","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"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."]},"schema":{"$ref":"#/components/schemas/RollbackPreview"}}},"description":"What would change."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The service has no such deploy."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Preview a rollback","tags":["Deploys and builds"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d/rollback-preview\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d/rollback-preview\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d/rollback-preview\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/deploys/5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d/rollback-preview\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby rollback my-api --preview"}],"x-kilby-permission":"deploy"}},"/services/{id}/disk/snapshots":{"get":{"description":"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.\n\nNeeds 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.\n\nPermission: `deploy`.","operationId":"listDiskSnapshots","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"enabled":true,"retention_days":7,"weekly_kept":0,"next_snapshot_at":"2026-11-14T03:00:00Z","disk_created":true,"snapshots":[{"id":"snap-0a1b2c3d4e5f67890","created_at":"2026-11-13T03:12:00Z","size_gb":10,"status":"completed","progress_percent":100,"type":"daily","expires_at":"2026-11-20T03:12:00Z"}],"restored_disks":[]},"schema":{"additionalProperties":false,"properties":{"disk_created":{"description":"false until the service has started once and its disk exists.","type":"boolean"},"enabled":{"description":"false when this platform does not take snapshots yet.","type":"boolean"},"next_snapshot_at":{"description":"When the schedule starts its next snapshot. Snapshots start within the hour after.","format":"date-time","type":["string","null"]},"restored_disks":{"description":"Disks restored from this service's snapshots.","items":{"$ref":"#/components/schemas/RestoredDisk"},"type":"array"},"retention_days":{"description":"How long a daily snapshot is kept.","type":"integer"},"snapshots":{"items":{"$ref":"#/components/schemas/DiskSnapshot"},"type":"array"},"weekly_kept":{"description":"How many weekly snapshots are kept besides the daily ones; 0 for none.","type":"integer"}},"required":["enabled","retention_days","weekly_kept","next_snapshot_at","disk_created","snapshots","restored_disks"],"type":"object"}}},"description":"The snapshots."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service has no disk."},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: The snapshots could not be read right now."}},"summary":"List disk snapshots","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/disk/snapshots/{snapshot_id}/restore":{"post":{"description":"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.\n\nA 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.\n\nNeeds 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.\n\nPermission: `workspace`.","operationId":"restoreDiskSnapshot","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A snapshot's id, from List snapshots.","example":"snap-0a1b2c3d4e5f67890","in":"path","name":"snapshot_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Name the new disk","value":{"name":"my-api-before-migration"}}},"schema":{"additionalProperties":false,"properties":{"name":{"description":"The new disk's name. Defaults to the service's name, restored, and the snapshot's date. Allowed: 3 to 50 characters; not ending in -disk or starting with db-.","type":"string"}},"type":"object"}}},"description":"The body is optional.","required":false},"responses":{"202":{"content":{"application/json":{"example":{"restored_disk":{"id":"6a8d3f20-91c4-4e1b-8b57-0d2e4c9a1f33","name":"my-api-restored-20261113","status":"creating","message":"","size_gb":10,"snapshot_id":"snap-0a1b2c3d4e5f67890","snapshot_created_at":"2026-11-13T03:12:00Z","created_at":"2026-11-13T14:05:00Z","service":null}},"schema":{"additionalProperties":false,"properties":{"restored_disk":{"$ref":"#/components/schemas/RestoredDisk"}},"required":["restored_disk"],"type":"object"}}},"description":"The restore, in progress."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: No snapshot with that id belongs to this service's disk."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: Snapshots are not switched on, the service has no disk, the snapshot is not finished, or the name is taken."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The name is not valid, or the new disk would exceed the workspace's disk limit."},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: The snapshots could not be read right now."}},"summary":"Restore a disk snapshot","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots/snap-0a1b2c3d4e5f67890/restore\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"my-api-before-migration\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots/snap-0a1b2c3d4e5f67890/restore\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"name\": \"my-api-before-migration\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots/snap-0a1b2c3d4e5f67890/restore\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"name\": \"my-api-before-migration\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"name\": \"my-api-before-migration\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/disk/snapshots/snap-0a1b2c3d4e5f67890/restore\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/services/{id}/domains":{"get":{"description":"The custom domains of a web service, with the DNS records each one needs.\n\nPermission: `view`.","operationId":"listDomains","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"default_hostname":"my-api-x7k2.apps.kilby.neuramorphic.ai","domains":[{"id":"5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11","service_id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","hostname":"api.example.com","apex":false,"status":"pending_dns","status_message":"","dns_records":[{"type":"CNAME","name":"api.example.com","value":"my-api-x7k2.apps.kilby.neuramorphic.ai","purpose":"route"},{"type":"TXT","name":"_kilby-challenge.api.example.com","value":"kilby-verify=k3x9a1c7e5b2d804","purpose":"ownership"},{"type":"CNAME","name":"_acme-challenge.api.example.com","value":"k3x9a1c7e5b2d804.acme.kilby.neuramorphic.ai","purpose":"certificate"}],"verified_at":null,"certificate_expires_at":null,"certificate_validation":"http","routed_at":null,"redirect_to":null,"last_checked_at":null,"next_check_at":"2026-11-13T14:07:00Z","created_at":"2026-11-13T14:05:00Z"}]},"schema":{"additionalProperties":false,"properties":{"default_hostname":{"description":"The address every service has.","type":"string"},"domains":{"items":{"$ref":"#/components/schemas/Domain"},"type":"array"}},"required":["default_hostname","domains"],"type":"object"}}},"description":"The domains and the service's own address."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The service is not a web service."},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: Custom domains are not turned on."}},"summary":"List domains","tags":["Domains"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nThe 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.\n\nWhere Kilby offers it, the list also has an `_acme-challenge` `CNAME` (`purpose` `certificate`). Moving a site that is live elsewhere, create that record alone first: it proves ownership too, and the certificate is issued while visitors still go to the old host. The domain is then `active` with `routed_at` null until you switch its first record to Kilby.\n\nPermission: `deploy`.","operationId":"addDomain","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Add a subdomain","value":{"hostname":"api.example.com"}}},"schema":{"additionalProperties":false,"properties":{"hostname":{"description":"The domain, such as api.example.com. Allowed: a valid host name, not an address under Kilby's own domains.","type":"string"}},"required":["hostname"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"id":"5b0f6a51-8d3c-4c7e-9a43-0e2d1f9b7c11","service_id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","hostname":"api.example.com","apex":false,"status":"pending_dns","status_message":"","dns_records":[{"type":"CNAME","name":"api.example.com","value":"my-api-x7k2.apps.kilby.neuramorphic.ai","purpose":"route"},{"type":"TXT","name":"_kilby-challenge.api.example.com","value":"kilby-verify=k3x9a1c7e5b2d804","purpose":"ownership"},{"type":"CNAME","name":"_acme-challenge.api.example.com","value":"k3x9a1c7e5b2d804.acme.kilby.neuramorphic.ai","purpose":"certificate"}],"verified_at":null,"certificate_expires_at":null,"certificate_validation":"http","routed_at":null,"redirect_to":null,"last_checked_at":null,"next_check_at":"2026-11-13T14:07:00Z","created_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/Domain"}}},"description":"The domain, waiting for its DNS records."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The domain is already used by another service."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The host name is not valid, the service is not a web service, or a limit was reached."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 30 domains were added in the last hour."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: Custom domains are not turned on."}},"summary":"Add a custom domain","tags":["Domains"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"hostname\": \"api.example.com\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"hostname\": \"api.example.com\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"hostname\": \"api.example.com\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"hostname\": \"api.example.com\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/domains\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/env":{"get":{"description":"The names of the service's environment variables, never their values. A read-only key can call it, as a viewer sees the names in the dashboard.\n\nPermission: `view`.","operationId":"getEnv","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"names":["DATABASE_URL","LOG_LEVEL"]},"schema":{"additionalProperties":false,"properties":{"names":{"items":{"type":"string"},"type":"array"}},"required":["names"],"type":"object"}}},"description":"The names, sorted. Empty when there are none."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List environment variables","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby env list"}],"x-kilby-permission":"view"},"patch":{"description":"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.\n\nPermission: `secrets`.","operationId":"patchEnv","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Set one and remove one","value":{"set":{"LOG_LEVEL":"debug"},"unset":["OLD_FLAG"]}}},"schema":{"additionalProperties":false,"properties":{"set":{"additionalProperties":{"type":"string"},"description":"Name to value. Allowed: names of letters, digits and underscores up to 128 characters, values up to 8 KB, up to 100 variables and 512 KB per service.","type":"object"},"unset":{"description":"Names to remove.","items":{"type":"string"},"type":"array"}},"type":"object"}}},"description":"Both fields are optional; `{}` changes nothing. Unknown fields, `null`, a value that is not a string and a name in both lists are refused.","required":false},"responses":{"200":{"content":{"application/json":{"example":{"names":["DATABASE_URL","LOG_LEVEL"],"added":[],"changed":["LOG_LEVEL"],"removed":["OLD_FLAG"],"restarted":true},"schema":{"additionalProperties":false,"properties":{"added":{"items":{"type":"string"},"type":"array"},"changed":{"items":{"type":"string"},"type":"array"},"names":{"items":{"type":"string"},"type":"array"},"removed":{"items":{"type":"string"},"type":"array"},"restarted":{"description":"Whether the service restarts to use the new values.","type":"boolean"}},"required":["names","added","changed","removed","restarted"],"type":"object"}}},"description":"The names now set, and what changed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is being deleted."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`too_large`: The request is larger than 512 KB."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A name or value is not valid, or the body has fields it should not."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Change environment variables","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"set\": {\"LOG_LEVEL\": \"debug\"}, \"unset\": [\"OLD_FLAG\"]}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"set\": {\"LOG_LEVEL\": \"debug\"}, \"unset\": [\"OLD_FLAG\"]}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"set\": {\"LOG_LEVEL\": \"debug\"}, \"unset\": [\"OLD_FLAG\"]},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"set\": {\"LOG_LEVEL\": \"debug\"}, \"unset\": [\"OLD_FLAG\"]}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby env set"}],"x-kilby-permission":"secrets"}},"/services/{id}/env-groups":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"listServiceEnvGroups","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"env_groups":[{"id":"c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c","name":"shared-keys","position":1}]},"schema":{"additionalProperties":false,"properties":{"env_groups":{"description":"The groups in order, first wins: `id`, `name` and `position` (1 is first).","items":{"type":"object"},"type":"array"}},"required":["env_groups"],"type":"object"}}},"description":"The groups, in order."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List the groups a service uses","tags":["Environment groups"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"put":{"description":"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`.\n\nPermission: `deploy`.","operationId":"setServiceEnvGroups","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Two groups","value":{"env_groups":["shared-keys","flags"]}},"example2":{"summary":"Unlink all","value":{"env_groups":[]}}},"schema":{"additionalProperties":false,"properties":{"env_groups":{"description":"Group names or ids, first one winning. An empty list unlinks them all. Allowed: up to 20 groups per service by default.","items":{"type":"string"},"type":"array"}},"required":["env_groups"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"env_groups":[{"id":"c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c","name":"shared-keys","position":1}],"linked":["shared-keys"],"unlinked":[],"restarted":true},"schema":{"additionalProperties":false,"properties":{"env_groups":{"description":"The groups in order: `id`, `name` and `position`.","items":{"type":"object"},"type":"array"},"linked":{"description":"Names of the groups that are new.","items":{"type":"string"},"type":"array"},"restarted":{"description":"Whether the service restarts to use the new variables.","type":"boolean"},"unlinked":{"description":"Names of the groups that were removed.","items":{"type":"string"},"type":"array"}},"required":["env_groups","linked","unlinked","restarted"],"type":"object"}}},"description":"The groups now linked and what changed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: A group is not one of this workspace's."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is being deleted, or a group appears twice."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: More groups than a service can use, or the service would receive more than 512 KB of variables."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Link groups to a service","tags":["Environment groups"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PUT \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"env_groups\": [\"shared-keys\", \"flags\"]}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups\", {\n  method: \"PUT\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"env_groups\": [\"shared-keys\", \"flags\"]}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.put(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"env_groups\": [\"shared-keys\", \"flags\"]},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"env_groups\": [\"shared-keys\", \"flags\"]}`)\n\treq, err := http.NewRequest(\"PUT\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env-groups\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby env-group link"}],"x-kilby-permission":"deploy"}},"/services/{id}/env/effective":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"getEffectiveEnv","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"variables":[{"name":"LOG_LEVEL","source":"service","group":null,"overrides":["shared-keys"]},{"name":"OPENAI_API_KEY","source":"group","group":{"id":"c1a2f3e4-6b7d-4c8e-9a0b-1d2e3f4a5b6c","name":"shared-keys","position":1},"overrides":[]}]},"schema":{"additionalProperties":false,"properties":{"variables":{"description":"Each has `name`, `source` (`service` or `group`), `group` (`id`, `name`, `position`; null for the service's own) and `overrides`.","items":{"type":"object"},"type":"array"}},"required":["variables"],"type":"object"}}},"description":"The variables, sorted by name."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List the effective environment","tags":["Environment groups"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env/effective\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env/effective\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env/effective\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/env/effective\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/services/{id}/events":{"get":{"description":"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.\n\nEvery 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.\n\nOnly 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.\n\nUp 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.\n\nPermission: `view`.","operationId":"listServiceEvents","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"How far back to look. The same ranges as the metrics.","example":"24h","in":"query","name":"range","required":false,"schema":{"default":"1h","enum":["1h","6h","24h","7d"],"type":"string"}},{"description":"Only events of these kinds. Repeat it or separate the kinds with commas.","example":"failure,scale","in":"query","name":"kind","required":false,"schema":{"enum":["deploy","failure","scale","state","config","maintenance"],"type":"string"}},{"description":"How many events to return. Allowed: 1 to 200.","example":100,"in":"query","name":"limit","required":false,"schema":{"default":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"range":"24h","from":"2026-11-13T14:10:00Z","to":"2026-11-14T14:10:00Z","truncated":false,"events":[{"id":"d-5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d-live","type":"deploy_live","kind":"deploy","title":"Deploy live","detail":"took 1m 12s · api:1.4","at":"2026-11-14T13:41:12Z","by":{"kind":"system","name":"Kilby"},"url":"https://kilby.example.com/dashboard/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events#d-5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d"},{"id":"d-5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d-start","type":"deploy_started","kind":"deploy","title":"Deploy started","detail":"After a settings change · api:1.4","at":"2026-11-14T13:40:00Z","by":{"kind":"person","name":"Ada Lovelace"},"url":"https://kilby.example.com/dashboard/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events#d-5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d"},{"id":"e-4812","type":"scaled","kind":"scale","title":"Instance count changed","detail":"Instances: 1 → 2","at":"2026-11-14T13:40:00Z","by":{"kind":"person","name":"Ada Lovelace"},"url":"https://kilby.example.com/dashboard/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events"}]},"schema":{"additionalProperties":false,"properties":{"events":{"description":"Newest first.","items":{"additionalProperties":false,"properties":{"at":{"description":"When it happened.","format":"date-time","type":"string"},"by":{"additionalProperties":false,"description":"Who did it.","properties":{"kind":{"enum":["person","hook","system","unknown"],"type":"string"},"name":{"description":"The person's name, `Deploy hook`, `Kilby` or `Someone`.","type":"string"}},"required":["kind","name"],"type":"object"},"detail":{"description":"More about it: the image, how long it took, what changed. Empty when there is nothing to add.","type":"string"},"id":{"description":"Stays the same every time the event is read.","type":"string"},"kind":{"description":"The group of the type.","enum":["deploy","failure","scale","state","config","maintenance"],"type":"string"},"title":{"description":"A short sentence.","type":"string"},"type":{"description":"What happened, exactly.","enum":["deploy_started","deploy_live","deploy_failed","crashed","restarted","rolled_back","scaled","resized","disk_changed","suspended","resumed","created","env_changed","settings_changed","domain_changed","maintenance"],"type":"string"},"url":{"description":"The page in the dashboard that tells more.","type":"string"}},"required":["id","type","kind","title","detail","at","by","url"],"type":"object"},"type":"array"},"from":{"format":"date-time","type":"string"},"range":{"type":"string"},"to":{"format":"date-time","type":"string"},"truncated":{"description":"true when the range holds more events than were returned: the oldest are left out.","type":"boolean"}},"required":["range","from","to","truncated","events"],"type":"object"}}},"description":"The events."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: range is not one of the four values, kind is not a kind, or limit is not a number from 1 to 200."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List events","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events?kind=failure%2Cscale\u0026limit=100\u0026range=24h\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events?kind=failure%2Cscale\\u0026limit=100\\u0026range=24h\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events?kind=failure%2Cscale\\u0026limit=100\\u0026range=24h\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/events?kind=failure%2Cscale\u0026limit=100\u0026range=24h\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/services/{id}/git-hook":{"delete":{"description":"Revokes the hook. Its URL stops working immediately.\n\nPermission: `deploy`.","operationId":"deleteGitHook","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Revoked. There is no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The service has no build hook."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Revoke a build hook","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status); // 204: nothing to read\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code)  # 204: nothing to read\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"},"get":{"description":"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.\n\nPermission: `view`.","operationId":"getGitHook","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"prefix":"kgh_3f9a","created_at":"2026-11-13T14:05:00Z","last_used_at":null},"schema":{"$ref":"#/components/schemas/DeployHook"}}},"description":"The hook, without its URL."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The service has no build hook."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The service is not built from a public repository."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a build hook","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nPermission: `deploy`.","operationId":"createGitHook","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"201":{"content":{"application/json":{"example":{"url":"https://onkilby.com/hooks/git/kgh_3f9a1c7e5b2d8046a9e1c4f7b30d2685c1a7e9f4d6b8203a5","prefix":"kgh_3f9a","created_at":"2026-11-13T14:05:00Z","last_used_at":null},"schema":{"$ref":"#/components/schemas/DeployHook"}}},"description":"The hook, with its URL."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The service is not built from a public repository."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 20 hooks were created in the last hour."}},"summary":"Create a build hook","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/git-hook\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/logs":{"get":{"description":"Reads a service's log in one of two ways.\n\n**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.\n\n**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.\n\nPermission: `view`.","operationId":"getServiceLogs","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Live only: how many lines to return. Allowed: 1 to 2000.","example":100,"in":"query","name":"tail","required":false,"schema":{"default":200,"type":"integer"}},{"description":"Stored: start of the range, inclusive. A time like `2026-11-14T10:00:00Z`, or how long ago: `15m`, `1h`, `24h`, `7d`.","in":"query","name":"since","required":false,"schema":{"type":"string"}},{"description":"Stored: end of the range, exclusive. A time or how long ago.","in":"query","name":"until","required":false,"schema":{"default":"now","type":"string"}},{"description":"Stored: only lines that contain this text, ignoring case. A plain substring, not a pattern. Allowed: up to 200 characters.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"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).","in":"query","name":"level","required":false,"schema":{"type":"string"}},{"description":"Stored: how many lines to return. Allowed: 1 to 1000.","in":"query","name":"limit","required":false,"schema":{"default":200,"type":"integer"}},{"description":"Stored: `desc` returns the newest lines first, `asc` the oldest first.","in":"query","name":"order","required":false,"schema":{"default":"desc","enum":["desc","asc"],"type":"string"}},{"description":"Stored: `next_cursor` of the previous answer to the same request, to read the next page.","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Stored: `json`, or `text` for plain lines like `2026-11-14T10:00:00.123Z [x2k4p] message`.","in":"query","name":"format","required":false,"schema":{"default":"json","enum":["json","text"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"lines":[{"time":"2026-11-13T14:09:03.412Z","instance":"x2k4p","message":"panic: runtime error: invalid memory address or nil pointer dereference","level":"error"},{"time":"2026-11-13T14:09:01.120Z","instance":"x2k4p","message":"GET /v1/chat 200 412ms","level":"info"}],"next_cursor":"1.q3k9Xw2b.MTc5NDYzNTc0MTEyMDAwMDAwMC80Mi8w","partial":false,"note":"","order":"desc"},"schema":{"additionalProperties":false,"properties":{"lines":{"description":"In the order asked for.","items":{"$ref":"#/components/schemas/LogLine"},"type":"array"},"next_cursor":{"description":"Pass it as `cursor` for the next page. Empty when the range holds nothing more.","type":"string"},"note":{"description":"Says what happened when `partial` is true. Empty otherwise.","type":"string"},"order":{"description":"`desc` or `asc`.","type":"string"},"partial":{"description":"true when the search stopped at its limit before the end of the range.","type":"boolean"}},"required":["lines","next_cursor","partial","note","order"],"type":"object"}}},"description":"Stored logs: a page of lines. Without the stored parameters the answer is the live text described above."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A time, level, limit or cursor is not valid."},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: Live logs are not available in this environment, or stored logs were asked for and log storage is off."}},"summary":"Read logs","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/logs?tail=100\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/logs?tail=100\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/logs?tail=100\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/logs?tail=100\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby logs my-api --since 1h --grep timeout"}],"x-kilby-permission":"view"}},"/services/{id}/maintenance":{"put":{"description":"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.\n\nOnly 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.\n\nPermission: `deploy`.","operationId":"setServiceMaintenance","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Turn on with a message","value":{"enabled":true,"message":"We are upgrading the database. Back at 14:00 UTC."}},"example2":{"summary":"Turn off","value":{"enabled":false}}},"schema":{"additionalProperties":false,"properties":{"enabled":{"description":"`true` turns maintenance mode on, `false` turns it off.","type":"boolean"},"message":{"description":"What the page tells visitors. Plain text; line breaks are kept. Allowed: up to 280 characters.","type":"string"}},"required":["enabled"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api","type":"web","image":"ghcr.io/acme/api:1.4","port":8080,"plan":"starter","status":"live","status_message":"","suspended":false,"url":"https://my-api-x7k2.apps.kilby.neuramorphic.ai","internal_address":"my-api:8080","created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-13T14:05:00Z","registry_credential_id":null,"health_check_path":"/healthz","instances":2,"autoscaling":{"min":2,"max":4,"target_cpu_percent":70},"disk":null,"instances_running":2,"instances_desired":2,"pre_deploy_command":"","pre_deploy_timeout_seconds":600,"source":null,"environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"auto_concurrency":true,"render_compat":false,"stop_first":false,"read_only_root":false,"maintenance":true,"maintenance_message":"We are upgrading the database. Back at 14:00 UTC.","primary_domain":"my-api-x7k2.apps.kilby.neuramorphic.ai","primary_domain_choice":null},"schema":{"$ref":"#/components/schemas/Service"}}},"description":"The service, with `maintenance` and `maintenance_message` as they are now."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is not a web service, or it is being deleted."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: `enabled` is missing, or the message is longer than 280 characters or has control characters."},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: The platform does not show pages of its own yet, so there is nothing to turn on."}},"summary":"Turn maintenance mode on or off","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PUT \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/maintenance\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"enabled\": true,\n  \"message\": \"We are upgrading the database. Back at 14:00 UTC.\"\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/maintenance\", {\n  method: \"PUT\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"enabled\": true,\n    \"message\": \"We are upgrading the database. Back at 14:00 UTC.\"\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.put(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/maintenance\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"enabled\": True,\n        \"message\": \"We are upgrading the database. Back at 14:00 UTC.\"\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"enabled\": true,\n  \"message\": \"We are upgrading the database. Back at 14:00 UTC.\"\n}`)\n\treq, err := http.NewRequest(\"PUT\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/maintenance\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/metrics":{"get":{"description":"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.\n\nCron jobs have no live metrics; their run time is in Read usage.\n\nPermission: `view`.","operationId":"getServiceMetrics","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"How far back to look.","example":"24h","in":"query","name":"range","required":false,"schema":{"default":"1h","enum":["1h","6h","24h","7d"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"range":"24h","from":"2026-11-12T14:10:00Z","to":"2026-11-13T14:10:00Z","step_seconds":300,"metrics_available":true,"points":[{"time":"2026-11-13T14:05:00Z","instances":2,"cpu_used":0.042,"cpu_peak":0.11,"cpu_limit":0.5,"memory_used_mb":182,"memory_peak_mb":190,"memory_limit_mb":512}]},"schema":{"additionalProperties":false,"properties":{"from":{"format":"date-time","type":"string"},"metrics_available":{"description":"false when nothing has been measured yet.","type":"boolean"},"points":{"items":{"$ref":"#/components/schemas/MetricPoint"},"type":"array"},"range":{"type":"string"},"step_seconds":{"description":"The time each point averages.","type":"integer"},"to":{"format":"date-time","type":"string"}},"required":["range","from","to","step_seconds","metrics_available","points"],"type":"object"}}},"description":"The measurements."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: range is not one of the four values, or the service is a cron job."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Read CPU and memory","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics?range=24h\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics?range=24h\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics?range=24h\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics?range=24h\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/services/{id}/metrics/requests":{"get":{"description":"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`).\n\nLatency 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.\n\n`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`.\n\nOnly 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.\n\nPermission: `view`.","operationId":"getServiceRequestMetrics","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"How far back to look.","example":"24h","in":"query","name":"range","required":false,"schema":{"default":"1h","enum":["1h","6h","24h","7d","30d"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"range":"1h","from":"2026-11-14T09:14:00Z","to":"2026-11-14T10:14:00Z","step_seconds":60,"state":"ok","available":true,"summary":{"requests":1840,"status":{"1xx":0,"2xx":1790,"3xx":12,"4xx":30,"5xx":8},"error_rate":0.004348,"requests_per_second_average":0.5111,"requests_per_second_peak":0.9,"latency_ms":{"p50":38.2,"p95":142.5,"p99":610.0,"samples":1840,"min_samples":20,"min_samples_p99":100}},"points":[{"time":"2026-11-14T10:13:00Z","requests":54,"requests_per_second":0.9,"status":{"1xx":0,"2xx":52,"3xx":0,"4xx":1,"5xx":1},"error_rate":0.018519,"latency_ms":{"p50":35.0,"p95":150.0,"p99":480.0,"samples":54,"min_samples":20,"min_samples_p99":100}}]},"schema":{"additionalProperties":false,"properties":{"available":{"description":"false when request metrics are not turned on in this environment.","type":"boolean"},"from":{"format":"date-time","type":"string"},"points":{"items":{"$ref":"#/components/schemas/RequestPoint"},"type":"array"},"range":{"type":"string"},"state":{"description":"Whether Kilby is reading the proxy.","enum":["ok","starting","unavailable","off"],"type":"string"},"step_seconds":{"description":"What one point adds up.","type":"integer"},"summary":{"description":"The whole range in a few numbers. null when not available.","oneOf":[{"additionalProperties":false,"properties":{"error_rate":{"description":"5xx divided by all responses, 0 to 1. null without requests.","type":["number","null"]},"latency_ms":{"additionalProperties":false,"description":"Percentiles of the whole range, in milliseconds.","properties":{"min_samples":{"description":"p50 and p95 are null below this.","type":"integer"},"min_samples_p99":{"description":"p99 is null below this.","type":"integer"},"p50":{"type":["number","null"]},"p95":{"type":["number","null"]},"p99":{"type":["number","null"]},"samples":{"description":"Requests the percentiles are drawn from.","type":"integer"}},"required":["p50","p95","p99","samples","min_samples","min_samples_p99"],"type":"object"},"requests":{"description":"Responses in the range.","type":"integer"},"requests_per_second_average":{"type":"number"},"requests_per_second_peak":{"description":"The busiest point, averaged over its step.","type":"number"},"status":{"additionalProperties":false,"description":"Responses per class.","properties":{"1xx":{"type":"integer"},"2xx":{"type":"integer"},"3xx":{"type":"integer"},"4xx":{"type":"integer"},"5xx":{"type":"integer"}},"required":["1xx","2xx","3xx","4xx","5xx"],"type":"object"}},"required":["requests","status","error_rate","requests_per_second_average","requests_per_second_peak","latency_ms"],"type":"object"},{"type":"null"}]},"to":{"format":"date-time","type":"string"}},"required":["range","from","to","step_seconds","state","available","summary","points"],"type":"object"}}},"description":"The request metrics."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: range is not one of the five values, or the service is not a web service."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Read request metrics","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics/requests?range=24h\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics/requests?range=24h\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics/requests?range=24h\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/metrics/requests?range=24h\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby metrics requests my-api --range 24h"}],"x-kilby-permission":"view"}},"/services/{id}/previews":{"get":{"description":"The service's preview settings, and its previews with their state.\n\nPermission: `view`.","operationId":"getServicePreviews","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"eligible":true,"not_eligible_reason":"","settings":{"enabled":true,"copy_secrets":false,"run_pre_deploy":false,"plan":"starter","variables":["DATABASE_URL"]},"previews":[{"id":"5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350","pull_request":42,"title":"Add the search page","branch":"search-page","commit":"8a2e7d9a74a99a24383b37a774d17ddd931058c0","state":"active","reason":"","service_id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","url":"https://my-api-pr-42-x7k2.apps.kilby.neuramorphic.ai","status":"live","expires_at":"2026-11-13T14:05:00Z","created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z","ended_at":null}],"running":1,"limit":5},"schema":{"additionalProperties":false,"properties":{"eligible":{"description":"The service can have previews: a web service built from a GitHub repository connected to Kilby.","type":"boolean"},"limit":{"description":"How many its plan runs at once: 0 on Hobby, 5 on Pro, 20 on Scale.","type":"integer"},"not_eligible_reason":{"description":"Why not, when eligible is false.","type":"string"},"previews":{"description":"The open previews and the 50 most recent ones in all.","items":{"$ref":"#/components/schemas/Preview"},"type":"array"},"running":{"description":"How many previews the workspace runs now.","type":"integer"},"settings":{"$ref":"#/components/schemas/PreviewSettings"}},"required":["eligible","not_eligible_reason","settings","previews","running","limit"],"type":"object"}}},"description":"The service's preview settings and its previews, open ones first."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The workspace has no service with that id."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a service's previews","tags":["Pull request previews"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"patch":{"description":"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.\n\nPermission: `secrets`.","operationId":"updateServicePreviews","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Turn previews on","value":{"enabled":true}},"example2":{"summary":"Give previews a database","value":{"variables":{"DATABASE_URL":"postgres://preview:secret@staging-db:5432/app"}}}},"schema":{"additionalProperties":false,"properties":{"copy_secrets":{"type":"boolean"},"enabled":{"type":"boolean"},"plan":{"description":"starter, standard or pro.","type":"string"},"run_pre_deploy":{"type":"boolean"},"variables":{"additionalProperties":{"type":"string"},"description":"Variables previews get on top of the copied ones, which win over them.","type":["object","null"]}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"eligible":true,"not_eligible_reason":"","settings":{"enabled":true,"copy_secrets":false,"run_pre_deploy":false,"plan":"starter","variables":["DATABASE_URL"]},"previews":[{"id":"5b2d9f71-0c3e-4a8b-9d16-e4f7a2c8b350","pull_request":42,"title":"Add the search page","branch":"search-page","commit":"8a2e7d9a74a99a24383b37a774d17ddd931058c0","state":"active","reason":"","service_id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","url":"https://my-api-pr-42-x7k2.apps.kilby.neuramorphic.ai","status":"live","expires_at":"2026-11-13T14:05:00Z","created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z","ended_at":null}],"running":1,"limit":5},"schema":{"additionalProperties":false,"properties":{"eligible":{"description":"The service can have previews: a web service built from a GitHub repository connected to Kilby.","type":"boolean"},"limit":{"description":"How many its plan runs at once: 0 on Hobby, 5 on Pro, 20 on Scale.","type":"integer"},"not_eligible_reason":{"description":"Why not, when eligible is false.","type":"string"},"previews":{"description":"The open previews and the 50 most recent ones in all.","items":{"$ref":"#/components/schemas/Preview"},"type":"array"},"running":{"description":"How many previews the workspace runs now.","type":"integer"},"settings":{"$ref":"#/components/schemas/PreviewSettings"}},"required":["eligible","not_eligible_reason","settings","previews","running","limit"],"type":"object"}}},"description":"The service's preview settings and its previews, open ones first."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The workspace has no service with that id."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_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."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Change a service's preview settings","tags":["Pull request previews"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"enabled\": true}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"enabled\": true}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"enabled\": True},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"enabled\": true}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/previews\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"secrets"}},"/services/{id}/primary-domain":{"patch":{"description":"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.\n\nNothing 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.\n\nPermission: `deploy`.","operationId":"setPrimaryDomain","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Make a custom domain primary","value":{"primary_domain":"example.com"}},"example2":{"summary":"Let Kilby choose again","value":{"primary_domain":null}}},"schema":{"additionalProperties":false,"properties":{"primary_domain":{"description":"The Kilby address or a custom domain of the service, or null.","type":["string","null"]}},"required":["primary_domain"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api","type":"web","image":"ghcr.io/acme/api:1.4","port":8080,"plan":"starter","status":"live","status_message":"","suspended":false,"url":"https://my-api-x7k2.apps.kilby.neuramorphic.ai","internal_address":"my-api:8080","created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-13T14:05:00Z","registry_credential_id":null,"health_check_path":"/healthz","instances":2,"autoscaling":{"min":2,"max":4,"target_cpu_percent":70},"disk":null,"instances_running":2,"instances_desired":2,"pre_deploy_command":"","pre_deploy_timeout_seconds":600,"source":null,"environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"auto_concurrency":true,"render_compat":false,"stop_first":false,"read_only_root":false,"maintenance":false,"maintenance_message":"","primary_domain":"example.com","primary_domain_choice":"example.com"},"schema":{"$ref":"#/components/schemas/Service"}}},"description":"The service."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: primary_domain is missing, is not an address of the service, or names a custom domain that is not live; or the service is not a web service."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Choose the primary address","tags":["Domains"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/primary-domain\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"primary_domain\": \"example.com\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/primary-domain\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"primary_domain\": \"example.com\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/primary-domain\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"primary_domain\": \"example.com\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"primary_domain\": \"example.com\"}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/primary-domain\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/resume":{"post":{"description":"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.\n\nPermission: `deploy`.","operationId":"resumeService","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api","type":"web","image":"ghcr.io/acme/api:1.4","port":8080,"plan":"starter","status":"deploying","status_message":"","suspended":false,"url":"https://my-api-x7k2.apps.kilby.neuramorphic.ai","internal_address":"my-api:8080","created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-13T14:05:00Z","registry_credential_id":null,"health_check_path":"/healthz","instances":2,"autoscaling":{"min":2,"max":4,"target_cpu_percent":70},"disk":null,"instances_running":0,"instances_desired":2,"pre_deploy_command":"","pre_deploy_timeout_seconds":600,"source":null,"environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"auto_concurrency":true,"render_compat":false,"stop_first":false,"read_only_root":false,"maintenance":false,"maintenance_message":"","primary_domain":"my-api-x7k2.apps.kilby.neuramorphic.ai","primary_domain_choice":null},"schema":{"$ref":"#/components/schemas/Service"}}},"description":"The service, deploying again."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is not suspended."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: Resuming would exceed a limit of the workspace."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Resume a service","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/resume\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/resume\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/resume\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/resume\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/rollback":{"post":{"description":"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.\n\n`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.\n\nTake the id from List deploys; it must be a deploy that reached `live`. Look at what would change first with Preview a rollback.\n\nPermission: `deploy`.","operationId":"rollbackService","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Roll back, restoring the variables","value":{"deploy_id":"5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d"}},"example2":{"summary":"Roll back and keep the current variables","value":{"deploy_id":"5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d","restore_env":false}}},"schema":{"additionalProperties":false,"properties":{"deploy_id":{"description":"The deploy to restore.","format":"uuid","type":"string"},"restore_env":{"description":"Restore the environment variables of that deploy. false keeps the variables saved now.","type":"boolean"}},"required":["deploy_id"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"example":{"id":"8a0f6c2d-1b4e-4d97-a3c5-6e7f8091a2b3","image":"ghcr.io/acme/api:1.4","trigger":"rollback","status":"queued","message":"","rollback_of":"5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d","created_at":"2026-11-13T14:05:00Z","finished_at":null,"title":"Rollback to 1.4","environment_restored":true},"schema":{"$ref":"#/components/schemas/DeployRecord"}}},"description":"The new deploy, which restores the earlier one."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The service has no such deploy."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The deploy never went live, or the service is suspended."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_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."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Roll back to an earlier deploy","tags":["Deploys and builds"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/rollback\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"deploy_id\": \"5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/rollback\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"deploy_id\": \"5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/rollback\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"deploy_id\": \"5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"deploy_id\": \"5d1e2b7c-3a4f-4b8e-9c0d-1e2f3a4b5c6d\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/rollback\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby rollback my-api"}],"x-kilby-permission":"deploy"}},"/services/{id}/runs":{"get":{"description":"The last 50 runs of a cron job, newest first.\n\nPermission: `view`.","operationId":"listRuns","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"runs":[{"name":"nightly-report-manual-1794524411","status":"succeeded","message":"","manual":true,"started_at":"2026-11-12T22:46:51Z","finished_at":"2026-11-12T22:46:58Z"}]},"schema":{"additionalProperties":false,"properties":{"runs":{"items":{"$ref":"#/components/schemas/Run"},"type":"array"}},"required":["runs"],"type":"object"}}},"description":"The runs."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The service is not a cron job."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List runs","tags":["Cron"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"Runs the cron job once, outside its schedule. While a run is going, a second request answers `409`.\n\nPermission: `deploy`.","operationId":"triggerRun","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"name":"nightly-report-manual-1794524411","status":"running"},"schema":{"additionalProperties":false,"properties":{"name":{"description":"The run's name.","type":"string"},"status":{"description":"Always running.","type":"string"}},"required":["name","status"],"type":"object"}}},"description":"The run has started."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The cron job is suspended, or a run is still in progress."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The service is not a cron job."},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`unavailable`: Runs are not available in this environment."}},"summary":"Start a run now","tags":["Cron"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/runs\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/services/{id}/secret-files":{"get":{"description":"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/\u003cname\u003e` (`path`), read-only. The files are not in the app's working directory.\n\nPermission: `view`.","operationId":"listSecretFiles","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"files":[{"name":".env","path":"/etc/secrets/.env","size":142,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"}],"directory":"/etc/secrets","limits":{"max_file_bytes":131072,"files_per_service":10,"bytes_per_service":786432,"files_per_workspace":100,"bytes_per_workspace":8388608}},"schema":{"additionalProperties":false,"properties":{"directory":{"description":"Where a service finds its files.","type":"string"},"files":{"description":"Each has `name`, `path`, `size` (bytes), `created_at` and `updated_at`.","items":{"type":"object"},"type":"array"},"limits":{"description":"`max_file_bytes`, `files_per_service`, `bytes_per_service`, `files_per_workspace` and `bytes_per_workspace`.","type":"object"}},"required":["files","directory","limits"],"type":"object"}}},"description":"The files, by name. Empty when there are none."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List secret files","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby secret-file list"}],"x-kilby-permission":"view"}},"/services/{id}/secret-files/{name}":{"delete":{"description":"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.\n\nPermission: `secrets`.","operationId":"deleteSecretFile","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"The file's name: a plain file name, not a path. Allowed: letters, digits, dots, underscores and hyphens, 128 characters at most, not made of dots only and not starting with two dots.","example":".env","in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"removed":".env","restarted":true},"schema":{"additionalProperties":false,"properties":{"removed":{"description":"The file's name.","type":"string"},"restarted":{"description":"Whether the service restarts without the file.","type":"boolean"}},"required":["removed","restarted"],"type":"object"}}},"description":"The name that was removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: The service has no such file."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is being deleted."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: Too many changes to secret files in this workspace in a minute."}},"summary":"Delete a secret file","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby secret-file rm"}],"x-kilby-permission":"secrets"},"put":{"description":"Stores the file, encrypted, and makes it available to the service at `/etc/secrets/\u003cname\u003e`, 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.\n\nPermission: `secrets`.","operationId":"putSecretFile","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"The file's name: a plain file name, not a path. Allowed: letters, digits, dots, underscores and hyphens, 128 characters at most, not made of dots only and not starting with two dots.","example":".env","in":"path","name":"name","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"A .env file","value":{"content":"DATABASE_URL=postgres://app:example@db-main-rw:5432/app\nLOG_LEVEL=info\n"}}},"schema":{"additionalProperties":false,"properties":{"content":{"description":"The text of the file. Line breaks are kept as sent. Allowed: 1 byte to 128 KB; up to 10 files and 768 KB per service by default.","type":"string"},"name":{"description":"Optional. When it is sent it must be the name in the path.","type":"string"}},"required":["content"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"file":{"name":".env","path":"/etc/secrets/.env","size":142,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"},"created":false,"changed":true,"restarted":true},"schema":{"additionalProperties":false,"properties":{"changed":{"type":"boolean"},"created":{"description":"false.","type":"boolean"},"file":{"type":"object"},"restarted":{"type":"boolean"}},"required":["file","created","changed","restarted"],"type":"object"}}},"description":"The file existed. `changed` is false when the content was the same."},"201":{"content":{"application/json":{"example":{"file":{"name":".env","path":"/etc/secrets/.env","size":142,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"},"created":true,"changed":true,"restarted":true},"schema":{"additionalProperties":false,"properties":{"changed":{"description":"true.","type":"boolean"},"created":{"description":"true.","type":"boolean"},"file":{"description":"`name`, `path`, `size`, `created_at` and `updated_at`.","type":"object"},"restarted":{"description":"Whether the service restarts to use the file.","type":"boolean"}},"required":["file","created","changed","restarted"],"type":"object"}}},"description":"The file was created."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is being deleted."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`too_large`: The request is larger than 512 KB."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_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."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: Too many changes to secret files in this workspace in a minute (60 by default)."}},"summary":"Add or replace a secret file","tags":["Environment"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PUT \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"content\": \"DATABASE_URL=postgres://app:example@db-main-rw:5432/app\\nLOG_LEVEL=info\\n\"\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env\", {\n  method: \"PUT\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"content\": \"DATABASE_URL=postgres://app:example@db-main-rw:5432/app\\nLOG_LEVEL=info\\n\"\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.put(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"content\": \"DATABASE_URL=postgres://app:example@db-main-rw:5432/app\\nLOG_LEVEL=info\\n\"\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"content\": \"DATABASE_URL=postgres://app:example@db-main-rw:5432/app\\nLOG_LEVEL=info\\n\"\n}`)\n\treq, err := http.NewRequest(\"PUT\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/secret-files/.env\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby secret-file put"}],"x-kilby-permission":"secrets"}},"/services/{id}/suspend":{"post":{"description":"Stops the service and keeps its settings, address and disk. A suspended service costs nothing to run. Cron jobs stop running on their schedule.\n\nPermission: `deploy`.","operationId":"suspendService","parameters":[{"description":"The service's id.","example":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"my-api","type":"web","image":"ghcr.io/acme/api:1.4","port":8080,"plan":"starter","status":"suspended","status_message":"","suspended":false,"url":"https://my-api-x7k2.apps.kilby.neuramorphic.ai","internal_address":"my-api:8080","created_at":"2026-11-12T22:40:11Z","updated_at":"2026-11-13T14:05:00Z","registry_credential_id":null,"health_check_path":"/healthz","instances":2,"autoscaling":{"min":2,"max":4,"target_cpu_percent":70},"disk":null,"instances_running":2,"instances_desired":2,"pre_deploy_command":"","pre_deploy_timeout_seconds":600,"source":null,"environment":{"id":"9a3c5e17-0d48-4b2a-b6f1-7e2d8c1a4053","name":"Production","default":true,"project":{"id":"2b7d9e41-6c0a-4f38-8d15-a3e9c40b7f12","name":"Default"}},"auto_concurrency":true,"render_compat":false,"stop_first":false,"read_only_root":false,"maintenance":false,"maintenance_message":"","primary_domain":"my-api-x7k2.apps.kilby.neuramorphic.ai","primary_domain_choice":null},"schema":{"$ref":"#/components/schemas/Service"}}},"description":"The service, with `suspended` true."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The service is already suspended or is being deleted."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Suspend a service","tags":["Services"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/suspend\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/suspend\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/suspend\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/services/7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea/suspend\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"deploy"}},"/slack-destinations":{"get":{"description":"The workspace's Slack destinations with how each is doing. The webhook URLs are never returned.\n\nPermission: `view`.","operationId":"listSlackDestinations","responses":{"200":{"content":{"application/json":{"example":{"slack_destinations":[{"id":"b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70","name":"deploys","channel":"#deploys","url_hint":"hooks.slack.com/services/T…/B…/****","events":["deploy.failed","cron.run.failed"],"enabled":true,"state":"healthy","state_detail":"The last message got through.","last_delivery":{"status":"succeeded","response_code":200,"at":"2026-11-13T14:05:00Z"},"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"}],"max":5},"schema":{"additionalProperties":false,"properties":{"max":{"type":"integer"},"slack_destinations":{"items":{"$ref":"#/components/schemas/SlackDestination"},"type":"array"}},"required":["slack_destinations","max"],"type":"object"}}},"description":"The destinations, and how many a workspace can have."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List Slack destinations","tags":["Slack"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/slack-destinations\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/slack-destinations\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/slack-destinations\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/slack-destinations\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby slack list"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nNeeds: An admin key, created by an admin or the owner of the workspace.\n\nPermission: `workspace`.","operationId":"createSlackDestination","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Deploys channel","value":{"name":"deploys","channel":"#deploys","url":"https://hooks.slack.com/services/T000/B000/xxxx","events":["deploy.failed","cron.run.failed"]}}},"schema":{"additionalProperties":false,"properties":{"channel":{"description":"A label for you, such as `#deploys`. Display only. Allowed: up to 80 characters.","type":"string"},"events":{"description":"The event types to send. At least one. The list is under Event webhooks.","items":{"type":"string"},"type":"array"},"name":{"description":"A name for the destination. Allowed: up to 60 characters.","type":"string"},"url":{"description":"The incoming webhook URL from Slack. Write-only. Allowed: up to 500 characters.","format":"uri","type":"string"}},"required":["name","url","events"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"id":"b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70","name":"deploys","channel":"#deploys","url_hint":"hooks.slack.com/services/T…/B…/****","events":["deploy.failed","cron.run.failed"],"enabled":true,"state":"untested","state_detail":"Nothing was sent yet.","last_delivery":{"status":"succeeded","response_code":200,"at":"2026-11-13T14:05:00Z"},"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/SlackDestination"}}},"description":"The destination, without its URL."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The workspace already has 5 destinations, or one with that name."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The URL is not a Slack incoming webhook URL, or no event was chosen, or one is not an event type."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 20 destinations were created in the last hour."}},"summary":"Connect a Slack channel","tags":["Slack"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/slack-destinations\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"name\": \"deploys\",\n  \"channel\": \"#deploys\",\n  \"url\": \"https://hooks.slack.com/services/T000/B000/xxxx\",\n  \"events\": [\"deploy.failed\", \"cron.run.failed\"]\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/slack-destinations\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"name\": \"deploys\",\n    \"channel\": \"#deploys\",\n    \"url\": \"https://hooks.slack.com/services/T000/B000/xxxx\",\n    \"events\": [\"deploy.failed\", \"cron.run.failed\"]\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/slack-destinations\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"name\": \"deploys\",\n        \"channel\": \"#deploys\",\n        \"url\": \"https://hooks.slack.com/services/T000/B000/xxxx\",\n        \"events\": [\"deploy.failed\", \"cron.run.failed\"]\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"name\": \"deploys\",\n  \"channel\": \"#deploys\",\n  \"url\": \"https://hooks.slack.com/services/T000/B000/xxxx\",\n  \"events\": [\"deploy.failed\", \"cron.run.failed\"]\n}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/slack-destinations\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby slack add deploys --channel '#deploys' --events deploy.failed,cron.run.failed"}],"x-kilby-permission":"workspace"}},"/slack-destinations/{id}":{"delete":{"description":"Deletes the destination and its history. It receives no more messages. The webhook stays in Slack: remove it there too if you no longer need it.\n\nNeeds: An admin key, created by an admin or the owner of the workspace.\n\nPermission: `workspace`.","operationId":"deleteSlackDestination","parameters":[{"description":"The Slack destination's id.","example":"b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Deleted. There is no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete a Slack destination","tags":["Slack"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status); // 204: nothing to read\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code)  # 204: nothing to read\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby slack rm deploys"}],"x-kilby-permission":"workspace"},"get":{"description":"One destination. Its URL is never returned.\n\nPermission: `view`.","operationId":"getSlackDestination","parameters":[{"description":"The Slack destination's id.","example":"b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70","name":"deploys","channel":"#deploys","url_hint":"hooks.slack.com/services/T…/B…/****","events":["deploy.failed","cron.run.failed"],"enabled":true,"state":"healthy","state_detail":"The last message got through.","last_delivery":{"status":"succeeded","response_code":200,"at":"2026-11-13T14:05:00Z"},"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/SlackDestination"}}},"description":"The destination."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a Slack destination","tags":["Slack"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"patch":{"description":"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.\n\nNeeds: An admin key, created by an admin or the owner of the workspace.\n\nPermission: `workspace`.","operationId":"updateSlackDestination","parameters":[{"description":"The Slack destination's id.","example":"b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Pause a destination","value":{"enabled":false}}},"schema":{"additionalProperties":false,"properties":{"channel":{"description":"A new label. Allowed: up to 80 characters.","type":"string"},"enabled":{"description":"false pauses it; true resumes it.","type":"boolean"},"events":{"description":"The event types to send. At least one. The list is under Event webhooks.","items":{"type":"string"},"type":"array"},"name":{"description":"A new name. Allowed: up to 60 characters.","type":"string"},"url":{"description":"A new incoming webhook URL. Write-only; leave it out to keep the current one.","format":"uri","type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"id":"b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70","name":"deploys","channel":"#deploys","url_hint":"hooks.slack.com/services/T…/B…/****","events":["deploy.failed","cron.run.failed"],"enabled":false,"state":"healthy","state_detail":"The last message got through.","last_delivery":{"status":"succeeded","response_code":200,"at":"2026-11-13T14:05:00Z"},"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/SlackDestination"}}},"description":"The destination after the change."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: Another destination has that name."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A field is not valid."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Change a Slack destination","tags":["Slack"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"enabled\": false}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"enabled\": false}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"enabled\": False},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"enabled\": false}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/slack-destinations/{id}/deliveries":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"listSlackDeliveries","parameters":[{"description":"The Slack destination's id.","example":"b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"deliveries":[{"id":"2e9b4c71-6d3a-4f08-b1c5-8a7e0d9f3c42","event_id":"b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65","event_type":"deploy.failed","status":"succeeded","attempts":1,"response_code":200,"duration_ms":184,"created_at":"2026-11-13T14:05:00Z","last_attempt_at":"2026-11-13T14:05:00Z"}],"max_attempts":4},"schema":{"additionalProperties":false,"properties":{"deliveries":{"items":{"$ref":"#/components/schemas/Delivery"},"type":"array"},"max_attempts":{"description":"How many times one message is tried.","type":"integer"}},"required":["deliveries","max_attempts"],"type":"object"}}},"description":"The deliveries."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List deliveries to a Slack destination","tags":["Slack"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/deliveries\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/deliveries\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/deliveries\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/deliveries\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/slack-destinations/{id}/test":{"post":{"description":"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.\n\nNeeds: An admin key, created by an admin or the owner of the workspace.\n\nPermission: `workspace`.","operationId":"testSlackDestination","parameters":[{"description":"The Slack destination's id.","example":"b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"event_id":"b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65","type":"test"},"schema":{"additionalProperties":false,"properties":{"event_id":{"format":"uuid","type":"string"},"type":{"description":"Always test.","type":"string"}},"required":["event_id","type"],"type":"object"}}},"description":"The test message is queued."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 10 test messages a minute for this destination."}},"summary":"Send a test message","tags":["Slack"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/test\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/test\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/test\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/slack-destinations/b6d1f0a2-7c34-4e59-9a18-3f2e8d5c4b70/test\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby slack test deploys"}],"x-kilby-permission":"workspace"}},"/templates":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"listTemplates","responses":{"200":{"content":{"application/json":{"example":{"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."]}]},"schema":{"additionalProperties":false,"properties":{"templates":{"items":{"$ref":"#/components/schemas/Template"},"type":"array"}},"required":["templates"],"type":"object"}}},"description":"The templates."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List templates","tags":["Templates"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/templates\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/templates\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/templates\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/templates\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby templates list"}],"x-kilby-permission":"view"}},"/templates/{id}":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"getTemplate","parameters":[{"description":"The template's id, from List templates.","example":"open-webui","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"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."]},"schema":{"$ref":"#/components/schemas/Template"}}},"description":"The template."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no template with that id."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a template","tags":["Templates"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/templates/open-webui\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/templates/open-webui\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/templates/open-webui\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/templates/open-webui\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby templates list"}],"x-kilby-permission":"view"}},"/templates/{id}/deploy":{"post":{"description":"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.\n\nKeys, 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.\n\nSend `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.\n\nPermission: `deploy`.","operationId":"deployTemplate","parameters":[{"description":"The template's id, from List templates.","example":"open-webui","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Open WebUI with a chosen name","value":{"name":"team-chat"}},"example2":{"summary":"Two services, both named","value":{"names":{"web":"team-chat","ollama":"team-models"}}},"example3":{"summary":"With a setting","value":{"name":"ai-gateway","inputs":{"OPENAI_API_KEY":"paste-your-key-here"}}}},"schema":{"additionalProperties":false,"properties":{"inputs":{"additionalProperties":{"type":"string"},"description":"Values for the settings the template asks for (its `inputs`), by variable name. Values are stored encrypted.","type":"object"},"name":{"description":"The name of the main service (the first web service of the template, or its first service). Same rules as for a service. Allowed: 3 to 40 characters: lowercase letters, digits and hyphens, starting with a letter. Not starting with db-.","type":"string"},"names":{"additionalProperties":{"type":"string"},"description":"Names by resource key, for a template that creates more than one service.","type":"object"}},"type":"object"}}},"description":"The body is optional: without it the suggested names and default settings are used.","required":false},"responses":{"201":{"content":{"application/json":{"example":{"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."]},"schema":{"additionalProperties":false,"properties":{"after_deploy":{"description":"What to do next, with the names you chose.","items":{"type":"string"},"type":"array"},"primary":{"description":"The service to open first: the template's main one.","format":"uuid","type":"string"},"services":{"description":"Every service that was created, in the order of the template's resources.","items":{"$ref":"#/components/schemas/Service"},"type":"array"},"template":{"description":"The template's id.","type":"string"}},"required":["template","primary","services","after_deploy"],"type":"object"}}},"description":"The services that were created."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`not_found`: There is no template with that id."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The workspace already has a service with one of the names."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_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."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Deploy a template","tags":["Templates"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/templates/open-webui/deploy\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"team-chat\"}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/templates/open-webui/deploy\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"name\": \"team-chat\"}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/templates/open-webui/deploy\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"name\": \"team-chat\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"name\": \"team-chat\"}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/templates/open-webui/deploy\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby templates deploy open-webui --name team-chat --set WEBUI_ADMIN_EMAIL=you@example.com"}],"x-kilby-permission":"deploy"}},"/usage":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"getUsage","parameters":[{"description":"The month, as YYYY-MM. Not in the future.","example":"2026-11","in":"query","name":"month","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"month":"2026-11","from":"2026-11-01T00:00:00Z","to":"2026-12-01T00:00:00Z","totals":{"instance_seconds":3317400,"instance_hours":921.5,"vcpu_hours":460.75,"memory_gb_hours":460.75,"disk_gb_months":2.1,"used_vcpu_hours":31.2,"used_memory_gb_hours":188.4},"resources":[{"id":"7cb800a8-7d0e-49ed-9df2-cb162d9fc2ea","name":"chat-app","type":"service","plan":"starter","deleted":false,"instance_seconds":1105920,"instance_hours":307.2,"vcpu_hours":153.6,"memory_gb_hours":153.6,"disk_gb_months":0,"used_vcpu_hours":18.9,"used_memory_gb_hours":61}]},"schema":{"additionalProperties":false,"properties":{"from":{"format":"date-time","type":"string"},"month":{"type":"string"},"resources":{"items":{"$ref":"#/components/schemas/UsageResource"},"type":"array"},"to":{"format":"date-time","type":"string"},"totals":{"$ref":"#/components/schemas/UsageFigures"}},"required":["month","from","to","totals","resources"],"type":"object"}}},"description":"The month's usage."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: month is not a month in the form YYYY-MM, or is in the future."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Read usage","tags":["Workspaces"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/usage?month=2026-11\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/usage?month=2026-11\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/usage?month=2026-11\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/usage?month=2026-11\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/webhooks":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"listWebhooks","responses":{"200":{"content":{"application/json":{"example":{"webhooks":[{"id":"e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90","url":"https://example.com/kilby-events","description":"On-call","events":["deploy.failed","cron.run.failed"],"enabled":true,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"}]},"schema":{"additionalProperties":false,"properties":{"webhooks":{"items":{"$ref":"#/components/schemas/Webhook"},"type":"array"}},"required":["webhooks"],"type":"object"}}},"description":"The endpoints."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List webhook endpoints","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/webhooks\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/webhooks\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/webhooks\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/webhooks\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"post":{"description":"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.\n\nNeeds: An admin key, created by an admin or the owner of the workspace.\n\nPermission: `workspace`.","operationId":"createWebhook","requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"On-call endpoint","value":{"url":"https://example.com/kilby-events","description":"On-call","events":["deploy.failed","cron.run.failed"]}}},"schema":{"additionalProperties":false,"properties":{"description":{"description":"A note for you. Allowed: up to 100 characters.","type":"string"},"events":{"description":"The event types to send. At least one. The list is under Event webhooks.","items":{"type":"string"},"type":"array"},"url":{"description":"Where to send events. It must be https and point to a public internet address. Allowed: up to 500 characters.","format":"uri","type":"string"}},"required":["url","events"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"id":"e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90","url":"https://example.com/kilby-events","description":"On-call","events":["deploy.failed","cron.run.failed"],"enabled":true,"secret":"whsec_your-signing-secret","created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/Webhook"}}},"description":"The endpoint, with its signing secret."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`conflict`: The workspace already has 5 endpoints."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: The URL is not allowed, or no event was chosen, or one is not an event type."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 20 endpoints were created in the last hour."}},"summary":"Add a webhook endpoint","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/webhooks\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"url\": \"https://example.com/kilby-events\",\n  \"description\": \"On-call\",\n  \"events\": [\"deploy.failed\", \"cron.run.failed\"]\n}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/webhooks\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"url\": \"https://example.com/kilby-events\",\n    \"description\": \"On-call\",\n    \"events\": [\"deploy.failed\", \"cron.run.failed\"]\n  }),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/webhooks\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\n        \"url\": \"https://example.com/kilby-events\",\n        \"description\": \"On-call\",\n        \"events\": [\"deploy.failed\", \"cron.run.failed\"]\n    },\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\n  \"url\": \"https://example.com/kilby-events\",\n  \"description\": \"On-call\",\n  \"events\": [\"deploy.failed\", \"cron.run.failed\"]\n}`)\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/webhooks\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/webhooks/{id}":{"delete":{"description":"Deletes the endpoint. It receives no more events.\n\nNeeds: An admin key, created by an admin or the owner of the workspace.\n\nPermission: `workspace`.","operationId":"deleteWebhook","parameters":[{"description":"The webhook endpoint's id.","example":"e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Deleted. There is no body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Delete a webhook endpoint","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X DELETE \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status); // 204: nothing to read\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.delete(\n    \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code)  # 204: nothing to read\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"},"get":{"description":"One endpoint. The signing secret is never returned here.\n\nPermission: `view`.","operationId":"getWebhook","parameters":[{"description":"The webhook endpoint's id.","example":"e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90","url":"https://example.com/kilby-events","description":"On-call","events":["deploy.failed","cron.run.failed"],"enabled":true,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/Webhook"}}},"description":"The endpoint."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get a webhook endpoint","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"},"patch":{"description":"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.\n\nNeeds: An admin key, created by an admin or the owner of the workspace.\n\nPermission: `workspace`.","operationId":"updateWebhook","parameters":[{"description":"The webhook endpoint's id.","example":"e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"example1":{"summary":"Pause an endpoint","value":{"enabled":false}}},"schema":{"additionalProperties":false,"properties":{"description":{"description":"A new note. Allowed: up to 100 characters.","type":"string"},"enabled":{"description":"false pauses delivery; true resumes it.","type":"boolean"},"events":{"description":"The event types to send. At least one. The list is under Event webhooks.","items":{"type":"string"},"type":"array"},"url":{"description":"A new URL.","format":"uri","type":"string"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"example":{"id":"e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90","url":"https://example.com/kilby-events","description":"On-call","events":["deploy.failed","cron.run.failed"],"enabled":false,"created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/Webhook"}}},"description":"The endpoint after the change."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`invalid_request`: A field is not valid."},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Change a webhook endpoint","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X PATCH \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"enabled\": false}'"},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\"enabled\": false}),\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.patch(\n    \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n    json={\"enabled\": False},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := strings.NewReader(`{\"enabled\": false}`)\n\treq, err := http.NewRequest(\"PATCH\", \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90\", body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/webhooks/{id}/deliveries":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"listDeliveries","parameters":[{"description":"The webhook endpoint's id.","example":"e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"deliveries":[{"id":"2e9b4c71-6d3a-4f08-b1c5-8a7e0d9f3c42","event_id":"b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65","event_type":"deploy.failed","status":"succeeded","attempts":1,"response_code":200,"duration_ms":184,"created_at":"2026-11-13T14:05:00Z","last_attempt_at":"2026-11-13T14:05:00Z"}],"max_attempts":4},"schema":{"additionalProperties":false,"properties":{"deliveries":{"items":{"$ref":"#/components/schemas/Delivery"},"type":"array"},"max_attempts":{"description":"How many times one event is tried.","type":"integer"}},"required":["deliveries","max_attempts"],"type":"object"}}},"description":"The deliveries."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"List deliveries","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/deliveries\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/deliveries\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/deliveries\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/deliveries\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}},"/webhooks/{id}/secret":{"post":{"description":"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.\n\nNeeds: An admin key, created by an admin or the owner of the workspace.\n\nPermission: `workspace`.","operationId":"rollWebhookSecret","parameters":[{"description":"The webhook endpoint's id.","example":"e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"id":"e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90","url":"https://example.com/kilby-events","description":"On-call","events":["deploy.failed","cron.run.failed"],"enabled":true,"secret":"whsec_your-signing-secret","created_at":"2026-11-13T14:05:00Z","updated_at":"2026-11-13T14:05:00Z"},"schema":{"$ref":"#/components/schemas/Webhook"}}},"description":"The endpoint, with the new secret."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Roll the signing secret","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/secret\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/secret\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/secret\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/secret\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/webhooks/{id}/test":{"post":{"description":"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.\n\nNeeds: An admin key, created by an admin or the owner of the workspace.\n\nPermission: `workspace`.","operationId":"testWebhook","parameters":[{"description":"The webhook endpoint's id.","example":"e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"202":{"content":{"application/json":{"example":{"event_id":"b3a9c7e1-4d2f-4a85-8c6e-1f0d9b8a7c65","type":"test"},"schema":{"additionalProperties":false,"properties":{"event_id":{"format":"uuid","type":"string"},"type":{"description":"Always test.","type":"string"}},"required":["event_id","type"],"type":"object"}}},"description":"The test event is queued."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"`rate_limited`: More than 10 test events a minute for this endpoint."}},"summary":"Send a test event","tags":["Webhooks"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl -X POST \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/test\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/test\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.post(\n    \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/test\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"POST\", \"https://onkilby.com/api/v1/webhooks/e7c1a4d2-9b3f-4e58-a6d0-3c8f1b2a7e90/test\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"workspace"}},"/workspace":{"get":{"description":"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.\n\nPermission: `view`.","operationId":"getWorkspace","responses":{"200":{"content":{"application/json":{"example":{"id":"3d6f1c0e-5a9b-4c27-8e41-0b7a92d1f6c3","name":"Acme","plan":"beta","key":{"name":"ci","role":"developer"},"services":3,"cron_jobs":1,"databases":1,"postgres_versions":["17","18"],"limits":{"services":5,"cron_jobs":5,"databases":2,"cpu":2,"memory_gb":4,"database_storage_gb":50,"storage_gb":50}},"schema":{"additionalProperties":false,"properties":{"cron_jobs":{"type":"integer"},"databases":{"type":"integer"},"id":{"format":"uuid","type":"string"},"key":{"additionalProperties":false,"description":"The API key that made this request. Never the key itself.","properties":{"name":{"description":"The name the key was given.","type":"string"},"role":{"description":"What the key can do: `developer` or `viewer`.","type":"string"}},"required":["name","role"],"type":"object"},"limits":{"additionalProperties":false,"properties":{"cpu":{"description":"Cores across all running instances.","type":"number"},"cron_jobs":{"type":"integer"},"database_storage_gb":{"description":"The same as storage_gb. Kept for clients written before service disks.","type":"integer"},"databases":{"type":"integer"},"memory_gb":{"description":"GB across all running instances.","type":"number"},"services":{"description":"Most services and cron jobs together.","type":"integer"},"storage_gb":{"description":"GB of databases and service disks together.","type":"integer"}},"required":["services","cron_jobs","databases","cpu","memory_gb","database_storage_gb","storage_gb"],"type":"object"},"name":{"type":"string"},"plan":{"description":"The workspace's plan: `beta`, `hobby`, `pro`, `scale` or `enterprise`. See Read the plan and the limits.","enum":["beta","hobby","pro","scale","enterprise"],"type":"string"},"postgres_versions":{"description":"The Postgres major versions a new database can be created with, oldest first.","items":{"type":"string"},"type":"array"},"services":{"description":"Services that are not cron jobs.","type":"integer"}},"required":["id","name","key","services","cron_jobs","databases","postgres_versions","limits"],"type":"object"}}},"description":"The workspace."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get the workspace","tags":["Workspaces"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/workspace\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/workspace\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/workspace\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/workspace\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"},{"label":"kilby CLI","lang":"Shell","source":"kilby whoami"}],"x-kilby-permission":"view"}},"/workspace/network":{"get":{"description":"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.\n\n**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.\n\nAn 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.\n\nPermission: `view`.","operationId":"getNetwork","responses":{"200":{"content":{"application/json":{"example":{"outbound_ips":["3.23.67.240"],"shared":true},"schema":{"additionalProperties":false,"properties":{"outbound_ips":{"description":"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.","items":{"type":"string"},"type":"array"},"shared":{"description":"Always `true` today: the addresses are used by every workspace.","type":"boolean"}},"required":["outbound_ips","shared"],"type":"object"}}},"description":"The addresses."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get the outbound IP addresses","tags":["Workspaces"],"x-codeSamples":[{"label":"curl","lang":"Shell","source":"curl \"https://onkilby.com/api/v1/workspace/network\" \\\n  -H \"Authorization: Bearer $KILBY_API_KEY\""},{"label":"JavaScript","lang":"JavaScript","source":"// Node 18 or later, as an ES module (.mjs), or any browser or edge runtime.\nconst res = await fetch(\"https://onkilby.com/api/v1/workspace/network\", {\n  headers: {\n    Authorization: `Bearer ${process.env.KILBY_API_KEY}`,\n  },\n});\nconsole.log(res.status, await res.json());\n"},{"label":"Python","lang":"Python","source":"import os\nimport requests\n\nres = requests.get(\n    \"https://onkilby.com/api/v1/workspace/network\",\n    headers={\"Authorization\": f\"Bearer {os.environ['KILBY_API_KEY']}\"},\n)\nprint(res.status_code, res.json())\n"},{"label":"Go","lang":"Go","source":"package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://onkilby.com/api/v1/workspace/network\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"KILBY_API_KEY\"))\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\tout, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.Status, string(out))\n}\n"}],"x-kilby-permission":"view"}}},"security":[{"bearerAuth":[]}],"servers":[{"description":"Kilby","url":"https://onkilby.com/api/v1"}],"tags":[{"description":"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.","name":"Services"},{"description":"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.","name":"Projects"},{"description":"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.","name":"Deploys and builds"},{"description":"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.","name":"Environment"},{"description":"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.","name":"Environment groups"},{"description":"Managed Postgres with continuous backups. A database is reachable from every service in the same workspace and from nowhere else.","name":"Databases"},{"description":"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`.","name":"Key Value"},{"description":"A cron job is a service of type `cron` with a `schedule`. Create it with Create a service; these endpoints start a run by hand and list the runs.","name":"Cron"},{"description":"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.","name":"Domains"},{"description":"What the key's workspace holds, what it used, and which emails it sends.","name":"Workspaces"},{"description":"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.","name":"API keys"},{"description":"Deploy a repository instead of an image. Kilby connects to GitHub with its own GitHub App, so no token of yours is stored.","name":"GitHub and Git"},{"description":"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.","name":"Blueprints"},{"description":"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.","name":"Billing and pricing"},{"description":"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.","name":"Kilby AI"},{"description":"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.","name":"Templates"},{"description":"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.","name":"Webhooks"},{"description":"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`.","name":"DNS AI"},{"description":"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.","name":"Log streams"},{"description":"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.","name":"Pull request previews"},{"description":"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.","name":"Slack"}],"x-kilby-permissions":{"deploy":"Create, change, deploy, suspend and delete services and databases. Developer keys and above.","none":"No API key needed.","secrets":"Read and change variables, registry credentials and database passwords. Developer keys and above.","view":"Read everything except secret values. Viewer keys and above.","workspace":"Manage webhook endpoints and email notifications. Admin keys, created by an admin or the owner."}}