{ "servers": [ { "url": "api.deno.com" } ], "info": { "title": "Deno Deploy API", "version": "2.0.0", "description": "[Download OpenAPI Spec](./openapi.json)\n\nREST API for managing apps, revisions, layers, and runtime logs on [Deno Deploy](https://deno.com/deploy).\n\n## SDKs\n\n- **Python**: [github.com/denoland/sandbox-py](https://github.com/denoland/sandbox-py)\n- **JavaScript / TypeScript**: [@deno/sandbox on npm](https://www.npmjs.com/package/@deno/sandbox)\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer ddo_your_token_here\n```\n\nOrganization access tokens can be created in the Deno Deploy dashboard under **Settings > Access Tokens**.\n\n## Conventions\n\n- All field names use `snake_case`.\n- Streaming endpoints support both JSONL (`application/x-ndjson`) and SSE (`text/event-stream`). Set the `Accept` header to choose a format.\n\n## Pagination\n\nList endpoints use cursor-based pagination with `cursor` and `limit` query parameters. When more results exist, the response includes a `Link` header with the next page URL:\n\n```\nLink: ; rel=\"next\"\n```\n\n## Error Responses\n\nAll errors return a consistent JSON body:\n\n```json\n{\n \"error\": {\n \"code\": \"ERROR_CODE\",\n \"message\": \"Human-readable description\"\n }\n}\n```" }, "tags": [ { "name": "apps", "description": "An app is the top-level container for a deployable application.\nApps have configuration (build settings, environment variables), can reference layers for shared config, and contain revisions (deployments).\n\n**Key characteristics:**\n\n- Identified by UUID or human-readable slug (slugs cannot contain underscores, IDs always do)\n- Support up to 5 labels for filtering and grouping\n- Reference layers via `layers` array for inherited configuration\n- Have app-specific `env_vars` that override layer values\n- Have a `config` that provides defaults for revisions" }, { "name": "revisions", "description": "A revision represents a specific build and deployment of an app. Revisions are immutable once created — to make changes, you create a new revision.\n\nStatus lifecycle: `queued` → `building` → `succeeded` (success), `queued` → `failed` (build error, cancelled, or timeout), or `queued` → `skipped`." }, { "name": "layers", "description": "A layer is a mutable configuration object that can be shared across multiple apps. Layers provide the solution for bulk environment variable management: instead of updating thousands of apps individually, you create a layer, attach it to apps, then update the layer once.\n\n**Key characteristics:**\n\n- Organization-scoped and identified by ID or slug\n- Contain environment variables\n- Can include other layers (base layers) for hierarchical configuration\n- Apps reference layers in their `layers` array\n- Updating a layer is O(1) regardless of how many apps reference it\n- Layer updates cause running isolates to restart but do not require redeployment" }, { "name": "environment variables", "description": "Environment variables can be set on layers, apps, and revisions. They support **context filtering**, allowing different values per deployment context (e.g., `production`, `preview`, `build`).\n\n## Resolution Order\n\nResolution order (later overrides earlier):\n\n1. Organization-wide env vars\n2. App's layer env vars (flattened, in `layers` array order)\n3. App-specific env vars\n4. Revision's layer env vars (flattened, in `layers` array order)\n5. Revision-specific env vars\n\nWithin each layer level (2 and 4), later entries in the `layers` array override earlier ones. When a layer includes base layers, those bases are resolved depth-first, then the including layer's own env vars take precedence. For example, if `app.layers` is `[X]` and layer X includes `[A, B]`, the resolution within level 2 is: A → B → X (X's own vars win).\n\n> **Note:** The current implementation uses a different resolution order where app-level env vars (levels 3–5) take precedence over revision-level env vars (levels 1–2). We plan to align the implementation with the documented order above in a future update.\n\n## Updating\n\nWhen updating via PATCH, `env_vars` performs a **deep merge**: match by `id`, or by `key`+`contexts`, or create new. Set `delete: true` to remove." } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "description": "Bearer token authentication", "type": "http", "scheme": "Bearer", "bearerFormat": "string" } }, "schemas": { "Labels": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "examples": [ { "custom.customer_id": "cust_123", "custom.environment": "production" } ] }, "EnvVar": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the environment variable" }, "key": { "type": "string", "description": "The environment variable name" }, "value": { "type": "string", "description": "The value. Omitted when `secret` is true" }, "secret": { "type": "boolean", "description": "Whether the value is masked in API responses" }, "contexts": { "anyOf": [ { "const": "all" }, { "type": "array", "items": { "type": "string" } } ], "description": "Deployment contexts this variable applies to. `\"all\"` means every context." } }, "required": [ "id", "key", "secret", "contexts" ], "examples": [ { "id": "00000000-0000-0000-0000-000000000000", "key": "DATABASE_URL", "value": "postgres://localhost/dev", "secret": false, "contexts": "all" }, { "id": "00000000-0000-0000-0000-000000000000", "key": "API_SECRET", "secret": true, "contexts": "all" }, { "id": "00000000-0000-0000-0000-000000000000", "key": "CACHE_TTL", "value": "3600", "secret": false, "contexts": [ "production" ] } ] }, "EnvVarInput": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$", "description": "The environment variable name" }, "value": { "type": "string", "maxLength": 4096, "description": "The environment variable value" }, "secret": { "type": "boolean", "description": "Whether to mask the value in API responses. Defaults to false" }, "contexts": { "anyOf": [ { "const": "all" }, { "type": "array", "items": { "type": "string" } } ], "description": "Deployment contexts this variable applies to. Defaults to `\"all\"`." } }, "required": [ "key", "value" ], "examples": [ { "key": "DATABASE_URL", "value": "postgres://localhost/dev" }, { "key": "API_SECRET", "value": "sk-xxx", "secret": true }, { "key": "CACHE_TTL", "value": "3600", "contexts": [ "production" ] } ] }, "EnvVarInputForDeploy": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_]+$", "description": "The environment variable name" }, "value": { "type": "string", "maxLength": 4096, "description": "The environment variable value" } }, "required": [ "key", "value" ], "examples": [ { "key": "DATABASE_URL", "value": "postgres://localhost/dev" } ] }, "RevisionEnvVar": { "type": "object", "properties": { "key": { "type": "string", "description": "The environment variable name" }, "value": { "type": "string", "description": "The environment variable value" } }, "required": [ "key", "value" ], "examples": [ { "key": "DATABASE_URL", "value": "postgres://localhost/dev" } ] }, "EnvVarUpdate": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the existing variable to update or delete" }, "key": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Variable name. Used for matching when `id` is not provided" }, "value": { "type": "string", "maxLength": 4096, "description": "New value for the variable" }, "secret": { "type": "boolean", "description": "Whether to mask the value in API responses" }, "contexts": { "anyOf": [ { "const": "all" }, { "type": "array", "items": { "type": "string" } } ], "description": "Deployment contexts this variable applies to" }, "delete": { "type": "boolean", "description": "Set to true to remove this variable" } }, "examples": [ { "id": "00000000-0000-0000-0000-000000000000", "value": "postgres://prod-host/db" }, { "id": "00000000-0000-0000-0000-000000000000", "delete": true }, { "key": "NEW_VAR", "value": "new-value" } ] }, "LayerRefInput": { "anyOf": [ { "type": "string", "description": "Layer ID to reference" }, { "type": "string", "description": "Layer slug to reference" } ] }, "LayerRef": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique layer identifier" }, "slug": { "type": "string", "description": "Human-readable layer slug" } }, "required": [ "id", "slug" ], "examples": [ { "id": "lyr_abc123", "slug": "shared-secrets" } ] }, "Runtime": { "type": "object", "properties": { "type": { "enum": [ "dynamic", "static" ], "description": "`dynamic` runs a Deno process; `static` serves pre-built files" }, "entrypoint": { "type": "string", "description": "Main module path. Required when `type` is `dynamic`" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Additional CLI arguments passed to the entrypoint" }, "cwd": { "type": "string", "description": "Working directory or static file root. Required when `type` is `static`" }, "spa": { "type": "boolean", "description": "Enable single-page application mode (fallback to index.html). Only for `static` type" } }, "required": [ "type" ] }, "Config": { "type": "object", "properties": { "framework": { "enum": [ "", "nextjs", "astro", "nuxt", "remix", "solidstart", "tanstackstart", "sveltekit", "fresh", "lume" ], "description": "Framework preset. Mutually exclusive with `runtime`" }, "install": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom install command. Omit to skip the install step" }, "build": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom build command. Omit to skip the build step" }, "predeploy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Command to run before each deployment (e.g. database migrations). Omit to skip" }, "runtime": { "$ref": "#/components/schemas/Runtime", "description": "Runtime configuration. Mutually exclusive with `framework`" }, "crons": { "type": "boolean", "description": "Whether cron jobs are enabled for revisions of the app. When false, revisions that register cron jobs using Deno.cron fail to build. Defaults to true" } }, "examples": [ { "framework": "nextjs", "install": "npm install", "build": "npm run build" }, { "runtime": { "type": "dynamic", "entrypoint": "main.ts" } }, { "runtime": { "type": "static", "cwd": "./dist", "spa": true } } ] }, "ConfigOutput": { "type": "object", "properties": { "framework": { "enum": [ "", "nextjs", "astro", "nuxt", "remix", "solidstart", "tanstackstart", "sveltekit", "fresh", "lume" ], "description": "Framework preset used for this build" }, "install": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Install command. Null if skipped" }, "build": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Build command. Null if skipped" }, "predeploy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pre-deploy command. Null if skipped" }, "runtime": { "$ref": "#/components/schemas/Runtime", "description": "Runtime configuration" }, "crons": { "type": "boolean", "description": "Whether cron jobs are enabled for revisions of the app. When false, revisions that register cron jobs using Deno.cron fail to build. Defaults to true" } } }, "Asset": { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "file", "default": "file", "description": "Asset type discriminator" }, "encoding": { "enum": [ "utf-8", "base64" ], "default": "utf-8", "description": "Content encoding" }, "content": { "type": "string", "description": "File content, encoded according to `encoding`" } }, "required": [ "content" ] }, { "type": "object", "properties": { "kind": { "const": "symlink", "description": "Asset type discriminator" }, "target": { "type": "string", "description": "Relative path to the symlink target" } }, "required": [ "kind", "target" ] } ], "examples": [ { "kind": "file", "encoding": "utf-8", "content": "Deno.serve(() => new Response(\"Hello\"));" }, { "kind": "file", "encoding": "base64", "content": "aGVsbG8=" }, { "kind": "symlink", "target": "./main.ts" } ] }, "Assets": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/Asset" }, "examples": [ { "main.ts": { "kind": "file", "encoding": "utf-8", "content": "Deno.serve(() => new Response(\"Hello\"));" }, "deno.json": { "kind": "file", "encoding": "utf-8", "content": "{\"imports\": {}}" } } ] }, "Partition": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "examples": [ { "git.branch": "main" } ] }, "BuildStep": { "enum": [ "preparing", "installing", "building", "deploying" ] }, "BuildLogEntry": { "type": "object", "properties": { "timestamp": { "type": "string", "description": "ISO 8601 timestamp of the log entry" }, "level": { "enum": [ "debug", "info", "warn", "error" ], "description": "Log severity level" }, "message": { "type": "string", "description": "Log message content" }, "step": { "$ref": "#/components/schemas/BuildStep", "description": "Build step that produced this log (e.g. `preparing`, `installing`, `building`)" }, "timeline": { "type": "string", "description": "Timeline slug, if the log is associated with a specific timeline" } }, "required": [ "timestamp", "level", "message" ], "examples": [ { "timestamp": "2024-01-15T10:30:05Z", "level": "info", "message": "Starting build...", "step": "preparing" }, { "timestamp": "2024-01-15T10:30:20Z", "level": "error", "message": "Failed to resolve module 'foo'", "step": "installing" } ] }, "RevisionProgress": { "type": "object", "properties": { "queued": { "anyOf": [ { "type": "object", "properties": { "status": { "const": "pending", "description": "Stage has not started yet" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "skipped", "description": "Stage was skipped" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "running", "description": "Stage is currently running" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" } }, "required": [ "status", "start" ] }, { "type": "object", "properties": { "status": { "enum": [ "succeeded", "timed_out", "cancelled", "errored" ], "description": "Terminal stage status" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" }, "end": { "type": "string", "description": "ISO 8601 timestamp when the stage ended" } }, "required": [ "status", "start", "end" ] } ], "description": "Queue stage — waiting for a build slot" }, "preparing": { "anyOf": [ { "type": "object", "properties": { "status": { "const": "pending", "description": "Stage has not started yet" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "skipped", "description": "Stage was skipped" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "running", "description": "Stage is currently running" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" } }, "required": [ "status", "start" ] }, { "type": "object", "properties": { "status": { "enum": [ "succeeded", "timed_out", "cancelled", "errored" ], "description": "Terminal stage status" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" }, "end": { "type": "string", "description": "ISO 8601 timestamp when the stage ended" } }, "required": [ "status", "start", "end" ] } ], "description": "Prepare stage — cloning source code and restoring caches" }, "installing": { "allOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "const": "pending", "description": "Stage has not started yet" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "skipped", "description": "Stage was skipped" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "running", "description": "Stage is currently running" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" } }, "required": [ "status", "start" ] }, { "type": "object", "properties": { "status": { "enum": [ "succeeded", "timed_out", "cancelled", "errored" ], "description": "Terminal stage status" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" }, "end": { "type": "string", "description": "ISO 8601 timestamp when the stage ended" } }, "required": [ "status", "start", "end" ] } ] }, { "type": "object", "properties": { "command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The command being executed, or null if not applicable" } }, "required": [ "command" ] } ], "description": "Install stage — installing dependencies" }, "building": { "allOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "const": "pending", "description": "Stage has not started yet" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "skipped", "description": "Stage was skipped" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "running", "description": "Stage is currently running" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" } }, "required": [ "status", "start" ] }, { "type": "object", "properties": { "status": { "enum": [ "succeeded", "timed_out", "cancelled", "errored" ], "description": "Terminal stage status" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" }, "end": { "type": "string", "description": "ISO 8601 timestamp when the stage ended" } }, "required": [ "status", "start", "end" ] } ] }, { "type": "object", "properties": { "command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The command being executed, or null if not applicable" } }, "required": [ "command" ] } ], "description": "Build stage — running the build command" }, "deploying": { "allOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "const": "pending", "description": "Stage has not started yet" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "skipped", "description": "Stage was skipped" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "running", "description": "Stage is currently running" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" } }, "required": [ "status", "start" ] }, { "type": "object", "properties": { "status": { "enum": [ "succeeded", "timed_out", "cancelled", "errored" ], "description": "Terminal stage status" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" }, "end": { "type": "string", "description": "ISO 8601 timestamp when the stage ended" } }, "required": [ "status", "start", "end" ] } ] }, { "type": "object", "properties": { "timelines": { "type": "array", "items": { "allOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "const": "pending", "description": "Stage has not started yet" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "skipped", "description": "Stage was skipped" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "running", "description": "Stage is currently running" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" } }, "required": [ "status", "start" ] }, { "type": "object", "properties": { "status": { "enum": [ "succeeded", "timed_out", "cancelled", "errored" ], "description": "Terminal stage status" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" }, "end": { "type": "string", "description": "ISO 8601 timestamp when the stage ended" } }, "required": [ "status", "start", "end" ] } ] }, { "type": "object", "properties": { "slug": { "type": "string", "description": "Timeline slug" }, "partition": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "examples": [ { "git.branch": "main" } ], "description": "Partition key-value pairs identifying this timeline" }, "databases": { "type": "array", "items": { "allOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "const": "pending", "description": "Stage has not started yet" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "skipped", "description": "Stage was skipped" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "running", "description": "Stage is currently running" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" } }, "required": [ "status", "start" ] }, { "type": "object", "properties": { "status": { "enum": [ "succeeded", "timed_out", "cancelled", "errored" ], "description": "Terminal stage status" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" }, "end": { "type": "string", "description": "ISO 8601 timestamp when the stage ended" } }, "required": [ "status", "start", "end" ] } ] }, { "type": "object", "properties": { "engine": { "type": "string", "description": "Database engine type (e.g. postgresql, denokv)" } }, "required": [ "engine" ] } ] }, "description": "Per-database provisioning progress" }, "predeploy": { "allOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "const": "pending", "description": "Stage has not started yet" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "skipped", "description": "Stage was skipped" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "running", "description": "Stage is currently running" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" } }, "required": [ "status", "start" ] }, { "type": "object", "properties": { "status": { "enum": [ "succeeded", "timed_out", "cancelled", "errored" ], "description": "Terminal stage status" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" }, "end": { "type": "string", "description": "ISO 8601 timestamp when the stage ended" } }, "required": [ "status", "start", "end" ] } ] }, { "type": "object", "properties": { "command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The command being executed, or null if not applicable" } }, "required": [ "command" ] } ], "description": "Pre-deploy command stage progress" }, "warmup": { "anyOf": [ { "type": "object", "properties": { "status": { "const": "pending", "description": "Stage has not started yet" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "skipped", "description": "Stage was skipped" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "running", "description": "Stage is currently running" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" } }, "required": [ "status", "start" ] }, { "type": "object", "properties": { "status": { "enum": [ "succeeded", "timed_out", "cancelled", "errored" ], "description": "Terminal stage status" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" }, "end": { "type": "string", "description": "ISO 8601 timestamp when the stage ended" } }, "required": [ "status", "start", "end" ] } ], "description": "Isolate warmup stage progress" }, "routing": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "const": "pending", "description": "Stage has not started yet" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "skipped", "description": "Stage was skipped" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "const": "running", "description": "Stage is currently running" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" } }, "required": [ "status", "start" ] }, { "type": "object", "properties": { "status": { "enum": [ "succeeded", "timed_out", "cancelled", "errored" ], "description": "Terminal stage status" }, "start": { "type": "string", "description": "ISO 8601 timestamp when the stage started" }, "end": { "type": "string", "description": "ISO 8601 timestamp when the stage ended" } }, "required": [ "status", "start", "end" ] } ] }, { "type": "object", "properties": { "status": { "const": "timeline_blocked", "description": "Routing is blocked waiting for other timelines" }, "timelines": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "Timeline slug" }, "partition": { "type": "object", "propertyNames": {}, "additionalProperties": {}, "examples": [ { "git.branch": "main" } ], "description": "Partition key-value pairs identifying this timeline" } }, "required": [ "slug", "partition" ] }, "description": "Timelines that are blocking this stage" }, "stage": { "const": "warmup", "description": "The stage that is blocked" } }, "required": [ "status", "timelines", "stage" ] } ], "description": "Domain routing stage progress" } }, "required": [ "slug", "partition", "databases", "predeploy", "routing" ] } ] }, "description": "Per-timeline deployment progress" } }, "required": [ "timelines" ] } ], "description": "Deploy stage — uploading artifacts and routing traffic" } }, "required": [ "queued", "preparing", "installing", "building", "deploying" ], "examples": [ { "queued": { "status": "succeeded", "start": "2025-01-01T00:00:00Z", "end": "2025-01-01T00:00:01Z" }, "preparing": { "status": "succeeded", "start": "2025-01-01T00:00:01Z", "end": "2025-01-01T00:00:05Z" }, "installing": { "status": "succeeded", "start": "2025-01-01T00:00:05Z", "end": "2025-01-01T00:00:10Z", "command": null }, "building": { "status": "succeeded", "start": "2025-01-01T00:00:10Z", "end": "2025-01-01T00:00:20Z", "command": "deno task build" }, "deploying": { "status": "succeeded", "start": "2025-01-01T00:00:20Z", "end": "2025-01-01T00:00:25Z", "timelines": [ { "status": "succeeded", "start": "2025-01-01T00:00:20Z", "end": "2025-01-01T00:00:25Z", "slug": "production", "partition": {}, "databases": [ { "status": "succeeded", "start": "2025-01-01T00:00:20Z", "end": "2025-01-01T00:00:22Z", "engine": "postgresql" }, { "status": "succeeded", "start": "2025-01-01T00:00:20Z", "end": "2025-01-01T00:00:21Z", "engine": "denokv" } ], "predeploy": { "status": "succeeded", "start": "2025-01-01T00:00:22Z", "end": "2025-01-01T00:00:23Z", "command": "deno task db:migrate" }, "routing": { "status": "succeeded", "start": "2025-01-01T00:00:23Z", "end": "2025-01-01T00:00:25Z" } } ] } } ] }, "RuntimeLog": { "type": "object", "properties": { "timestamp": { "type": "string", "description": "ISO 8601 timestamp of the log entry" }, "level": { "enum": [ "debug", "info", "warn", "error" ], "description": "Log severity level" }, "message": { "type": "string", "description": "Log message content" }, "revision_id": { "type": "string", "description": "Revision that produced this log entry" }, "region": { "type": "string", "description": "Region where the isolate was running" }, "trace_id": { "type": "string", "description": "OpenTelemetry trace ID for request correlation" }, "span_id": { "type": "string", "description": "OpenTelemetry span ID" } }, "required": [ "timestamp", "level", "message" ], "examples": [ { "timestamp": "2024-01-15T10:30:00.123Z", "level": "info", "message": "Handling request", "revision_id": "r2ysnrrhr352", "region": "us-east-1", "trace_id": "abc123def456", "span_id": "span789" } ] }, "RuntimeLogsResponse": { "type": "object", "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeLog" }, "description": "Array of log entries" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for fetching the next page, or null if no more results" } }, "required": [ "logs", "next_cursor" ], "examples": [ { "logs": [ { "timestamp": "2024-01-15T10:30:00.123Z", "level": "info", "message": "Handling request", "revision_id": "r2ysnrrhr352", "region": "us-east-1" }, { "timestamp": "2024-01-15T10:30:00.456Z", "level": "error", "message": "Database connection failed", "revision_id": "r2ysnrrhr352", "region": "us-east-1" } ], "next_cursor": "eyJsYXN0X3RpbWVzdGFtcCI6..." } ] }, "App": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique app identifier (UUID)" }, "slug": { "type": "string", "description": "Human-readable app slug" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "User-defined key-value labels for filtering and grouping" }, "layers": { "type": "array", "items": { "$ref": "#/components/schemas/LayerRef" }, "description": "Layers referenced by this app, in priority order (later overrides earlier)" }, "env_vars": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVar" }, "description": "App-specific environment variables" }, "config": { "$ref": "#/components/schemas/ConfigOutput", "description": "Default build and runtime configuration for new revisions" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of last modification" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of creation" } }, "required": [ "id", "slug", "layers", "updated_at", "created_at" ], "examples": [ { "id": "00000000-0000-0000-0000-000000000000", "slug": "my-customer-app", "labels": { "custom.customer_id": "cust_123", "custom.environment": "production" }, "layers": [ { "id": "lyr_abc123", "slug": "shared-secrets" } ], "env_vars": [ { "id": "00000000-0000-0000-0000-000000000000", "key": "APP_NAME", "value": "My Customer App", "secret": false, "contexts": "all" } ], "config": { "framework": "nextjs", "install": "npm install", "build": "npm run build" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ] }, "AppListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique app identifier (UUID)" }, "slug": { "type": "string", "description": "Human-readable app slug" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "User-defined key-value labels" }, "layers": { "type": "array", "items": { "$ref": "#/components/schemas/LayerRef" }, "description": "Layers referenced by this app, in priority order (later overrides earlier)" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of last modification" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of creation" } }, "required": [ "id", "slug", "layers", "updated_at", "created_at" ] }, "Revision": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique revision identifier" }, "status": { "enum": [ "skipped", "queued", "building", "succeeded", "failed" ], "description": "Current revision lifecycle status" }, "failure_reason": { "anyOf": [ { "enum": [ "error", "cancelled", "timed_out", "skipped" ] }, { "type": "null" } ], "description": "Reason for failure, or null if not failed" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "Metadata labels attached to this revision (e.g. git info)" }, "layers": { "type": "array", "items": { "$ref": "#/components/schemas/LayerRef" }, "description": "Layers referenced by this revision, in priority order (later overrides earlier)" }, "env_vars": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionEnvVar" }, "description": "Revision-specific environment variables (immutable once created)" }, "config": { "$ref": "#/components/schemas/ConfigOutput", "description": "Build and runtime configuration used for this revision" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of creation" }, "cancellation_requested_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when cancellation was requested, or null" }, "build_finished_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the build completed, or null if still building" }, "deleted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of deletion, or null if active" } }, "required": [ "id", "status", "failure_reason", "layers", "env_vars", "created_at", "cancellation_requested_at", "build_finished_at", "deleted_at" ], "examples": [ { "id": "r2ysnrrhr352", "status": "succeeded", "failure_reason": null, "labels": { "custom.branch": "main", "custom.sha": "abc123def456" }, "layers": [ { "id": "lyr_abc123", "slug": "deployment-secrets" } ], "env_vars": [ { "key": "BUILD_ID", "value": "abc123" } ], "config": { "framework": "fresh", "install": "deno cache main.ts" }, "created_at": "2024-01-15T10:30:00Z", "cancellation_requested_at": null, "build_finished_at": "2024-01-15T10:31:50Z", "deleted_at": null }, { "id": "r2ysnrrhr352", "status": "failed", "failure_reason": "error", "labels": { "custom.branch": "main" }, "layers": [], "env_vars": [], "config": { "framework": "fresh" }, "created_at": "2024-01-15T10:30:00Z", "cancellation_requested_at": null, "build_finished_at": "2024-01-15T10:32:00Z", "deleted_at": null } ] }, "RevisionListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique revision identifier" }, "status": { "enum": [ "skipped", "queued", "building", "succeeded", "failed" ], "description": "Current revision lifecycle status" }, "failure_reason": { "anyOf": [ { "enum": [ "error", "cancelled", "timed_out", "skipped" ] }, { "type": "null" } ], "description": "Reason for failure, or null if not failed" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "Metadata labels attached to this revision" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of creation" }, "cancellation_requested_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when cancellation was requested, or null" }, "build_finished_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp when the build completed, or null if still building" }, "deleted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of deletion, or null if active" } }, "required": [ "id", "status", "failure_reason", "created_at", "cancellation_requested_at", "build_finished_at", "deleted_at" ] }, "Timeline": { "type": "object", "properties": { "slug": { "type": "string", "description": "Timeline slug derived from the partition config name" }, "partition": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "examples": [ { "git.branch": "main" } ], "description": "Partition key-value pairs identifying this timeline" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain name assigned to this timeline" } }, "required": [ "domain" ] }, "description": "Domains routed to this timeline" } }, "required": [ "slug", "partition", "domains" ] }, "Layer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique layer identifier" }, "slug": { "type": "string", "description": "Human-readable layer slug" }, "description": { "type": "string", "description": "Optional description of the layer's purpose" }, "layers": { "type": "array", "items": { "$ref": "#/components/schemas/LayerRef" }, "description": "Base layers included by this layer, in priority order (later overrides earlier). The including layer's own env vars take precedence over all its bases" }, "env_vars": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVar" }, "description": "Environment variables defined in this layer" }, "app_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of apps that reference this layer" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of creation" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of last modification" } }, "required": [ "id", "slug", "layers", "env_vars", "app_count", "created_at", "updated_at" ], "examples": [ { "id": "lyr_abc123", "slug": "shared-secrets", "description": "Common API keys and secrets for all customer apps", "layers": [ { "id": "lyr_base123", "slug": "base-config" } ], "env_vars": [ { "id": "00000000-0000-0000-0000-000000000000", "key": "DATABASE_URL", "value": "postgres://host/db", "secret": false, "contexts": "all" }, { "id": "00000000-0000-0000-0000-000000000000", "key": "API_SECRET", "secret": true, "contexts": "all" } ], "app_count": 42, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ] }, "LayerAppRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique app identifier (UUID)" }, "slug": { "type": "string", "description": "Human-readable app slug" }, "layer_position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Index of this layer in the app's `layers` array" } }, "required": [ "id", "slug", "layer_position" ], "examples": [ { "id": "00000000-0000-0000-0000-000000000000", "slug": "customer-app-1", "layer_position": 0 } ] } } }, "openapi": "3.1.1", "paths": { "/v2/apps/{app}": { "get": { "operationId": "apps.get", "summary": "Get app details", "description": "Get detailed information about an app, including labels, layers, environment variables, and config.", "tags": [ "apps" ], "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The app ID or slug" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } } } } }, "patch": { "operationId": "apps.update", "summary": "Update app", "description": "All fields are optional. `labels` and `layers` replace the entire value. `env_vars` performs a deep merge with existing variables. `config` replaces the entire deploy config (no deep merge).\n\nUpdating `layers` or `env_vars` will restart running isolates.", "tags": [ "apps" ], "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The app ID or slug" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "New app slug" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "Replace all labels" }, "layers": { "type": "array", "items": { "$ref": "#/components/schemas/LayerRefInput" }, "description": "Replace all layer references" }, "env_vars": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVarUpdate" }, "description": "Deep merge with existing environment variables" }, "config": { "$ref": "#/components/schemas/Config", "description": "Replace the entire deploy config" } }, "required": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } } } } }, "delete": { "operationId": "apps.delete", "summary": "Delete app", "description": "Delete an app and all its revisions.", "tags": [ "apps" ], "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The app ID or slug" } ], "responses": { "204": { "description": "OK" } } } }, "/v2/apps": { "get": { "operationId": "apps.list", "summary": "List apps", "description": "List apps with optional filtering by labels or layer.\n\nUse `labels[key]=value` query parameters to filter by label values. Use `layer` to filter apps that reference a specific layer.", "tags": [ "apps" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true, "description": "The pagination cursor" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "allowEmptyValue": true, "allowReserved": true, "description": "The maximum number of items to return" }, { "name": "labels", "in": "query", "schema": { "$ref": "#/components/schemas/Labels", "description": "Filter by labels" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true, "description": "Filter by labels (e.g. `labels[key]=value`)" }, { "name": "layer", "in": "query", "schema": { "type": "string" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true, "description": "Layer ID or slug. Slugs cannot contain underscores; IDs always do." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AppListItem" } } } } } } }, "post": { "operationId": "apps.create", "summary": "Create app", "description": "Apps can reference layers for shared configuration, have app-specific environment variables, and a config that provides defaults for revisions.", "tags": [ "apps" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "App slug. If omitted, a random slug is generated" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "Key-value labels for filtering and grouping (max 5)" }, "layers": { "type": "array", "items": { "$ref": "#/components/schemas/LayerRefInput" }, "description": "Layers to reference for inherited configuration" }, "env_vars": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVarInput" }, "description": "App-specific environment variables" }, "config": { "$ref": "#/components/schemas/Config", "description": "Default build and runtime configuration" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } } } } } }, "/v2/apps/{app}/deploy": { "post": { "operationId": "apps.deploy", "summary": "Create revision", "description": "Create a new revision (deployment).\n\nUpload source files as assets and optionally specify `config`, `layers`, `env_vars`, and `labels`. Asset keys are relative paths resolved against `/app/src`.\n\nIf `config` is omitted, it is inherited from the app's config. If specified, it fully replaces the app's config (no deep merge).\n\nRevision `env_vars` are immutable once created and have highest priority in the resolution order. Context filtering is not supported for revision env vars.\n\nUse `production` and `preview` to control which timelines the revision is deployed to. By default, revisions are deployed to the production timeline only.", "tags": [ "apps" ], "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The app ID or slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assets": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/Asset" }, "examples": [ { "main.ts": { "kind": "file", "encoding": "utf-8", "content": "Deno.serve(() => new Response(\"Hello\"));" }, "deno.json": { "kind": "file", "encoding": "utf-8", "content": "{\"imports\": {}}" } } ], "description": "Source files to deploy. Keys are paths relative to `/app/src`" }, "config": { "$ref": "#/components/schemas/Config", "description": "Build and runtime config. If omitted, inherited from the app" }, "layers": { "type": "array", "items": { "$ref": "#/components/schemas/LayerRefInput" }, "description": "Layers to reference for this revision" }, "env_vars": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVarInputForDeploy" }, "description": "Revision-specific environment variables (immutable once created)" }, "labels": { "$ref": "#/components/schemas/Labels", "description": "Metadata labels (e.g. git branch, commit SHA)" }, "production": { "type": "boolean", "default": true, "description": "Whether to deploy to the production timeline. Defaults to true" }, "preview": { "type": "boolean", "default": false, "description": "Whether to deploy as a preview deployment. Defaults to false" } }, "required": [ "assets" ] } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } } } } }, "/v2/apps/{app}/logs": { "get": { "operationId": "apps.logs", "summary": "Get or stream logs", "description": "Query historical runtime logs, or stream them using Server-Sent Events or JSONL.\n\nWhen `end` is specified, returns paginated JSON.\nWhen `end` is omitted, streams logs in real-time using SSE or JSONL.\n\nRequesting `Accept: application/json` without `end` will return an error.", "tags": [ "apps" ], "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The app ID or slug" }, { "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "Start of the time range (ISO 8601)" }, "allowEmptyValue": true, "allowReserved": true, "description": "Start of the time range (ISO 8601)" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "End of the time range (ISO 8601). If omitted, logs are streamed in real-time" }, "allowEmptyValue": true, "allowReserved": true, "description": "End of the time range (ISO 8601). If omitted, logs are streamed in real-time" }, { "name": "revision_id", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter logs by revision ID" }, "allowEmptyValue": true, "allowReserved": true, "description": "Filter logs by revision ID" }, { "name": "level", "in": "query", "required": false, "schema": { "enum": [ "debug", "info", "warn", "error" ], "description": "Minimum log severity level" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true, "description": "Minimum log severity level" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "description": "Full-text search query" }, "allowEmptyValue": true, "allowReserved": true, "description": "Full-text search query" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true, "description": "The pagination cursor" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "allowEmptyValue": true, "allowReserved": true, "description": "The maximum number of items to return" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeLogsResponse" } } } } } } }, "/v2/revisions/{revision}": { "get": { "operationId": "revisions.get", "summary": "Get revision details", "description": "Get revision details.\n\nRevision IDs are globally unique. The response includes `layers`, `env_vars`, and `config` when available.\n\nStatus lifecycle (one of):\n- queued -> building -> succeeded (success)\n- queued -> failed (build error, cancelled, or timeout)\n- queued -> skipped (e.g., commit message contains [skip-ci])", "tags": [ "revisions" ], "parameters": [ { "name": "revision", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Revision ID (globally unique)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } } } }, "delete": { "operationId": "revisions.delete", "summary": "Delete revision", "description": "Delete a revision. Cannot delete revisions that are currently building or actively routed.", "tags": [ "revisions" ], "parameters": [ { "name": "revision", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Revision ID (globally unique)" } ], "responses": { "204": { "description": "OK" } } } }, "/v2/revisions/{revision}/cancel": { "post": { "operationId": "revisions.cancel", "summary": "Cancel revision build", "description": "Request cancellation of a build in progress. Cancellation is asynchronous — this endpoint returns immediately with the current revision state. The `cancellation_requested_at` field will be set, but the revision may still be in `building` status. Poll the revision or use the [/progress](#tag/revisions/GET/api/v2/revisions/{revision}/progress) endpoint to wait for the build to reach the `failed` state with `failure_reason: \"cancelled\"`.", "tags": [ "revisions" ], "parameters": [ { "name": "revision", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Revision ID (globally unique)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } } } } }, "/v2/apps/{app}/revisions": { "get": { "operationId": "revisions.list", "summary": "List revisions for app", "description": "List revisions for an app. Optionally filter by status.", "tags": [ "revisions" ], "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The app ID or slug" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true, "description": "The pagination cursor" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "allowEmptyValue": true, "allowReserved": true, "description": "The maximum number of items to return" }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "skipped", "queued", "building", "succeeded", "failed" ], "description": "Filter revisions by status" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true, "description": "Filter by revision status" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionListItem" } } } } } } } }, "/v2/revisions/{revision}/progress": { "get": { "operationId": "revisions.progress", "summary": "Stream revision progress", "description": "Stream revision build progress. The stream ends when the revision\nreaches a terminal state (`succeeded`, `failed`, or `skipped`).\n\nSupports both JSONL (`Accept: application/x-ndjson`) and SSE (`Accept: text/event-stream`)\nformats via the `Accept` header.", "tags": [ "revisions" ], "parameters": [ { "name": "revision", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Revision ID (globally unique)" } ], "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "oneOf": [ { "type": "object", "properties": { "event": { "const": "message" }, "data": { "$ref": "#/components/schemas/RevisionProgress" }, "id": { "type": "string" }, "retry": { "type": "number" } }, "required": [ "event", "data" ] }, { "type": "object", "properties": { "event": { "const": "done" }, "data": {}, "id": { "type": "string" }, "retry": { "type": "number" } }, "required": [ "event" ] }, { "type": "object", "properties": { "event": { "const": "error" }, "data": {}, "id": { "type": "string" }, "retry": { "type": "number" } }, "required": [ "event" ] } ] } }, "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/RevisionProgress" } } } } } } }, "/v2/revisions/{revision}/build_logs": { "get": { "operationId": "revisions.build_logs", "summary": "Stream build logs", "description": "Stream build logs for a revision.\n\nSupports both Server-Sent Events (SSE) (`Accept: text/event-stream`) and JSON Lines (`Accept: application/x-ndjson`) formats. Use the `Accept` header to specify the desired format.\n\nThe stream remains open during active builds and closes when the build completes.", "tags": [ "revisions" ], "parameters": [ { "name": "revision", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Revision ID (globally unique)" }, { "name": "step", "in": "query", "required": false, "schema": { "enum": [ "preparing", "installing", "building", "deploying" ], "description": "Filter logs by build step" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true, "description": "Filter logs by build step" }, { "name": "timeline", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter logs by timeline slug" }, "allowEmptyValue": true, "allowReserved": true, "description": "Filter logs by timeline slug" } ], "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "oneOf": [ { "type": "object", "properties": { "event": { "const": "message" }, "data": { "$ref": "#/components/schemas/BuildLogEntry" }, "id": { "type": "string" }, "retry": { "type": "number" } }, "required": [ "event", "data" ] }, { "type": "object", "properties": { "event": { "const": "done" }, "data": {}, "id": { "type": "string" }, "retry": { "type": "number" } }, "required": [ "event" ] }, { "type": "object", "properties": { "event": { "const": "error" }, "data": {}, "id": { "type": "string" }, "retry": { "type": "number" } }, "required": [ "event" ] } ] } }, "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/BuildLogEntry" } } } } } } }, "/v2/revisions/{revision}/timelines": { "get": { "operationId": "revisions.timelines", "summary": "Get revision timelines", "description": "Get the timelines (deployment targets) where this revision is active.", "tags": [ "revisions" ], "parameters": [ { "name": "revision", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Revision ID (globally unique)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Timeline" } } } } } } } }, "/v2/layers": { "post": { "operationId": "layers.create", "summary": "Create layer", "description": "Create a new layer.", "tags": [ "layers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "Human-readable layer slug" }, "description": { "type": "string", "description": "Optional description of the layer's purpose" }, "layers": { "type": "array", "items": { "$ref": "#/components/schemas/LayerRefInput" }, "description": "Other layers to include for hierarchical configuration" }, "env_vars": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVarInput" }, "description": "Environment variables for this layer" } }, "required": [ "slug" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layer" } } } } } }, "get": { "operationId": "layers.list", "summary": "List layers", "description": "List all layers in the organization.", "tags": [ "layers" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true, "description": "The search query for filtering" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true, "description": "The pagination cursor" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "allowEmptyValue": true, "allowReserved": true, "description": "The maximum number of items to return" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Layer" } } } } } } } }, "/v2/layers/{layer}": { "get": { "operationId": "layers.get", "summary": "Get layer", "description": "Get a layer by ID or slug.\n\nSlugs cannot contain underscores; IDs always do.", "tags": [ "layers" ], "parameters": [ { "name": "layer", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer ID or slug. Slugs cannot contain underscores; IDs always do." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layer" } } } } } }, "patch": { "operationId": "layers.update", "summary": "Update layer", "description": "Update a layer. This is the key operation for bulk environment variable updates.\n\nAll fields are optional. `env_vars` performs a deep merge with existing variables: update by ID, update by key+contexts match, or create new. Set `delete: true` to remove a variable.\n\nRunning isolates will restart to pick up the new configuration.", "tags": [ "layers" ], "parameters": [ { "name": "layer", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer ID or slug. Slugs cannot contain underscores; IDs always do." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "New layer slug" }, "description": { "type": "string", "description": "New description" }, "layers": { "type": "array", "items": { "$ref": "#/components/schemas/LayerRefInput" }, "description": "Replace all included layers" }, "env_vars": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVarUpdate" }, "description": "Deep merge with existing environment variables" } }, "required": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layer" } } } } } }, "delete": { "operationId": "layers.delete", "summary": "Delete layer", "description": "Returns 409 Conflict if apps still reference this layer.", "tags": [ "layers" ], "parameters": [ { "name": "layer", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer ID or slug. Slugs cannot contain underscores; IDs always do." } ], "responses": { "204": { "description": "OK" } } } }, "/v2/layers/{layer}/apps": { "get": { "operationId": "layers.apps", "summary": "List apps using layer", "description": "List apps that reference this layer.\n\nThe `layer_position` indicates the index in each app's `layers` array.", "tags": [ "layers" ], "parameters": [ { "name": "layer", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer ID or slug. Slugs cannot contain underscores; IDs always do." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true, "description": "The pagination cursor" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "allowEmptyValue": true, "allowReserved": true, "description": "The maximum number of items to return" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LayerAppRef" } } } } } } } } } }