{ "openapi": "3.1.0", "info": { "title": "Tori public API", "version": "1.0.0", "description": "Customer-facing HTTP API for Tori. Admin, enrollment, zone-agent, and builder endpoints are not part of this document.\n\nAuthenticate with `Authorization: Bearer `. Session tokens from magic-link sign-in start with `tok_`. API tokens from the console or CLI login start with `tori_`. CLI approve/authorize require a session token so an API token cannot mint a child.\n\nInteractive docs at https://docs.tori.host call this origin from the browser. There is no documentation proxy; the token stays in the tab and is not written to localStorage. CORS allows `https://docs.tori.host`, `https://my.tori.host`, and `https://admin.tori.zone`. `/healthz` is included so try-it-out can ping this process.\n\nRate limits send `Retry-After` and `{ \"error\": \"rate_limited\", \"retryAfter\": }` except `POST /api/auth/cli/token`, which sends `slow_down`. They do not send `X-RateLimit-*` headers. Authenticated customer reads allow 600/minute; writes allow 120/minute. Unauthenticated 401s are not counted against an account. Auth and CLI routes use the per-address 15-minute buckets named on each operation.", "license": { "name": "MIT", "identifier": "MIT" } }, "servers": [ { "url": "https://api.tori.host", "description": "Production control plane" } ], "tags": [ { "name": "Meta", "description": "Process identity. Not authenticated." }, { "name": "Auth", "description": "Magic-link sessions and CLI device/loopback sign-in." }, { "name": "Apps", "description": "Customer apps. Deleted apps are omitted from every response." }, { "name": "Deploys", "description": "Static uploads, service images, source builds, rollback, and cancel." }, { "name": "Logs", "description": "Service logs for an app the caller owns." }, { "name": "Domains", "description": "Custom hostnames. Static apps only today." }, { "name": "Environment", "description": "Encrypted env vars; list responses are masked." }, { "name": "Databases", "description": "One managed Postgres per service app." }, { "name": "Account", "description": "Plan and default region for the signed-in user." }, { "name": "Tokens", "description": "Long-lived API tokens. Secrets are shown once." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/account": { "get": { "description": "`plan` and `defaultRegion` are on the account, not on `user`. `user` is id/email/name only. `limits.maxCustomDomains` is the same plan table the add-domain route enforces; nestling is 0.", "operationId": "getAccount", "responses": { "200": { "content": { "application/json": { "example": { "defaultRegion": "eu", "limits": { "database": { "connectionLimit": 5, "maxBytes": 67108864 }, "maxCustomDomains": 0 }, "plan": "nestling", "user": { "email": "you@example.com", "id": "u_1f9a3c2b00", "name": "you" } }, "schema": { "properties": { "defaultRegion": { "enum": [ "eu", "us" ], "type": "string" }, "limits": { "properties": { "database": { "properties": { "connectionLimit": { "type": "number" }, "maxBytes": { "type": "number" } }, "required": [ "connectionLimit", "maxBytes" ], "type": "object" }, "maxCustomDomains": { "type": "number" } }, "required": [ "maxCustomDomains" ], "type": "object" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "user": { "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "email", "name" ], "type": "object" } }, "required": [ "user", "plan", "defaultRegion", "limits" ], "type": "object" } } }, "description": "Account snapshot." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Get the signed-in account", "tags": [ "Account" ] }, "patch": { "description": "Only `defaultRegion` (`eu` or `us`) is writable here. Unknown fields are ignored. A body without a recognised region returns the current account unchanged.", "operationId": "updateAccount", "requestBody": { "content": { "application/json": { "example": { "defaultRegion": "eu" }, "schema": { "properties": { "defaultRegion": { "enum": [ "eu", "us" ], "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "defaultRegion": { "enum": [ "eu", "us" ], "type": "string" }, "limits": { "properties": { "database": { "properties": { "connectionLimit": { "type": "number" }, "maxBytes": { "type": "number" } }, "required": [ "connectionLimit", "maxBytes" ], "type": "object" }, "maxCustomDomains": { "type": "number" } }, "required": [ "maxCustomDomains" ], "type": "object" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "user": { "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "email", "name" ], "type": "object" } }, "required": [ "user", "plan", "defaultRegion", "limits" ], "type": "object" } } }, "description": "Account after the write." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Update account settings", "tags": [ "Account" ] } }, "/api/apps": { "get": { "description": "Return the signed-in account’s apps that have not been deleted. Tombstones exist to hold the slug and to let cleanup resume; they are omitted here and from every other customer route. `kind` is always present on the wire (`static` or `service`). Client libraries that default a missing `kind` to `static` are compensating for older servers, not for this one.", "operationId": "listApps", "responses": { "200": { "content": { "application/json": { "example": [ { "createdAt": "2026-09-18T10:00:00.000Z", "currentDeployId": "d_1f9a3c2b00", "framework": "static", "id": "a_1f9a3c2b00", "kind": "static", "name": "crimson-finch", "region": "eu", "slug": "crimson-finch", "status": "running", "updatedAt": "2026-09-18T10:05:00.000Z", "url": "https://crimson-finch.tori.cloud", "zone": "cz-prg-1" } ], "schema": { "items": { "properties": { "createdAt": { "type": "string" }, "currentDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "framework": { "enum": [ "vite", "next", "astro", "sveltekit", "static" ], "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "static", "service" ], "type": "string" }, "name": { "type": "string" }, "region": { "enum": [ "eu", "us" ], "type": "string" }, "slug": { "type": "string" }, "status": { "enum": [ "running", "napping", "deploying", "error" ], "type": "string" }, "updatedAt": { "type": "string" }, "url": { "type": "string" }, "zone": { "type": "string" } }, "required": [ "id", "slug", "name", "region", "zone", "status", "framework", "kind", "currentDeployId", "url", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" } } }, "description": "JSON array of apps owned by the caller." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List apps", "tags": [ "Apps" ] }, "post": { "description": "Creates an app. Omit `name` to get a generated `adjective-bird` slug. `name` must match `^[a-z0-9-]{1,63}$`. Reserved slugs (`api`, `console`, `admin`, `www`, `tori`, `enroll`, `my`) return 409 `slug taken`. Omit `region` to use the account default. Omit `kind` (or send anything other than `service`) to create a static app — an old client that has never heard of kinds must keep creating static apps. Kind is immutable after create. 403 `app_limit_reached` is not a 429: waiting does not free a slot; delete an app or upgrade. 409 is about the name, including “slug still being reclaimed” for the caller’s own unfinished deletion.", "operationId": "createApp", "requestBody": { "content": { "application/json": { "example": { "kind": "static", "name": "crimson-finch", "region": "eu" }, "schema": { "properties": { "kind": { "enum": [ "static", "service" ], "type": "string" }, "name": { "type": "string" }, "region": { "enum": [ "eu", "us" ], "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "201": { "content": { "application/json": { "example": { "createdAt": "2026-09-18T10:00:00.000Z", "currentDeployId": null, "framework": "static", "id": "a_1f9a3c2b00", "kind": "static", "name": "crimson-finch", "region": "eu", "slug": "crimson-finch", "status": "deploying", "updatedAt": "2026-09-18T10:05:00.000Z", "url": "https://crimson-finch.tori.cloud", "zone": "cz-prg-1" }, "schema": { "properties": { "createdAt": { "type": "string" }, "currentDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "framework": { "enum": [ "vite", "next", "astro", "sveltekit", "static" ], "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "static", "service" ], "type": "string" }, "name": { "type": "string" }, "region": { "enum": [ "eu", "us" ], "type": "string" }, "slug": { "type": "string" }, "status": { "enum": [ "running", "napping", "deploying", "error" ], "type": "string" }, "updatedAt": { "type": "string" }, "url": { "type": "string" }, "zone": { "type": "string" } }, "required": [ "id", "slug", "name", "region", "zone", "status", "framework", "kind", "currentDeployId", "url", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The app. Status starts as `deploying` until a deploy lands." }, "400": { "content": { "application/json": { "example": { "error": "invalid slug" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Name is present but not a valid slug." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "403": { "content": { "application/json": { "example": { "code": "app_limit_reached", "error": "app limit reached: your nestling plan allows 3 apps. Delete one or upgrade.", "limit": 3, "plan": "nestling" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "This plan may not create another app. Not retryable by waiting." }, "409": { "content": { "application/json": { "example": { "error": "slug taken" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The slug is taken, reserved, or still being reclaimed." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Create an app", "tags": [ "Apps" ] } }, "/api/apps/{slug}": { "get": { "description": "404 for unknown slugs, other accounts’ apps, and deleted apps.", "operationId": "getApp", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-09-18T10:00:00.000Z", "currentDeployId": "d_1f9a3c2b00", "framework": "static", "id": "a_1f9a3c2b00", "kind": "static", "name": "crimson-finch", "region": "eu", "slug": "crimson-finch", "status": "running", "updatedAt": "2026-09-18T10:05:00.000Z", "url": "https://crimson-finch.tori.cloud", "zone": "cz-prg-1" }, "schema": { "properties": { "createdAt": { "type": "string" }, "currentDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "framework": { "enum": [ "vite", "next", "astro", "sveltekit", "static" ], "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "static", "service" ], "type": "string" }, "name": { "type": "string" }, "region": { "enum": [ "eu", "us" ], "type": "string" }, "slug": { "type": "string" }, "status": { "enum": [ "running", "napping", "deploying", "error" ], "type": "string" }, "updatedAt": { "type": "string" }, "url": { "type": "string" }, "zone": { "type": "string" } }, "required": [ "id", "slug", "name", "region", "zone", "status", "framework", "kind", "currentDeployId", "url", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The app." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Get one app", "tags": [ "Apps" ] }, "delete": { "description": "Stops serving immediately and hides the app from every customer route. `ok` is about the site; `reclaimed` is housekeeping (artifacts and rows). `reclaimed: false` means cleanup continues in the background — the caller does not retry. The slug is not handed to another account while a tombstone exists.", "operationId": "deleteApp", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ok": true, "reclaimed": true }, "schema": { "properties": { "ok": { "type": "boolean" }, "reclaimed": { "type": "boolean" } }, "required": [ "ok", "reclaimed" ], "type": "object" } } }, "description": "The site is gone." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete an app", "tags": [ "Apps" ] } }, "/api/apps/{slug}/database": { "get": { "description": "One managed Postgres per app. 404 if the app has none. Credentials are never in this response.", "operationId": "getDatabase", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "appId": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "provisioning", "ready", "error", "deleting" ], "type": "string" }, "updatedAt": { "type": "string" }, "zone": { "type": "string" } }, "required": [ "id", "appId", "zone", "status", "message", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "Database status for the owner." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Get the app database", "tags": [ "Databases" ] }, "post": { "description": "Service apps only. A static site cannot connect to a database (400). If a row already exists, returns it (200) rather than creating a second. A `deleting` or not-yet-cleaned `error` row is 409 until the zone finishes. An `error` row whose cleanup completed is retried.", "operationId": "createDatabase", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "appId": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "provisioning", "ready", "error", "deleting" ], "type": "string" }, "updatedAt": { "type": "string" }, "zone": { "type": "string" } }, "required": [ "id", "appId", "zone", "status", "message", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "Existing database row." }, "201": { "content": { "application/json": { "schema": { "properties": { "appId": { "type": "string" }, "createdAt": { "type": "string" }, "id": { "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "provisioning", "ready", "error", "deleting" ], "type": "string" }, "updatedAt": { "type": "string" }, "zone": { "type": "string" } }, "required": [ "id", "appId", "zone", "status", "message", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "Provisioning started." }, "400": { "content": { "application/json": { "example": { "error": "a static site cannot connect to a database; create a service app instead" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Wrong app kind." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "409": { "content": { "application/json": { "example": { "error": "database deletion is still in progress" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "A previous delete or failed create is still running." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a managed database", "tags": [ "Databases" ] }, "delete": { "description": "Marks the database `deleting` and wakes the zone. Idempotent: `pending: false` also covers an app with no database. Repeat deletes still wake the zone.", "operationId": "deleteDatabase", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ok": true, "pending": false }, "schema": { "properties": { "ok": { "const": true, "type": "boolean" }, "pending": { "type": "boolean" } }, "required": [ "ok", "pending" ], "type": "object" } } }, "description": "Deletion accepted or already gone." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete the app database", "tags": [ "Databases" ] } }, "/api/apps/{slug}/database/dumps": { "get": { "description": "Nightly custom-format dumps of this app database, newest first. Owner only. Credentials are never in this response. Another account sees 404.", "operationId": "listDatabaseDumps", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "properties": { "createdAt": { "type": "string" }, "databaseId": { "type": "string" }, "finishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "objectKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "succeeded", "failed" ], "type": "string" } }, "required": [ "id", "databaseId", "status", "objectKey", "message", "createdAt", "finishedAt" ], "type": "object" }, "type": "array" } } }, "description": "Dumps of this database." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List database dumps", "tags": [ "Databases" ] } }, "/api/apps/{slug}/database/dumps/{dumpId}": { "get": { "description": "Owner only. A dumpId that belongs to another app is 404, not 403.", "operationId": "getDatabaseDump", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } }, { "in": "path", "name": "dumpId", "required": true, "schema": { "example": "dmp_1f9a3c2b00", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "createdAt": { "type": "string" }, "databaseId": { "type": "string" }, "finishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "objectKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "succeeded", "failed" ], "type": "string" } }, "required": [ "id", "databaseId", "status", "objectKey", "message", "createdAt", "finishedAt" ], "type": "object" } } }, "description": "The dump." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Get one database dump", "tags": [ "Databases" ] } }, "/api/apps/{slug}/database/restores": { "get": { "description": "Restores of this app database, newest first. Does not print credentials.", "operationId": "listDatabaseRestores", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "properties": { "createdAt": { "type": "string" }, "databaseId": { "type": "string" }, "databaseName": { "type": "string" }, "dumpId": { "type": "string" }, "id": { "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "roleName": { "type": "string" }, "status": { "enum": [ "pending", "ready", "failed" ], "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "databaseId", "dumpId", "status", "message", "databaseName", "roleName", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" } } }, "description": "Restores of this database." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List restores", "tags": [ "Databases" ] }, "post": { "description": "Restores the named dump into a new Postgres database in the same cluster. Never overwrites the live app database and never rewrites DATABASE_URL. Credentials for the restore role use the same SecretRef path as create, and are not returned here.", "operationId": "createDatabaseRestore", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "dumpId": "dmp_1f9a3c2b00" }, "schema": { "properties": { "dumpId": { "type": "string" } }, "required": [ "dumpId" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "createdAt": { "type": "string" }, "databaseId": { "type": "string" }, "databaseName": { "type": "string" }, "dumpId": { "type": "string" }, "id": { "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "roleName": { "type": "string" }, "status": { "enum": [ "pending", "ready", "failed" ], "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "databaseId", "dumpId", "status", "message", "databaseName", "roleName", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "Restore started." }, "400": { "content": { "application/json": { "example": { "error": "dumpId is required" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Body is missing dumpId." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "409": { "content": { "application/json": { "example": { "error": "a restore is already running" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Another restore is still pending, or the dump has not succeeded." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Restore a dump into a separate database", "tags": [ "Databases" ] } }, "/api/apps/{slug}/database/restores/{restoreId}": { "get": { "description": "Owner only. A restoreId that belongs to another app is 404.", "operationId": "getDatabaseRestore", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } }, { "in": "path", "name": "restoreId", "required": true, "schema": { "example": "rst_1f9a3c2b00", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "createdAt": { "type": "string" }, "databaseId": { "type": "string" }, "databaseName": { "type": "string" }, "dumpId": { "type": "string" }, "id": { "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "roleName": { "type": "string" }, "status": { "enum": [ "pending", "ready", "failed" ], "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "databaseId", "dumpId", "status", "message", "databaseName", "roleName", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The restore." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Get restore status", "tags": [ "Databases" ] }, "delete": { "description": "Drops the restore row so a later restore can run. The live app database is not touched. Owner only.", "operationId": "deleteDatabaseRestore", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } }, { "in": "path", "name": "restoreId", "required": true, "schema": { "example": "rst_1f9a3c2b00", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "const": true, "type": "boolean" } }, "required": [ "deleted" ], "type": "object" } } }, "description": "The restore was deleted." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete a restore copy", "tags": [ "Databases" ] } }, "/api/apps/{slug}/deploys": { "get": { "description": "Newest first. A live/superseded service deploy without an image is a server bug and fails the whole list rather than omitting the row. `artifactsReclaimedAt` is always present on the wire (null if files remain). Client defaults that treat a missing field as null are for older servers.", "operationId": "listDeploys", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": [ { "alreadyLive": false, "appId": "a_1f9a3c2b00", "artifactsReclaimedAt": null, "build": null, "buildSeconds": 0, "cancelledAt": null, "commitish": null, "createdAt": "2026-09-18T10:04:00.000Z", "error": null, "id": "d_1f9a3c2b00", "image": null, "progress": "uploading", "progressUpdatedAt": "2026-09-18T10:04:00.000Z", "sizeKb": 240, "source": "cli", "status": "building", "timings": null } ], "schema": { "items": { "properties": { "alreadyLive": { "type": "boolean" }, "appId": { "type": "string" }, "artifactsReclaimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "build": { "anyOf": [ { "properties": { "attempt": { "type": "number" }, "logAvailable": { "type": "boolean" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "queuePosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "leased", "running", "done", "failed", "cancelled" ], "type": "string" } }, "required": [ "state", "queuePosition", "attempt", "provider", "startedAt", "logAvailable" ], "type": "object" }, { "type": "null" } ] }, "buildSeconds": { "type": "number" }, "cancelledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "commitish": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "progress": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "progressUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sizeKb": { "type": "number" }, "source": { "enum": [ "cli", "mcp" ], "type": "string" }, "status": { "enum": [ "live", "superseded", "failed", "building", "cancelled" ], "type": "string" }, "timings": { "anyOf": [ { "properties": { "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentObservedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "containerStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "controlPlaneReceivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "desiredReceivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imagePullStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imagePulledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "podScheduledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revisionReadyAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "routeReadyAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "acceptedAt", "desiredReceivedAt", "podScheduledAt", "imagePullStartedAt", "imagePulledAt", "containerStartedAt", "revisionReadyAt", "routeReadyAt", "agentObservedAt", "controlPlaneReceivedAt" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "id", "appId", "status", "source", "commitish", "sizeKb", "buildSeconds", "error", "progress", "progressUpdatedAt", "cancelledAt", "alreadyLive", "timings", "artifactsReclaimedAt", "image", "build", "createdAt" ], "type": "object" }, "type": "array" } } }, "description": "Deploys of this app." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List deploys", "tags": [ "Deploys" ] }, "post": { "description": "This route opts out of the per-request write budget; concurrency is bounded by the account’s in-flight deploy ceiling and by disk admission, not by counting POSTs.\n\n**Body must match `apps.kind`.** Static apps accept only `multipart/form-data` with a streamed `artifact` part (gzipped tar). Service apps accept `application/json` `{ \"image\": \"@sha256:<64 hex>\" }` or multipart source that queues a build. A JSON body against a static app is 400 `multipart form-data required`; a multipart artifact against a service app is 400 `service deploy body required`. Status is 400 in both cases, not 415 — the media type is not the whole story.\n\n**The artifact is streamed.** The server parses multipart incrementally and spools the file to disk. Do not replace this with a buffering form validator. Conflict (another building deploy on the same app) is decided at the first byte of the artifact so the client can stop sending. `source` defaults to `cli` when omitted; `mcp` is the other allowed value. `commitish` is optional.\n\nA 202 deploy is `building`. 429 with `Retry-After: 30` is the account ceiling (waiting for another deploy to finish is the fix). 503 is this pod’s spool/extraction capacity. 409 is another building deploy on this app.", "operationId": "createDeploy", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "image": "registry.tori.zone/library/web@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "schema": { "properties": { "commitish": { "type": "string" }, "image": { "type": "string" }, "release": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ] }, "restart": { "type": "boolean" }, "source": { "enum": [ "cli", "mcp" ], "type": "string" } }, "required": [ "image" ], "type": "object" } }, "multipart/form-data": { "encoding": { "artifact": { "contentType": "application/gzip, application/octet-stream" } }, "schema": { "properties": { "artifact": { "description": "Gzipped tar of static files, or a source archive for a service build. Streamed; the server does not buffer the whole part.", "format": "binary", "type": "string" }, "commitish": { "type": "string" }, "release": { "description": "Release-phase command run as a Job before the new revision takes traffic. A JSON array of argv, or a whitespace-separated string. Also accepted on the JSON body as a string or string array.", "type": "string" }, "source": { "enum": [ "cli", "mcp" ], "type": "string" } }, "required": [ "artifact" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "alreadyLive": true, "appId": "a_1f9a3c2b00", "artifactsReclaimedAt": null, "build": null, "buildSeconds": 0, "cancelledAt": null, "commitish": null, "createdAt": "2026-09-18T10:04:00.000Z", "error": null, "id": "d_1f9a3c2b00", "image": null, "progress": "uploading", "progressUpdatedAt": "2026-09-18T10:04:00.000Z", "sizeKb": 240, "source": "cli", "status": "live", "timings": null }, "schema": { "properties": { "alreadyLive": { "type": "boolean" }, "appId": { "type": "string" }, "artifactsReclaimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "build": { "anyOf": [ { "properties": { "attempt": { "type": "number" }, "logAvailable": { "type": "boolean" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "queuePosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "leased", "running", "done", "failed", "cancelled" ], "type": "string" } }, "required": [ "state", "queuePosition", "attempt", "provider", "startedAt", "logAvailable" ], "type": "object" }, { "type": "null" } ] }, "buildSeconds": { "type": "number" }, "cancelledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "commitish": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "progress": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "progressUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sizeKb": { "type": "number" }, "source": { "enum": [ "cli", "mcp" ], "type": "string" }, "status": { "enum": [ "live", "superseded", "failed", "building", "cancelled" ], "type": "string" }, "timings": { "anyOf": [ { "properties": { "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentObservedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "containerStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "controlPlaneReceivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "desiredReceivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imagePullStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imagePulledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "podScheduledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revisionReadyAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "routeReadyAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "acceptedAt", "desiredReceivedAt", "podScheduledAt", "imagePullStartedAt", "imagePulledAt", "containerStartedAt", "revisionReadyAt", "routeReadyAt", "agentObservedAt", "controlPlaneReceivedAt" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "id", "appId", "status", "source", "commitish", "sizeKb", "buildSeconds", "error", "progress", "progressUpdatedAt", "cancelledAt", "alreadyLive", "timings", "artifactsReclaimedAt", "image", "build", "createdAt" ], "type": "object" } } }, "description": "Service image deploy that is already the live revision (`alreadyLive: true`)." }, "202": { "content": { "application/json": { "example": { "alreadyLive": false, "appId": "a_1f9a3c2b00", "artifactsReclaimedAt": null, "build": null, "buildSeconds": 0, "cancelledAt": null, "commitish": null, "createdAt": "2026-09-18T10:04:00.000Z", "error": null, "id": "d_1f9a3c2b00", "image": null, "progress": "uploading", "progressUpdatedAt": "2026-09-18T10:04:00.000Z", "sizeKb": 240, "source": "cli", "status": "building", "timings": null }, "schema": { "properties": { "alreadyLive": { "type": "boolean" }, "appId": { "type": "string" }, "artifactsReclaimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "build": { "anyOf": [ { "properties": { "attempt": { "type": "number" }, "logAvailable": { "type": "boolean" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "queuePosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "leased", "running", "done", "failed", "cancelled" ], "type": "string" } }, "required": [ "state", "queuePosition", "attempt", "provider", "startedAt", "logAvailable" ], "type": "object" }, { "type": "null" } ] }, "buildSeconds": { "type": "number" }, "cancelledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "commitish": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "progress": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "progressUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sizeKb": { "type": "number" }, "source": { "enum": [ "cli", "mcp" ], "type": "string" }, "status": { "enum": [ "live", "superseded", "failed", "building", "cancelled" ], "type": "string" }, "timings": { "anyOf": [ { "properties": { "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentObservedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "containerStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "controlPlaneReceivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "desiredReceivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imagePullStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imagePulledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "podScheduledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revisionReadyAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "routeReadyAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "acceptedAt", "desiredReceivedAt", "podScheduledAt", "imagePullStartedAt", "imagePulledAt", "containerStartedAt", "revisionReadyAt", "routeReadyAt", "agentObservedAt", "controlPlaneReceivedAt" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "id", "appId", "status", "source", "commitish", "sizeKb", "buildSeconds", "error", "progress", "progressUpdatedAt", "cancelledAt", "alreadyLive", "timings", "artifactsReclaimedAt", "image", "build", "createdAt" ], "type": "object" } } }, "description": "Deploy accepted and `building`." }, "400": { "content": { "application/json": { "example": { "error": "multipart form-data required" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Wrong body for this app kind, missing artifact, or unreadable multipart." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "409": { "content": { "application/json": { "example": { "code": "DEPLOY_IN_PROGRESS", "error": "deploy already in progress" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "This app already has a building deploy." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 30 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Account concurrent-deploy ceiling. Retry-After is 30 seconds.", "headers": { "Retry-After": { "schema": { "example": 30, "type": "integer" } } } }, "503": { "content": { "application/json": { "example": { "error": "deploy capacity reached" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "This pod has no spool or extraction room. Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a deploy", "tags": [ "Deploys" ] } }, "/api/apps/{slug}/deploys/{deployId}": { "get": { "description": "Scoped to the app. Unknown deploy IDs are 404 `deploy not found`.", "operationId": "getDeploy", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } }, { "in": "path", "name": "deployId", "required": true, "schema": { "example": "d_1f9a3c2b00", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "alreadyLive": false, "appId": "a_1f9a3c2b00", "artifactsReclaimedAt": null, "build": null, "buildSeconds": 0, "cancelledAt": null, "commitish": null, "createdAt": "2026-09-18T10:04:00.000Z", "error": null, "id": "d_1f9a3c2b00", "image": null, "progress": "uploading", "progressUpdatedAt": "2026-09-18T10:04:00.000Z", "sizeKb": 240, "source": "cli", "status": "building", "timings": null }, "schema": { "properties": { "alreadyLive": { "type": "boolean" }, "appId": { "type": "string" }, "artifactsReclaimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "build": { "anyOf": [ { "properties": { "attempt": { "type": "number" }, "logAvailable": { "type": "boolean" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "queuePosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "leased", "running", "done", "failed", "cancelled" ], "type": "string" } }, "required": [ "state", "queuePosition", "attempt", "provider", "startedAt", "logAvailable" ], "type": "object" }, { "type": "null" } ] }, "buildSeconds": { "type": "number" }, "cancelledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "commitish": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "progress": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "progressUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sizeKb": { "type": "number" }, "source": { "enum": [ "cli", "mcp" ], "type": "string" }, "status": { "enum": [ "live", "superseded", "failed", "building", "cancelled" ], "type": "string" }, "timings": { "anyOf": [ { "properties": { "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentObservedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "containerStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "controlPlaneReceivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "desiredReceivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imagePullStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imagePulledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "podScheduledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revisionReadyAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "routeReadyAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "acceptedAt", "desiredReceivedAt", "podScheduledAt", "imagePullStartedAt", "imagePulledAt", "containerStartedAt", "revisionReadyAt", "routeReadyAt", "agentObservedAt", "controlPlaneReceivedAt" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "id", "appId", "status", "source", "commitish", "sizeKb", "buildSeconds", "error", "progress", "progressUpdatedAt", "cancelledAt", "alreadyLive", "timings", "artifactsReclaimedAt", "image", "build", "createdAt" ], "type": "object" } } }, "description": "The deploy." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Get one deploy", "tags": [ "Deploys" ] } }, "/api/apps/{slug}/deploys/{deployId}/build-log": { "get": { "description": "Raw text, not JSON, up to a few MiB of whatever the builder printed. One 404 covers “no such deploy”, “no source build”, and “log not stored” — `build.logAvailable` on the deploy is where the difference is told. `Content-Type` is the build-log type the server stored.", "operationId": "getBuildLog", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } }, { "in": "path", "name": "deployId", "required": true, "schema": { "example": "d_1f9a3c2b00", "type": "string" } } ], "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Build log bytes." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "build log not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "No log to fetch." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Fetch a source-build log", "tags": [ "Deploys" ] } }, "/api/apps/{slug}/deploys/{deployId}/cancel": { "post": { "description": "Service apps only. Static deploys cannot be cancelled (400). Only a `building` deploy that is not the live pointer can be cancelled. A builder that already holds a VM is asked to stop; the deploy may stay `building` until it does.", "operationId": "cancelDeploy", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } }, { "in": "path", "name": "deployId", "required": true, "schema": { "example": "d_1f9a3c2b00", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "alreadyLive": { "type": "boolean" }, "appId": { "type": "string" }, "artifactsReclaimedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "build": { "anyOf": [ { "properties": { "attempt": { "type": "number" }, "logAvailable": { "type": "boolean" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "queuePosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "leased", "running", "done", "failed", "cancelled" ], "type": "string" } }, "required": [ "state", "queuePosition", "attempt", "provider", "startedAt", "logAvailable" ], "type": "object" }, { "type": "null" } ] }, "buildSeconds": { "type": "number" }, "cancelledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "commitish": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "progress": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "progressUpdatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sizeKb": { "type": "number" }, "source": { "enum": [ "cli", "mcp" ], "type": "string" }, "status": { "enum": [ "live", "superseded", "failed", "building", "cancelled" ], "type": "string" }, "timings": { "anyOf": [ { "properties": { "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentObservedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "containerStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "controlPlaneReceivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "desiredReceivedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imagePullStartedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imagePulledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "podScheduledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revisionReadyAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "routeReadyAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "acceptedAt", "desiredReceivedAt", "podScheduledAt", "imagePullStartedAt", "imagePulledAt", "containerStartedAt", "revisionReadyAt", "routeReadyAt", "agentObservedAt", "controlPlaneReceivedAt" ], "type": "object" }, { "type": "null" } ] } }, "required": [ "id", "appId", "status", "source", "commitish", "sizeKb", "buildSeconds", "error", "progress", "progressUpdatedAt", "cancelledAt", "alreadyLive", "timings", "artifactsReclaimedAt", "image", "build", "createdAt" ], "type": "object" } } }, "description": "Current deploy row after the cancel request." }, "400": { "content": { "application/json": { "example": { "error": "Only service deployments can be cancelled." }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Wrong kind, or the deploy is not cancellable." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "409": { "content": { "application/json": { "example": { "error": "Deploy d_x is live; only an in-progress deployment can be cancelled." }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Not building, or it is the live pointer." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Cancel an in-progress service deploy", "tags": [ "Deploys" ] } }, "/api/apps/{slug}/deploys/{deployId}/events": { "get": { "description": "Server-sent events. Each `deploy` event’s `data` is the same JSON as `getDeploy`. The stream ends when the deploy leaves `building` or the app disappears. Too many open streams for this account is 429 with `Retry-After: 1`. `Cache-Control` is `no-cache, no-transform`; `X-Accel-Buffering: no` so proxies do not hold events.", "operationId": "watchDeploy", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } }, { "in": "path", "name": "deployId", "required": true, "schema": { "example": "d_1f9a3c2b00", "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "example": "event: deploy\ndata: {\"id\":\"d_1f9a3c2b00\",\"status\":\"building\"}\n\n", "type": "string" } } }, "description": "text/event-stream of deploy snapshots." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "deploy not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Deploy not found." }, "429": { "content": { "application/json": { "example": { "error": "too many open deploy event streams" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many open deploy event streams.", "headers": { "Retry-After": { "schema": { "example": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Watch a deploy (SSE)", "tags": [ "Deploys" ] } }, "/api/apps/{slug}/domains": { "get": { "description": "Hostnames attached to this app. Platform hostname `.tori.cloud` is not in this list. `expected` is the record to create: `CNAME` to the app’s own name, or `A` to the zone ingress addresses when the hostname has exactly two labels.", "operationId": "listDomains", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": [ { "appId": "a_1f9a3c2b00", "certificate": { "message": null, "notAfter": null, "reportedAt": null, "state": null }, "createdAt": "2026-09-18T10:00:00.000Z", "dns": { "checkedAt": null, "observed": null, "ok": null }, "expected": { "type": "CNAME", "value": "crimson-finch.tori.cloud" }, "failedReason": null, "hostname": "www.example.com", "id": "dom_1f9a3c2b00", "retryAfter": null, "status": "pending-dns" } ], "schema": { "items": { "properties": { "appId": { "type": "string" }, "certificate": { "properties": { "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notAfter": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reportedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "enum": [ "issuing", "ready", "failed" ], "type": "string" }, { "type": "null" } ] } }, "required": [ "state", "notAfter", "message", "reportedAt" ], "type": "object" }, "createdAt": { "type": "string" }, "dns": { "properties": { "checkedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "observed": { "anyOf": [ { "properties": { "a": { "items": { "type": "string" }, "type": "array" }, "aaaa": { "items": { "type": "string" }, "type": "array" }, "caa": { "items": { "type": "string" }, "type": "array" }, "cname": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "problem": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "a", "aaaa", "cname", "caa", "problem" ], "type": "object" }, { "type": "null" } ] }, "ok": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "checkedAt", "ok", "observed" ], "type": "object" }, "expected": { "properties": { "type": { "enum": [ "A", "CNAME" ], "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "failedReason": { "anyOf": [ { "enum": [ "dns-drift", "issuance" ], "type": "string" }, { "type": "null" } ] }, "hostname": { "type": "string" }, "id": { "type": "string" }, "retryAfter": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending-dns", "verified", "issuing", "active", "failed" ], "type": "string" } }, "required": [ "id", "appId", "hostname", "status", "expected", "dns", "certificate", "failedReason", "retryAfter", "createdAt" ], "type": "object" }, "type": "array" } } }, "description": "Domains of this app." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List custom domains", "tags": [ "Domains" ] }, "post": { "description": "Static apps only. Counted across every app the owner has, whatever the row’s status: a `pending-dns` name holds the hostname platform-wide. 400 `invalid hostname` carries `reason` (`empty`, `wildcard`, `ip-literal`, `not-convertible`, `too-long`, `label-too-long`, `label-chars`, `too-few-labels`, `reserved`) and `message`. 403 `domain_limit_reached` is the plan cap (nestling is 0). 409 `hostname taken` is the platform-wide unique index. Service apps return 409 `custom domains are not available for service apps` — a custom hostname needs a zone DomainMapping that does not exist yet, and accepting the row would reserve the name forever as `pending-dns`.", "operationId": "addDomain", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "hostname": "www.example.com" }, "schema": { "properties": { "hostname": { "type": "string" } }, "required": [ "hostname" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "appId": "a_1f9a3c2b00", "certificate": { "message": null, "notAfter": null, "reportedAt": null, "state": null }, "createdAt": "2026-09-18T10:00:00.000Z", "dns": { "checkedAt": null, "observed": null, "ok": null }, "expected": { "type": "CNAME", "value": "crimson-finch.tori.cloud" }, "failedReason": null, "hostname": "www.example.com", "id": "dom_1f9a3c2b00", "retryAfter": null, "status": "pending-dns" }, "schema": { "properties": { "appId": { "type": "string" }, "certificate": { "properties": { "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notAfter": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reportedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "enum": [ "issuing", "ready", "failed" ], "type": "string" }, { "type": "null" } ] } }, "required": [ "state", "notAfter", "message", "reportedAt" ], "type": "object" }, "createdAt": { "type": "string" }, "dns": { "properties": { "checkedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "observed": { "anyOf": [ { "properties": { "a": { "items": { "type": "string" }, "type": "array" }, "aaaa": { "items": { "type": "string" }, "type": "array" }, "caa": { "items": { "type": "string" }, "type": "array" }, "cname": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "problem": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "a", "aaaa", "cname", "caa", "problem" ], "type": "object" }, { "type": "null" } ] }, "ok": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "checkedAt", "ok", "observed" ], "type": "object" }, "expected": { "properties": { "type": { "enum": [ "A", "CNAME" ], "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "failedReason": { "anyOf": [ { "enum": [ "dns-drift", "issuance" ], "type": "string" }, { "type": "null" } ] }, "hostname": { "type": "string" }, "id": { "type": "string" }, "retryAfter": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending-dns", "verified", "issuing", "active", "failed" ], "type": "string" } }, "required": [ "id", "appId", "hostname", "status", "expected", "dns", "certificate", "failedReason", "retryAfter", "createdAt" ], "type": "object" } } }, "description": "Reserved; DNS is still pending." }, "400": { "content": { "application/json": { "example": { "error": "invalid hostname", "message": "that name is under a domain the platform owns", "reason": "reserved" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unusable name. `reason` is one of the hostname rejection codes; `message` is the matching sentence." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "403": { "content": { "application/json": { "example": { "code": "domain_limit_reached", "error": "custom domains are not included in the nestling plan. Upgrade to add one.", "limit": 0, "plan": "nestling" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "This account already holds `limit` custom domains, or the plan includes none. Waiting does not help." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "409": { "content": { "application/json": { "example": { "error": "hostname taken" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "That hostname is already reserved, or the app is a service (`error` is then `custom domains are not available for service apps` with a `message`)." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Add a custom domain", "tags": [ "Domains" ] } }, "/api/apps/{slug}/domains/{domainId}": { "delete": { "description": "Idempotent. Unknown domain IDs still return `{ ok: true }`.", "operationId": "removeDomain", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } }, { "in": "path", "name": "domainId", "required": true, "schema": { "example": "dom_1f9a3c2b00", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Gone, or it was not there." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Remove a custom domain", "tags": [ "Domains" ] } }, "/api/apps/{slug}/domains/{domainId}/verify": { "post": { "description": "Writes `dns_check_after = now` and, when this process has a resolver, runs the DNS check inline so the response carries the verdict. Does not shorten a `failed` row’s Let’s Encrypt hour: that check is scheduled for `retry_after`. At most one check per domain per 30 s; a second call returns 429 with `Retry-After` and `retryAfterSeconds`. A check already running (another verify or the sweeper) is also 429, with `error: \"dns check already running\"`. Without a resolver the row is only rescheduled. Distinct from the account-wide 429 (`error: rate_limited`).", "operationId": "verifyDomain", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } }, { "in": "path", "name": "domainId", "required": true, "schema": { "example": "dom_1f9a3c2b00", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "appId": "a_1f9a3c2b00", "certificate": { "message": null, "notAfter": null, "reportedAt": null, "state": null }, "createdAt": "2026-09-18T10:00:00.000Z", "dns": { "checkedAt": null, "observed": null, "ok": null }, "expected": { "type": "CNAME", "value": "crimson-finch.tori.cloud" }, "failedReason": null, "hostname": "www.example.com", "id": "dom_1f9a3c2b00", "retryAfter": null, "status": "pending-dns" }, "schema": { "properties": { "appId": { "type": "string" }, "certificate": { "properties": { "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notAfter": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reportedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "enum": [ "issuing", "ready", "failed" ], "type": "string" }, { "type": "null" } ] } }, "required": [ "state", "notAfter", "message", "reportedAt" ], "type": "object" }, "createdAt": { "type": "string" }, "dns": { "properties": { "checkedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "observed": { "anyOf": [ { "properties": { "a": { "items": { "type": "string" }, "type": "array" }, "aaaa": { "items": { "type": "string" }, "type": "array" }, "caa": { "items": { "type": "string" }, "type": "array" }, "cname": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "problem": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "a", "aaaa", "cname", "caa", "problem" ], "type": "object" }, { "type": "null" } ] }, "ok": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "checkedAt", "ok", "observed" ], "type": "object" }, "expected": { "properties": { "type": { "enum": [ "A", "CNAME" ], "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "failedReason": { "anyOf": [ { "enum": [ "dns-drift", "issuance" ], "type": "string" }, { "type": "null" } ] }, "hostname": { "type": "string" }, "id": { "type": "string" }, "retryAfter": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending-dns", "verified", "issuing", "active", "failed" ], "type": "string" } }, "required": [ "id", "appId", "hostname", "status", "expected", "dns", "certificate", "failedReason", "retryAfter", "createdAt" ], "type": "object" } } }, "description": "The domain after scheduling or after the inline check. A still-pending row means the check is running past the 8 s inline timeout and will write when it lands." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "domain not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "No such domain on this app, or the app is gone." }, "429": { "content": { "application/json": { "example": { "error": "dns check rate limited", "message": "this domain was checked 3 s ago; try again in 27 s", "retryAfterSeconds": 27 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "This domain was checked less than 30 s ago, or another check of it is already running. Header `Retry-After` is whole seconds. Body uses `retryAfterSeconds`, not the account-wide `retryAfter`. Account-wide 429 still uses `{ \"error\": \"rate_limited\", \"retryAfter\": }`.", "headers": { "Retry-After": { "description": "Whole seconds until another check of this domain is allowed.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Check a custom domain now", "tags": [ "Domains" ] } }, "/api/apps/{slug}/env": { "get": { "description": "Values are masked. 503 if this process cannot open the secret box (`REGISTRY_SECRET_KEY` missing or unreadable). The API never returns plaintext values after create/update of a different key.", "operationId": "listEnvVars", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "properties": { "appId": { "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" }, "updatedAt": { "type": "string" }, "valueMasked": { "type": "string" } }, "required": [ "id", "appId", "key", "valueMasked", "updatedAt" ], "type": "object" }, "type": "array" } } }, "description": "Masked env vars." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } }, "503": { "content": { "application/json": { "example": { "error": "environment encryption is unavailable" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Secret box is not available on this process." } }, "security": [ { "bearerAuth": [] } ], "summary": "List environment variables", "tags": [ "Environment" ] }, "put": { "description": "`key` must match `^[A-Z][A-Z0-9_]*$`. Value is any string, stored encrypted. 201 when this request created the row; 200 when it updated an existing key. Two concurrent PUTs of the same key become one row. The JSON response includes a masked value, not the secret you just sent, except the update path returns the value the handler still holds in memory as `valueMasked`.", "operationId": "setEnvVar", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "key": "DATABASE_URL", "value": "postgres://…" }, "schema": { "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "appId": { "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" }, "updatedAt": { "type": "string" }, "valueMasked": { "type": "string" } }, "required": [ "id", "appId", "key", "valueMasked", "updatedAt" ], "type": "object" } } }, "description": "Updated existing key." }, "201": { "content": { "application/json": { "schema": { "properties": { "appId": { "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" }, "updatedAt": { "type": "string" }, "valueMasked": { "type": "string" } }, "required": [ "id", "appId", "key", "valueMasked", "updatedAt" ], "type": "object" } } }, "description": "Created the key." }, "400": { "content": { "application/json": { "example": { "error": "invalid key or value" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Key missing/malformed, or value not a string." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } }, "503": { "content": { "application/json": { "example": { "error": "environment encryption is unavailable" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Cannot seal the value." } }, "security": [ { "bearerAuth": [] } ], "summary": "Set an environment variable", "tags": [ "Environment" ] } }, "/api/apps/{slug}/env/{envId}": { "delete": { "description": "Idempotent. Unknown IDs still return `{ ok: true }`.", "operationId": "removeEnvVar", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } }, { "in": "path", "name": "envId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "Gone, or it was not there." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete an environment variable", "tags": [ "Environment" ] } }, "/api/apps/{slug}/logs": { "get": { "description": "Service logs for this app. Query params: `start`, `end` (RFC 3339), `limit` (1–500, default 200), or `cursor` alone. `cursor` is exclusive of the other params. Maximum range is 24 hours; older than retention is 410. Default range is the last 15 minutes ending now. Cache-Control is `no-store`. Per-process: two in-flight queries per user, eight total; extra queries are 429 with Retry-After 3 and `code: logs_throttled`. Ownership is re-checked after the store returns so a revoked token cannot collect a result that was already in flight.", "operationId": "listLogs", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } }, { "in": "query", "name": "start", "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "end", "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Opaque; do not combine with start/end/limit.", "in": "query", "name": "cursor", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "entries": { "items": { "properties": { "id": { "type": "string" }, "message": { "type": "string" }, "pod": { "type": "string" }, "revision": { "type": "string" }, "stream": { "enum": [ "stdout", "stderr" ], "type": "string" }, "time": { "type": "string" } }, "required": [ "id", "time", "message", "stream" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "range": { "properties": { "end": { "type": "string" }, "start": { "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "retentionDays": { "type": "number" } }, "required": [ "entries", "nextCursor", "range", "retentionDays" ], "type": "object" } } }, "description": "A page of log entries. `nextCursor` is null on the last page." }, "400": { "content": { "application/json": { "example": { "code": "logs_invalid_query", "error": "invalid log range or cursor (maximum range: 24 hours)" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Bad range, extra query keys, or a broken cursor." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "403": { "content": { "application/json": { "example": { "error": "forbidden" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The app exists but is not this account’s." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "410": { "content": { "application/json": { "example": { "code": "logs_retention_expired", "error": "requested logs are outside retention" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Start is older than retentionDays." }, "422": { "content": { "application/json": { "example": { "code": "logs_window_too_large", "error": "narrow the log time range" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Offset walked past 10 000 lines; shrink the window." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } }, "503": { "content": { "application/json": { "example": { "code": "logs_unavailable", "error": "log storage is unavailable" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Tenant log store is not configured on this process." } }, "security": [ { "bearerAuth": [] } ], "summary": "Query app logs", "tags": [ "Logs" ] } }, "/api/apps/{slug}/rollback": { "post": { "description": "Body `{ \"deployId\" }`. The target must be `live` or `superseded` and must still have its files (`artifactsReclaimedAt` null). Static rollback moves the pointer in one transaction. Service rollback starts a new rollout and does not move the pointer here. 400 if the files are gone or the deploy is not rollbackable.", "operationId": "rollbackApp", "parameters": [ { "description": "App slug. Lowercase letters, digits, and hyphens; 1–63 characters. Reserved names such as `api` and `www` are refused on create.", "in": "path", "name": "slug", "required": true, "schema": { "example": "crimson-finch", "pattern": "^[a-z0-9-]{1,63}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "deployId": "d_1f9a3c2b00" }, "schema": { "properties": { "deployId": { "type": "string" } }, "required": [ "deployId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-09-18T10:00:00.000Z", "currentDeployId": "d_1f9a3c2b00", "framework": "static", "id": "a_1f9a3c2b00", "kind": "static", "name": "crimson-finch", "region": "eu", "slug": "crimson-finch", "status": "running", "updatedAt": "2026-09-18T10:05:00.000Z", "url": "https://crimson-finch.tori.cloud", "zone": "cz-prg-1" }, "schema": { "properties": { "createdAt": { "type": "string" }, "currentDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "framework": { "enum": [ "vite", "next", "astro", "sveltekit", "static" ], "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "static", "service" ], "type": "string" }, "name": { "type": "string" }, "region": { "enum": [ "eu", "us" ], "type": "string" }, "slug": { "type": "string" }, "status": { "enum": [ "running", "napping", "deploying", "error" ], "type": "string" }, "updatedAt": { "type": "string" }, "url": { "type": "string" }, "zone": { "type": "string" } }, "required": [ "id", "slug", "name", "region", "zone", "status", "framework", "kind", "currentDeployId", "url", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The app, now pointing at the target (static) or deploying (service)." }, "400": { "content": { "application/json": { "example": { "error": "deploy not rollbackable" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Wrong status, or files have been reclaimed." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Roll back to a previous deploy", "tags": [ "Deploys" ] } }, "/api/auth/callback": { "get": { "description": "Exchanges the one-time `token` query parameter for a session. The row is deleted in the same statement that validates it, so two concurrent redemptions cannot both mint a session. Creates the account on first use (`nestling` plan, default region `eu`).", "operationId": "redeemMagicLink", "parameters": [ { "description": "Raw token from the magic link. Not the session token.", "in": "query", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "token": "tok_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "user": { "email": "you@example.com", "id": "u_1f9a3c2b00", "name": "you" } }, "schema": { "properties": { "token": { "type": "string" }, "user": { "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "email", "name" ], "type": "object" } }, "required": [ "token", "user" ], "type": "object" } } }, "description": "Session token and user. Store `token` as `Authorization: Bearer`." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The `token` query parameter is unknown, expired, or already redeemed. This route does not read `Authorization`." } }, "security": [], "summary": "Redeem a magic-link token", "tags": [ "Auth" ] } }, "/api/auth/cli/approve": { "post": { "description": "Console only; session token required. Claims the pending row for this account. A guessed code signs **the victim CLI** into the guesser’s account, which is why this route is rate-limited (20/user, 60/address per 15 minutes) and why the claim is a single UPDATE.", "operationId": "approveCliDevice", "requestBody": { "content": { "application/json": { "example": { "userCode": "PQXR-4K7M" }, "schema": { "properties": { "userCode": { "type": "string" } }, "required": [ "userCode" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "clientName": { "type": "string" }, "expiresAt": { "type": "string" }, "userCode": { "type": "string" } }, "required": [ "userCode", "clientName", "expiresAt" ], "type": "object" } } }, "description": "The CLI may now exchange its device code." }, "400": { "content": { "application/json": { "example": { "error": "invalid_request" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Empty user code." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Approve a CLI device code", "tags": [ "Auth" ] } }, "/api/auth/cli/authorize": { "post": { "description": "Console only; session token required. Creates an already-approved authorization code the browser carries back to 127.0.0.1. `redirectUri` must be loopback HTTP.", "operationId": "authorizeCli", "requestBody": { "content": { "application/json": { "schema": { "properties": { "clientName": { "type": "string" }, "codeChallenge": { "type": "string" }, "redirectUri": { "type": "string" } }, "required": [ "codeChallenge", "redirectUri" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "code": { "type": "string" } }, "required": [ "code" ], "type": "object" } } }, "description": "Single-use authorization code." }, "400": { "content": { "application/json": { "example": { "error": "invalid code_challenge" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "PKCE or redirect_uri rejected." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Approve CLI loopback sign-in", "tags": [ "Auth" ] } }, "/api/auth/cli/device": { "post": { "description": "Unauthenticated. Hands the CLI a device code (secret) and a short user code the human types into the console. User codes are 8 characters from a no-vowel alphabet, grouped as `XXXX-XXXX`. Limit: 30 starts per address per 15 minutes.", "operationId": "startCliDeviceAuth", "requestBody": { "content": { "application/json": { "example": { "clientName": "devbox", "codeChallenge": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG" }, "schema": { "properties": { "clientName": { "type": "string" }, "codeChallenge": { "type": "string" } }, "required": [ "codeChallenge" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deviceCode": { "type": "string" }, "expiresIn": { "type": "number" }, "interval": { "type": "number" }, "userCode": { "type": "string" }, "verificationUri": { "type": "string" }, "verificationUriComplete": { "type": "string" } }, "required": [ "deviceCode", "userCode", "verificationUri", "verificationUriComplete", "expiresIn", "interval" ], "type": "object" } } }, "description": "Device and user codes. Poll `exchangeCliCode` every `interval` seconds." }, "400": { "content": { "application/json": { "example": { "error": "invalid code_challenge" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "PKCE S256 challenge is the wrong shape." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [], "summary": "Start CLI device-code sign-in", "tags": [ "Auth" ] } }, "/api/auth/cli/request/{userCode}": { "get": { "description": "Console only. Requires a **session** token (`tok_`), not an API token — an API token must not mint a child token. Reading is not approving; 200 vs 404 is still an oracle for “is this code live”, so the route is rate-limited (30/user, 90/address per 15 minutes).", "operationId": "getCliAuthRequest", "parameters": [ { "in": "path", "name": "userCode", "required": true, "schema": { "example": "PQXR-4K7M", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "clientName": { "type": "string" }, "expiresAt": { "type": "string" }, "userCode": { "type": "string" } }, "required": [ "userCode", "clientName", "expiresAt" ], "type": "object" } } }, "description": "Pending request the signed-in user may approve." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Look up a CLI device code", "tags": [ "Auth" ] } }, "/api/auth/cli/start": { "get": { "description": "Redirects the browser to the console with PKCE parameters. `redirect_uri` must be `http://127.0.0.1` or `http://[::1]` with no query, fragment, or userinfo. `localhost` is refused because it is a name. `code_challenge_method` must be `S256`. This response is an HTTP redirect, not JSON.", "operationId": "startCliAuth", "parameters": [ { "in": "query", "name": "redirect_uri", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "state", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "code_challenge", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "code_challenge_method", "required": true, "schema": { "enum": [ "S256" ], "type": "string" } }, { "in": "query", "name": "client_name", "required": false, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to the console CLI approval page." }, "400": { "description": "Invalid PKCE, missing state, or non-loopback redirect_uri. Plain text, not JSON." } }, "security": [], "summary": "Start CLI loopback sign-in", "tags": [ "Auth" ] } }, "/api/auth/cli/token": { "post": { "description": "Unauthenticated. Spends the loopback authorization code or the device code. The row is deleted in the same statement that validates it. While nobody has approved a device flow, the body is `{ error: \"authorization_pending\" }` (not a 401). Polling faster than `interval` is `{ error: \"slow_down\" }` with HTTP 429 — keep polling, do not abandon the sign-in. PKCE S256 binds the code to the process that started it.", "operationId": "exchangeCliCode", "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "type": "string" }, "codeVerifier": { "type": "string" } }, "required": [ "code", "codeVerifier" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "apiToken": { "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "lastUsedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "prefix": { "type": "string" }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "prefix", "createdAt", "lastUsedAt", "revokedAt" ], "type": "object" }, "token": { "type": "string" }, "user": { "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "email", "name" ], "type": "object" } }, "required": [ "token", "user", "apiToken" ], "type": "object" } } }, "description": "API token secret, shown once, plus the token list row." }, "400": { "content": { "application/json": { "example": { "error": "invalid_request" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing code or verifier, or the grant is invalid/expired/pending." }, "429": { "content": { "application/json": { "example": { "error": "slow_down", "retryAfter": 5 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "`slow_down` (RFC 8628) for both the per-code poll interval and the per-address budget. Wait and keep polling; do not treat this 429 as a spent grant. This endpoint never answers `rate_limited`.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } } } }, "security": [], "summary": "Exchange a CLI code for an API token", "tags": [ "Auth" ] } }, "/api/auth/logout": { "post": { "description": "Deletes the session when the bearer token is a `tok_` session. API tokens are not sessions and are not revoked here. Always returns `{ ok: true }` — it does not 401.", "operationId": "logout", "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "The session is gone, or there was none." } }, "security": [], "summary": "Drop a session", "tags": [ "Auth" ] } }, "/api/auth/magic-link": { "post": { "description": "Creates a single-use magic link for `email` and sends it to that inbox; the link expires in 15 minutes and opens the console the request came from (an `Origin` equal to the operator console’s lands there; anything else, including no `Origin`, lands on the customer console). A demo deployment (`DEV_MAGIC_LINKS=true`) returns the link as `devLink` instead of sending it, and only when `X-Tori-Demo-Secret` matches — that header does nothing in production. Invalid addresses still spend the per-address budget. The per-email budget is spent only after allowlist and demo-secret checks, so a stranger cannot lock a real inbox. Limit: 10 links per email / 60 per address per 15 minutes.", "operationId": "requestMagicLink", "requestBody": { "content": { "application/json": { "example": { "email": "you@example.com" }, "schema": { "properties": { "email": { "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "properties": { "devLink": { "type": "string" }, "ok": { "const": true, "type": "boolean" } }, "required": [ "ok" ], "type": "object" } } }, "description": "The link was sent (or, in a demo deployment, returned as `devLink`)." }, "400": { "content": { "application/json": { "example": { "error": "invalid email" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The body was not an email address." }, "403": { "content": { "application/json": { "example": { "error": "forbidden" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The address is not on the allowlist, or the demo access code is wrong." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } }, "503": { "content": { "application/json": { "example": { "error": "sign-in mail could not be sent" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The mail provider refused or did not answer, or this deployment has no way to deliver a link. Nothing was recorded; request again." } }, "security": [], "summary": "Request a sign-in link", "tags": [ "Auth" ] } }, "/api/auth/session": { "get": { "description": "Requires a bearer token. Returns the same shape as redeeming a magic link.", "operationId": "getSession", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "token": { "type": "string" }, "user": { "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "email", "name" ], "type": "object" } }, "required": [ "token", "user" ], "type": "object" } } }, "description": "The caller is signed in." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." } }, "security": [ { "bearerAuth": [] } ], "summary": "Read the current session", "tags": [ "Auth" ] } }, "/api/tokens": { "get": { "description": "Metadata only. Secrets are shown once at creation. Revoked tokens remain in the list with `revokedAt` set.", "operationId": "listTokens", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "lastUsedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "prefix": { "type": "string" }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "prefix", "createdAt", "lastUsedAt", "revokedAt" ], "type": "object" }, "type": "array" } } }, "description": "Tokens of this account, newest first." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "List API tokens", "tags": [ "Tokens" ] }, "post": { "description": "`name` is required. The `secret` field is the only time the token string is returned. Prefix `tori_` is public; the secret half is 192 bits and is independent of the prefix.", "operationId": "createToken", "requestBody": { "content": { "application/json": { "example": { "name": "ci" }, "schema": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "secret": { "type": "string" }, "token": { "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "lastUsedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "prefix": { "type": "string" }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "prefix", "createdAt", "lastUsedAt", "revokedAt" ], "type": "object" } }, "required": [ "token", "secret" ], "type": "object" } } }, "description": "Token row plus one-time secret." }, "400": { "content": { "application/json": { "example": { "error": "name required" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Empty name." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Mint an API token", "tags": [ "Tokens" ] } }, "/api/tokens/{tokenId}": { "delete": { "description": "Sets `revokedAt`. The row remains listable. 404 if the id is not this account’s.", "operationId": "revokeToken", "parameters": [ { "in": "path", "name": "tokenId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "lastUsedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "prefix": { "type": "string" }, "revokedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "prefix", "createdAt", "lastUsedAt", "revokedAt" ], "type": "object" } } }, "description": "The token, now revoked." }, "401": { "content": { "application/json": { "example": { "error": "unauthorized" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Missing or invalid bearer token. Session tokens start with `tok_`; API tokens start with `tori_`." }, "404": { "content": { "application/json": { "example": { "error": "not found" }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "The named resource is not visible to this account. Deleted apps look like this." }, "429": { "content": { "application/json": { "example": { "error": "rate_limited", "retryAfter": 42 }, "schema": { "properties": { "blockingDeployId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "error": { "type": "string" }, "limit": { "type": "number" }, "message": { "type": "string" }, "plan": { "enum": [ "nestling", "songbird", "flock" ], "type": "string" }, "reason": { "type": "string" }, "retryAfter": { "type": "number" }, "retryAfterSeconds": { "type": "number" } }, "required": [ "error" ], "type": "object" } } }, "description": "Too many requests in the current window. The only rate-limit header is `Retry-After` (seconds until the window rolls). The JSON body repeats `retryAfter`. There are no `X-RateLimit-*` headers. The window is the one named on this operation — not a single process-wide budget.", "headers": { "Retry-After": { "description": "Whole seconds until the window rolls.", "schema": { "minimum": 1, "type": "integer" } } } } }, "security": [ { "bearerAuth": [] } ], "summary": "Revoke an API token", "tags": [ "Tokens" ] } }, "/healthz": { "get": { "description": "Unstamped processes report `build: \"dev\"`. Production images echo the image tag so a deploy check can tell this release from the previous one. No authentication.", "operationId": "getHealthz", "responses": { "200": { "content": { "application/json": { "example": { "build": "dev", "ok": true }, "schema": { "properties": { "build": { "type": "string" }, "ok": { "const": true, "type": "boolean" } }, "required": [ "ok", "build" ], "type": "object" } } }, "description": "This process is serving." } }, "security": [], "summary": "Process health", "tags": [ "Meta" ] } } }, "components": { "securitySchemes": { "bearerAuth": { "description": "Session token (`tok_…`) or API token (`tori_…`). CLI device/loopback approval requires a session token.", "scheme": "bearer", "type": "http" } } } }