{
  "openapi": "3.1.0",
  "info": {
    "title": "Bezalel Computer API",
    "version": "1.0.0",
    "summary": "Persistent Linux desktops for agents: lifecycle, tasks, direct control, captures, files, previews, and scoped keys.",
    "description": "The API serves the dashboard at `/` and computer operations under `/api/v1`.\n\n## Authentication\n\nEvery `/api/v1` request needs one of:\n\n- `Authorization: Bearer <token>` with the **operator token** (`COMPUTER_API_TOKEN`). Sees every computer and key; the only principal that may register hosts, read diagnostics, or reassign a computer's owner.\n- `Authorization: Bearer bzc_…` with a **scoped API key**. Limited to the computers and permissions it was created with, until it expires or is revoked. Keys cannot create or destroy computers, manage keys, or sign out.\n- The **dashboard session cookie** set by the sign-in routes under `/api/auth`. A signed-in account has full control of the computers and keys it created and sees nothing else.\n\n`Origin` must match the configured public URL and cross-site fetches are refused.\n\n## Conventions\n\n- JSON bodies are limited to 64 KiB and must be objects.\n- Errors are `{ \"error\": { \"code\": \"…\", \"message\": \"…\" } }`. The status is derived from `code`: `invalid_request` / `invalid_path` / `size_mismatch` 400, `unauthorized` 401, `forbidden` 403, `not_found` 404, `busy` / `conflict` / `not_running` / `capacity` / `file_exists` / `file_changed` / `lease_expired` / `missing_disk` 409, `too_large` 413, `rate_limited` 429, `unreachable` / `file_error` / `terminal_failed` 502, `not_configured` / `terminal_recovery` 503, `transfer_timeout` 504, anything else 500.\n- Computer names are 1 to 200 characters of letters, digits, dots, dashes, and underscores, starting with a letter or digit. URL-encode them in paths.\n- Responses send `cache-control: no-store`.\n\n## WebSocket connections\n\n`live`, `browser`, and `terminal` return a one-use ticket URL of the form `wss://<api>/connect/<64 hex>`. Open it within 60 seconds with the same credentials that requested it (bearer header or session cookie). The relay closes after 15 minutes, when the session expires, or when the key is revoked; request a new ticket to reconnect. `live` carries VNC frames (subprotocol `binary`), `browser` carries Chrome DevTools Protocol, and `terminal` carries the shell frames described in the terminal guide.",
    "license": {
      "name": "AGPL-3.0-only",
      "identifier": "AGPL-3.0-only"
    }
  },
  "externalDocs": {
    "description": "Guides and source",
    "url": "https://github.com/boringcomputers/computer/tree/main/docs"
  },
  "servers": [
    {
      "url": "/",
      "description": "This deployment"
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "Unauthenticated liveness."
    },
    {
      "name": "Sign-in",
      "description": "Passwordless dashboard accounts: a magic link or a six-digit email code. Accounts are created on first sign-in. Each address may request at most five emails in ten minutes."
    },
    {
      "name": "Account",
      "description": "What the caller can see about this deployment."
    },
    {
      "name": "API keys",
      "description": "Scoped keys for agents. A key reaches only the computers and permissions it names, for at most 90 days. The token is returned once."
    },
    {
      "name": "Computers",
      "description": "Register, list, and change the power state of desktops."
    },
    {
      "name": "Tasks",
      "description": "Give the configured model an instruction and follow its progress."
    },
    {
      "name": "Control",
      "description": "Watch the desktop, take the mouse and keyboard, open a browser or shell, or run your own computer-use loop."
    },
    {
      "name": "Captures",
      "description": "Screenshots and screen recordings saved with the computer."
    },
    {
      "name": "Workspace files",
      "description": "Transfer files in `/home/desktop/workspace` on a running computer."
    },
    {
      "name": "Previews",
      "description": "Short-lived links to a web app listening on the computer. Requires a preview hostname on the deployment."
    },
    {
      "name": "Operator",
      "description": "Fleet hosts, diagnostics, and ownership transfers. Operator token only."
    },
    {
      "name": "Recording uploads",
      "description": "Used by the computer host to deliver a finished recording. These routes use the per-upload token from the grant, never an API key."
    }
  ],
  "security": [
    {
      "bearer": []
    },
    {
      "session": []
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "health",
        "summary": "Process health",
        "security": [],
        "description": "Answers as soon as the process is serving. Does not contact a host, storage, or the model.",
        "responses": {
          "200": {
            "description": "Serving.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ready",
                    "protocol"
                  ],
                  "properties": {
                    "ready": {
                      "type": "boolean",
                      "const": true
                    },
                    "protocol": {
                      "type": "integer",
                      "const": 1
                    }
                  }
                },
                "example": {
                  "ready": true,
                  "protocol": 1
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/sign-in/magic-link": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "sendMagicLink",
        "summary": "Email a sign-in link",
        "security": [],
        "description": "Sends a one-use link that expires in 10 minutes. The link opens `/magic-link` in the dashboard, which asks for a click and then calls `magic-link/verify`, so mail scanners that follow links do not consume them. Callback URLs, when supplied, must be the deployment's `/` or `/sign-in`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "$ref": "#/components/schemas/Email"
                  },
                  "callbackURL": {
                    "type": "string",
                    "format": "uri"
                  },
                  "errorCallbackURL": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              },
              "example": {
                "email": "alex@example.com",
                "callbackURL": "https://computers.example.com/"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email queued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "status": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/NotConfigured"
          }
        }
      }
    },
    "/api/auth/magic-link/verify": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "verifyMagicLink",
        "summary": "Confirm a sign-in link",
        "security": [],
        "description": "Exchanges the token from the link for a session cookie. The email must match the address the link was sent to. A used or expired link fails without touching a session.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token",
                  "email"
                ],
                "properties": {
                  "token": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{20,256}$"
                  },
                  "email": {
                    "$ref": "#/components/schemas/Email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed in. The `set-cookie` header carries the session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "503": {
            "$ref": "#/components/responses/NotConfigured"
          }
        }
      }
    },
    "/api/auth/email-otp/send-verification-otp": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "sendEmailCode",
        "summary": "Email a six-digit code",
        "security": [],
        "description": "Sends a code that expires in 10 minutes and allows five attempts. `type` must be `sign-in`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "type"
                ],
                "properties": {
                  "email": {
                    "$ref": "#/components/schemas/Email"
                  },
                  "type": {
                    "type": "string",
                    "const": "sign-in"
                  }
                }
              },
              "example": {
                "email": "alex@example.com",
                "type": "sign-in"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email queued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/NotConfigured"
          }
        }
      }
    },
    "/api/auth/sign-in/email-otp": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "signInWithEmailCode",
        "summary": "Sign in with a code",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "otp"
                ],
                "properties": {
                  "email": {
                    "$ref": "#/components/schemas/Email"
                  },
                  "otp": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$"
                  }
                }
              },
              "example": {
                "email": "alex@example.com",
                "otp": "482913"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed in. The `set-cookie` header carries the session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "503": {
            "$ref": "#/components/responses/NotConfigured"
          }
        }
      }
    },
    "/api/auth/get-session": {
      "get": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "getSession",
        "summary": "Current session",
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "The session, or `null` when signed out.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/SessionResult"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/sign-out": {
      "post": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "authSignOut",
        "summary": "Sign out (auth library route)",
        "security": [
          {
            "session": []
          }
        ],
        "description": "Clears the session cookie. The dashboard uses `DELETE /api/session`, which also closes that session's live connections.",
        "responses": {
          "200": {
            "description": "Signed out.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/session": {
      "delete": {
        "tags": [
          "Sign-in"
        ],
        "operationId": "signOut",
        "summary": "Sign out",
        "security": [
          {
            "session": []
          },
          {
            "bearer": []
          }
        ],
        "description": "Ends the dashboard session, clears its cookie, and closes viewer and terminal sockets that belong to it. API keys may not call this.",
        "responses": {
          "200": {
            "description": "Signed out.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "signedIn"
                  ],
                  "properties": {
                    "signedIn": {
                      "type": "boolean",
                      "const": false
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/v1/config": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getConfig",
        "summary": "Deployment configuration",
        "description": "Which optional features are configured, the per-account computer limit, and, for a signed-in session, the account's email.",
        "responses": {
          "200": {
            "description": "Configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Config"
                },
                "example": {
                  "model": "anthropic/claude-sonnet-4.5",
                  "modelConfigured": true,
                  "previewsConfigured": false,
                  "accountsConfigured": true,
                  "computersPerAccount": 5,
                  "account": {
                    "email": "alex@example.com",
                    "name": "alex"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/keys": {
      "get": {
        "tags": [
          "API keys"
        ],
        "operationId": "listKeys",
        "summary": "List keys",
        "description": "A signed-in account sees its own keys; the operator sees every key. Revoked and expired keys are included with their timestamps. Tokens are never returned.",
        "responses": {
          "200": {
            "description": "Keys.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "keys"
                  ],
                  "properties": {
                    "keys": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AccessKey"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "API keys"
        ],
        "operationId": "createKey",
        "summary": "Create a key",
        "description": "Every listed computer must already exist and belong to the caller. Expiry must be in the future and within 90 days. The response is the only time the token is shown.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateKeyInput"
              },
              "example": {
                "name": "research-agent",
                "computers": [
                  "research"
                ],
                "permissions": [
                  "read",
                  "control"
                ],
                "expiresAt": "2026-10-01T00:00:00.000Z"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatedKey"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/keys/{keyId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/KeyId"
        }
      ],
      "delete": {
        "tags": [
          "API keys"
        ],
        "operationId": "revokeKey",
        "summary": "Revoke a key",
        "description": "Takes effect immediately: in-flight requests are aborted, live connections close, and previews and recording grants created with the key are invalidated.",
        "responses": {
          "200": {
            "description": "Revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "revoked"
                  ],
                  "properties": {
                    "revoked": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/computers": {
      "get": {
        "tags": [
          "Computers"
        ],
        "operationId": "listComputers",
        "summary": "List computers",
        "description": "Each computer the caller may read, with its live host status. A computer whose host cannot be reached reports `status: \"unavailable\"`.",
        "responses": {
          "200": {
            "description": "Computers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "computers"
                  ],
                  "properties": {
                    "computers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ComputerListItem"
                      }
                    }
                  }
                },
                "example": {
                  "computers": [
                    {
                      "name": "research",
                      "createdAt": "2026-09-20T13:10:00.000Z",
                      "provisioned": true,
                      "status": "running",
                      "specs": "2 vCPU · 4 GiB",
                      "taskRunning": false
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Computers"
        ],
        "operationId": "createComputer",
        "summary": "Register a computer",
        "description": "Registers the name without starting a VM; `start` provisions it. Names are unique across the deployment. Accounts are limited to `computersPerAccount` from `/api/v1/config`. API keys may not create computers.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "$ref": "#/components/schemas/ComputerName"
                  }
                }
              },
              "example": {
                "name": "research"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Registered.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "name"
                  ],
                  "properties": {
                    "name": {
                      "$ref": "#/components/schemas/ComputerName"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/computers/{name}/status": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Computers"
        ],
        "operationId": "getStatus",
        "summary": "Current host state",
        "description": "Permission: `read`.",
        "requestBody": {
          "$ref": "#/components/requestBodies/Empty"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ComputerInfo"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/Unreachable"
          }
        }
      }
    },
    "/api/v1/computers/{name}/start": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Computers"
        ],
        "operationId": "startComputer",
        "summary": "Start the computer",
        "description": "Creates the VM on first start, then boots it. Permission: `control`.",
        "requestBody": {
          "$ref": "#/components/requestBodies/Empty"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ComputerInfo"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/Unreachable"
          }
        }
      }
    },
    "/api/v1/computers/{name}/stop": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Computers"
        ],
        "operationId": "stopComputer",
        "summary": "Stop the computer",
        "description": "Stops the VM and keeps its disk. Closes live connections and previews. Refused with `busy` while a task runs. Permission: `control`.",
        "requestBody": {
          "$ref": "#/components/requestBodies/Empty"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ComputerInfo"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/Unreachable"
          }
        }
      }
    },
    "/api/v1/computers/{name}/restart": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Computers"
        ],
        "operationId": "restartComputer",
        "summary": "Restart the computer",
        "description": "Refused with `busy` while a task runs. Permission: `control`.",
        "requestBody": {
          "$ref": "#/components/requestBodies/Empty"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ComputerInfo"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/Unreachable"
          }
        }
      }
    },
    "/api/v1/computers/{name}/destroy": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Computers"
        ],
        "operationId": "destroyComputer",
        "summary": "Delete the computer",
        "description": "Permanently deletes the disk and task history. Delete its captures first and stop any task; both fail with `busy`. API keys may not destroy computers.",
        "requestBody": {
          "$ref": "#/components/requestBodies/Empty"
        },
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "boolean"
                },
                "example": true
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/computers/{name}/bash": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Control"
        ],
        "operationId": "runBash",
        "summary": "Run a shell command",
        "description": "Starts the computer if needed, runs the command as the desktop user, and returns its output. Refused with `busy` while a task runs. Permission: `control`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BashInput"
              },
              "example": {
                "command": "ls -la ~/workspace",
                "timeoutSeconds": 60
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Output.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BashResult"
                },
                "example": {
                  "output": "total 8\ndrwx------ 2 desktop desktop 4096 Sep 21 13:10 .\n",
                  "exitCode": 0
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/Unreachable"
          }
        }
      }
    },
    "/api/v1/computers/{name}/task": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Tasks"
        ],
        "operationId": "startTask",
        "summary": "Start a task",
        "description": "Hands the instruction to the configured model, which drives the desktop. Returns immediately; poll `tasks` for progress. Pass `threadId` from an earlier task on the same computer to continue it. One task runs per computer at a time. Permission: `control`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskInput"
              },
              "example": {
                "instruction": "Open the browser and find a recipe for tonight's dinner."
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "503": {
            "$ref": "#/components/responses/NotConfigured"
          }
        }
      }
    },
    "/api/v1/computers/{name}/tasks": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "get": {
        "tags": [
          "Tasks"
        ],
        "operationId": "listTasks",
        "summary": "Task history",
        "description": "The latest 50 tasks, newest first. Permission: `read`.",
        "responses": {
          "200": {
            "description": "Tasks.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "tasks"
                  ],
                  "properties": {
                    "tasks": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Task"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/computers/{name}/cancel": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Tasks"
        ],
        "operationId": "cancelTask",
        "summary": "Cancel the running task",
        "description": "Stops the task and leaves the desktop running. Permission: `control`.",
        "requestBody": {
          "$ref": "#/components/requestBodies/Empty"
        },
        "responses": {
          "200": {
            "description": "Stopped.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "stopped"
                  ],
                  "properties": {
                    "stopped": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/computers/{name}/take_control": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Control"
        ],
        "operationId": "takeControl",
        "summary": "Take manual control",
        "description": "Cancels any task and reserves the mouse and keyboard for the caller. The reservation expires after 15 minutes without a viewer. Keep `controlToken` to undo a failed setup with `release_control`. Permission: `control`.",
        "requestBody": {
          "$ref": "#/components/requestBodies/Empty"
        },
        "responses": {
          "200": {
            "description": "Reserved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "interrupted"
                  ],
                  "properties": {
                    "interrupted": {
                      "type": "boolean"
                    },
                    "controlToken": {
                      "$ref": "#/components/schemas/LeaseToken"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/computers/{name}/release_control": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Control"
        ],
        "operationId": "releaseControl",
        "summary": "Release manual control",
        "description": "Releases the reservation and closes any open terminal. With `controlToken`, releases only if that reservation is still current and returns `resumed: false` otherwise, leaving a newer holder untouched. Permission: `control`.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "controlToken": {
                    "$ref": "#/components/schemas/LeaseToken"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "resumed"
                  ],
                  "properties": {
                    "resumed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/computers/{name}/live": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Control"
        ],
        "operationId": "connectLive",
        "summary": "Live desktop ticket",
        "description": "A one-use WebSocket URL and VNC password for the desktop, or `null` while the viewer is unavailable (for example, right after start). Connect with a VNC client such as noVNC; input is accepted only while the caller holds manual control. Permission: `control`.",
        "requestBody": {
          "$ref": "#/components/requestBodies/Empty"
        },
        "responses": {
          "200": {
            "description": "Ticket, or `null`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ConnectionTicket"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "example": {
                  "websocketUrl": "wss://computers.example.com/connect/3f9a…",
                  "password": "k7Qw…"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/computers/{name}/browser": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Control"
        ],
        "operationId": "connectBrowser",
        "summary": "Browser DevTools ticket",
        "description": "Opens Chromium on the desktop (optionally at `url`) and returns a one-use WebSocket URL relaying the Chrome DevTools Protocol, or `null` when the browser helper is unavailable. Permission: `control`.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BrowserInput"
              },
              "example": {
                "url": "https://example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ticket, or `null`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ConnectionTicket"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/computers/{name}/terminal": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Control"
        ],
        "operationId": "openTerminal",
        "summary": "Interactive shell ticket",
        "description": "Starts a shell on the running computer and returns a one-use WebSocket URL. The shell reserves manual control until it closes; `release_control` closes it. Refused with `busy` while a task runs: call `take_control` first. Permission: `control`.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TerminalSize"
              },
              "example": {
                "rows": 24,
                "cols": 80
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ticket.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectionTicket"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/Unreachable"
          }
        }
      }
    },
    "/api/v1/computers/{name}/lease": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Control"
        ],
        "operationId": "acquireLease",
        "summary": "Acquire an input lease",
        "description": "Reserves the desktop for your own computer-use loop. Pass the returned token on every `action` and end with `release`. Permission: `control`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LeaseInput"
              },
              "example": {
                "ttlSeconds": 300
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lease.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "lease"
                  ],
                  "properties": {
                    "lease": {
                      "$ref": "#/components/schemas/LeaseToken"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/computers/{name}/action": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Control"
        ],
        "operationId": "performAction",
        "summary": "Perform a desktop action",
        "description": "One computer-use action on a 1280 by 720 desktop, authorized by a lease. `screenshot` and `zoom` return an image; the rest return text output. A lost or expired lease fails with `lease_expired`. Permission: `control`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "type": "object",
                    "required": [
                      "lease"
                    ],
                    "properties": {
                      "lease": {
                        "$ref": "#/components/schemas/LeaseToken"
                      }
                    }
                  },
                  {
                    "$ref": "#/components/schemas/DesktopAction"
                  }
                ]
              },
              "examples": {
                "click": {
                  "value": {
                    "lease": "lease_…",
                    "action": "left_click",
                    "coordinate": [
                      200,
                      300
                    ]
                  }
                },
                "type": {
                  "value": {
                    "lease": "lease_…",
                    "action": "type",
                    "text": "hello"
                  }
                },
                "screenshot": {
                  "value": {
                    "lease": "lease_…",
                    "action": "screenshot"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/computers/{name}/release": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Control"
        ],
        "operationId": "releaseLease",
        "summary": "Release an input lease",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lease"
                ],
                "properties": {
                  "lease": {
                    "$ref": "#/components/schemas/LeaseToken"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Released.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "released"
                  ],
                  "properties": {
                    "released": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/computers/{name}/screenshot": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Captures"
        ],
        "operationId": "takeScreenshot",
        "summary": "Save a screenshot",
        "description": "Captures a PNG of the desktop and stores it with the computer. Download it from `/api/v1/files/{id}`. Permission: `control`.",
        "requestBody": {
          "$ref": "#/components/requestBodies/Empty"
        },
        "responses": {
          "200": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capture"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/Unreachable"
          }
        }
      }
    },
    "/api/v1/computers/{name}/recording": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "post": {
        "tags": [
          "Captures"
        ],
        "operationId": "recording",
        "summary": "Start or stop a screen recording",
        "description": "`start` begins an MP4 recording; one recording runs per computer. `stop` asks the host to finish encoding and upload it. Poll `files` until the state is `ready` or `failed`. A recording that is never stopped fails after 15 minutes. Permission: `control`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "action"
                    ],
                    "properties": {
                      "action": {
                        "type": "string",
                        "const": "start"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "action",
                      "id"
                    ],
                    "properties": {
                      "action": {
                        "type": "string",
                        "const": "stop"
                      },
                      "id": {
                        "$ref": "#/components/schemas/Identifier"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "start": {
                  "value": {
                    "action": "start"
                  }
                },
                "stop": {
                  "value": {
                    "action": "stop",
                    "id": "6c3f9d1e-6b1a-4c1f-9a2b-1f0d3c4e5a6b"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Capture state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capture"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/api/v1/computers/{name}/files": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "get": {
        "tags": [
          "Captures"
        ],
        "operationId": "listFiles",
        "summary": "List captures",
        "description": "Screenshots and recordings with their current state. Permission: `read`.",
        "responses": {
          "200": {
            "description": "Captures.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "files"
                  ],
                  "properties": {
                    "files": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Capture"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/files/{fileId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/FileId"
        }
      ],
      "get": {
        "tags": [
          "Captures"
        ],
        "operationId": "downloadFile",
        "summary": "Download a capture",
        "description": "The PNG or MP4 bytes of a `ready` capture. Supports one explicit `Range: bytes=start-end`. Permission: `read` on the capture's computer.",
        "parameters": [
          {
            "name": "Range",
            "in": "header",
            "schema": {
              "type": "string",
              "pattern": "^bytes=\\d+-\\d*$"
            },
            "description": "A single byte range."
          }
        ],
        "responses": {
          "200": {
            "description": "Whole file.",
            "headers": {
              "accept-ranges": {
                "schema": {
                  "type": "string",
                  "const": "bytes"
                }
              },
              "content-disposition": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "206": {
            "description": "The requested range.",
            "headers": {
              "content-range": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "416": {
            "description": "Unsatisfiable range."
          }
        }
      },
      "delete": {
        "tags": [
          "Captures"
        ],
        "operationId": "deleteFile",
        "summary": "Delete a capture",
        "description": "Deletes a `ready` or `failed` capture. Permission: `files:write` on the capture's computer.",
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "deleted"
                  ],
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/computers/{name}/workspace": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        },
        {
          "name": "path",
          "in": "query",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/GuestPath"
          },
          "description": "Relative path inside `/home/desktop/workspace`. No `.`, `..`, or backslashes."
        }
      ],
      "get": {
        "tags": [
          "Workspace files"
        ],
        "operationId": "downloadWorkspaceFile",
        "summary": "Download a workspace file",
        "description": "Streams a regular file from the running computer with chunked framing. Permission: `read`.",
        "responses": {
          "200": {
            "description": "File bytes.",
            "headers": {
              "x-file-size": {
                "schema": {
                  "type": "integer"
                },
                "description": "Exact byte count."
              },
              "content-disposition": {
                "schema": {
                  "type": "string",
                  "const": "attachment"
                }
              }
            },
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/Unreachable"
          },
          "503": {
            "$ref": "#/components/responses/NotConfigured"
          },
          "504": {
            "description": "The transfer exceeded 120 seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Workspace files"
        ],
        "operationId": "uploadWorkspaceFile",
        "summary": "Upload a workspace file",
        "description": "Writes up to 16 MiB to the running computer, creating parent directories. Fails with `file_exists` unless `overwrite=true`. Refused with `busy` while a task runs; `X-Computer-Lease` may prove manual ownership. At most 8 transfers run at once, 2 per computer. Permission: `files:write`.",
        "parameters": [
          {
            "name": "overwrite",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "X-File-Size",
            "in": "header",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 16777216
            },
            "description": "Exact byte count of the body. Must agree with `Content-Length` when present."
          },
          {
            "name": "X-Computer-Lease",
            "in": "header",
            "schema": {
              "$ref": "#/components/schemas/LeaseToken"
            },
            "description": "Optional lease or control token."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Written.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GuestFile"
                },
                "example": {
                  "path": "reports/result.csv",
                  "bytes": 1234
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "description": "Larger than 16 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/Unreachable"
          },
          "503": {
            "$ref": "#/components/responses/NotConfigured"
          },
          "504": {
            "description": "The transfer exceeded 120 seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/computers/{name}/previews": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "get": {
        "tags": [
          "Previews"
        ],
        "operationId": "listPreviews",
        "summary": "List active previews",
        "description": "Permission: `previews:manage`.",
        "responses": {
          "200": {
            "description": "Previews that have not expired.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "previews"
                  ],
                  "properties": {
                    "previews": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Preview"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "$ref": "#/components/responses/NotConfigured"
          }
        }
      },
      "post": {
        "tags": [
          "Previews"
        ],
        "operationId": "createPreview",
        "summary": "Create a preview link",
        "description": "A launch URL on an isolated preview origin for a port the deployment allows. The link expires after `ttlSeconds` (default 15 minutes) and is invalidated when the computer stops or restarts. Permission: `previews:manage`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreviewInput"
              },
              "example": {
                "port": 3000,
                "ttlSeconds": 900
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. Keep `url` private.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewLink"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "503": {
            "$ref": "#/components/responses/NotConfigured"
          }
        }
      }
    },
    "/api/v1/computers/{name}/previews/{previewId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        },
        {
          "name": "previewId",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/PreviewId"
          }
        }
      ],
      "delete": {
        "tags": [
          "Previews"
        ],
        "operationId": "revokePreview",
        "summary": "Revoke a preview",
        "description": "Closes open connections through the preview. Permission: `previews:manage`.",
        "responses": {
          "200": {
            "description": "Revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "revoked"
                  ],
                  "properties": {
                    "revoked": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "$ref": "#/components/responses/NotConfigured"
          }
        }
      }
    },
    "/api/v1/diagnostics": {
      "get": {
        "tags": [
          "Operator"
        ],
        "operationId": "getDiagnostics",
        "summary": "Deployment diagnostics",
        "security": [
          {
            "bearer": []
          }
        ],
        "description": "Checks API storage space, capture storage access, registered host capacity, the model, and previews without starting a VM. Omits credentials, URLs, and paths. Operator token only.",
        "responses": {
          "200": {
            "description": "Checks.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Diagnostics"
                },
                "example": {
                  "checks": [
                    {
                      "id": "api",
                      "status": "pass",
                      "message": "API authentication succeeded."
                    },
                    {
                      "id": "api_storage",
                      "status": "pass",
                      "message": "Free space on the API data filesystem.",
                      "availableBytes": 53687091200
                    },
                    {
                      "id": "host:default",
                      "status": "pass",
                      "message": "Host reachable with capacity."
                    },
                    {
                      "id": "model",
                      "status": "warn",
                      "message": "No model configured."
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/v1/fleet": {
      "get": {
        "tags": [
          "Operator"
        ],
        "operationId": "listHosts",
        "summary": "Registered hosts",
        "security": [
          {
            "bearer": []
          }
        ],
        "description": "Hosts with their live capacity and the count of recent unmet placement demand. Host tokens are omitted. Operator token only.",
        "responses": {
          "200": {
            "description": "Hosts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "hosts",
                    "demand"
                  ],
                  "properties": {
                    "hosts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FleetHost"
                      }
                    },
                    "demand": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Operator"
        ],
        "operationId": "registerHost",
        "summary": "Register or update a host",
        "security": [
          {
            "bearer": []
          }
        ],
        "description": "Verifies the host answers a capacity request before saving its credentials. An existing host's origin cannot change. `draining: true` excludes it from new placement while its computers stay available. Operator token only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id",
                  "origin",
                  "token",
                  "draining"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "origin": {
                    "type": "string",
                    "format": "uri"
                  },
                  "token": {
                    "type": "string",
                    "description": "The host's private management token."
                  },
                  "draining": {
                    "type": "boolean"
                  }
                }
              },
              "example": {
                "id": "host-two",
                "origin": "https://host-two.internal.example",
                "token": "…",
                "draining": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "registered",
                    "draining"
                  ],
                  "properties": {
                    "registered": {
                      "type": "string"
                    },
                    "draining": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/Unreachable"
          }
        }
      }
    },
    "/api/v1/computers/{name}/owner": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ComputerName"
        }
      ],
      "put": {
        "tags": [
          "Operator"
        ],
        "operationId": "assignOwner",
        "summary": "Hand a computer to an account",
        "security": [
          {
            "bearer": []
          }
        ],
        "description": "Moves a computer that predates accounts (or belongs to another account) to the account that has signed in with `email`. Keys that reached the computer are revoked; the new owner issues their own. Operator token only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "$ref": "#/components/schemas/Email"
                  }
                }
              },
              "example": {
                "email": "alex@example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reassigned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "name",
                    "owner",
                    "revokedKeys"
                  ],
                  "properties": {
                    "name": {
                      "$ref": "#/components/schemas/ComputerName"
                    },
                    "owner": {
                      "$ref": "#/components/schemas/Email"
                    },
                    "revokedKeys": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "$ref": "#/components/responses/NotConfigured"
          }
        }
      }
    },
    "/computer/recordings/upload/{fileId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/FileId"
        }
      ],
      "post": {
        "tags": [
          "Recording uploads"
        ],
        "operationId": "grantRecordingUpload",
        "summary": "Request an upload grant",
        "security": [
          {
            "uploadToken": []
          }
        ],
        "description": "Called by the host after `recording` stop. Fixes the byte count and returns the content URL. The grant expires 15 minutes after the recording started and cannot replace a completed file.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "bytes"
                ],
                "properties": {
                  "bytes": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Grant.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "url"
                  ],
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Where to `PUT` the MP4 body."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/computer/recordings/content/{fileId}/{grantHash}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/FileId"
        },
        {
          "name": "grantHash",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        }
      ],
      "put": {
        "tags": [
          "Recording uploads"
        ],
        "operationId": "uploadRecordingContent",
        "summary": "Upload recording bytes",
        "security": [],
        "description": "The MP4 body must start with an MP4 header and match the granted byte count exactly.",
        "requestBody": {
          "required": true,
          "content": {
            "video/mp4": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stored; the capture becomes `ready`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "uploaded"
                  ],
                  "properties": {
                    "uploaded": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "The operator token from `COMPUTER_API_TOKEN`, or a scoped key `bzc_<id>_<secret>` from `POST /api/v1/keys`."
      },
      "session": {
        "type": "apiKey",
        "in": "cookie",
        "name": "better-auth.session_token",
        "description": "The dashboard session set by the sign-in routes."
      },
      "uploadToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "The per-recording upload token the API gave the host when the recording started."
      }
    },
    "parameters": {
      "ComputerName": {
        "name": "name",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/ComputerName"
        },
        "description": "The computer's name, URL-encoded."
      },
      "KeyId": {
        "name": "keyId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/KeyId"
        }
      },
      "FileId": {
        "name": "fileId",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/Identifier"
        },
        "description": "A capture ID from `files`, `screenshot`, or `recording`."
      }
    },
    "requestBodies": {
      "Empty": {
        "required": false,
        "description": "Send `{}` or no body.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": false
            },
            "example": {}
          }
        }
      }
    },
    "responses": {
      "ComputerInfo": {
        "description": "Host state.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ComputerInfo"
            },
            "example": {
              "name": "research",
              "provisioned": true,
              "status": "running",
              "specs": "2 vCPU · 4 GiB"
            }
          }
        }
      },
      "InvalidRequest": {
        "description": "The body, query, or headers are invalid (`invalid_request`, `invalid_path`, `size_mismatch`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "invalid_request",
                "message": "Send a JSON object."
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, invalid, expired, or revoked credentials (`unauthorized`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "The access key is invalid, expired, or revoked."
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The credential exists but lacks the permission or role (`forbidden`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "This key requires the control permission."
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "No such computer, key, file, or route, or one the caller may not see (`not_found`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Computer not found."
              }
            }
          }
        }
      },
      "Conflict": {
        "description": "The operation conflicts with current state (`busy`, `conflict`, `not_running`, `capacity`, `file_exists`, `lease_expired`, `missing_disk`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "busy",
                "message": "Stop the task before changing this computer."
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests (`rate_limited`). A `retry-after` header may be present.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Too many sign-in emails for this address. Try again later."
              }
            }
          }
        }
      },
      "Unreachable": {
        "description": "The computer host did not answer or answered badly (`unreachable`, `file_error`, `terminal_failed`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unreachable",
                "message": "The computer host is unavailable."
              }
            }
          }
        }
      },
      "NotConfigured": {
        "description": "The feature is not configured on this deployment (`not_configured`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_configured",
                "message": "Private previews are not configured on this deployment."
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "A stable machine-readable code."
              },
              "message": {
                "type": "string",
                "description": "Safe to show to a person."
              }
            }
          }
        }
      },
      "Email": {
        "type": "string",
        "format": "email",
        "maxLength": 254
      },
      "ComputerName": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,199}$",
        "examples": [
          "research"
        ]
      },
      "Identifier": {
        "type": "string",
        "pattern": "^[a-f0-9-]{36}$",
        "description": "A UUID."
      },
      "KeyId": {
        "type": "string",
        "pattern": "^[a-f0-9]{32}$"
      },
      "PreviewId": {
        "type": "string",
        "pattern": "^[a-f0-9]{32}$"
      },
      "LeaseToken": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "SessionResult": {
        "type": "object",
        "properties": {
          "session": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "email": {
                "$ref": "#/components/schemas/Email"
              },
              "name": {
                "type": "string"
              }
            }
          }
        }
      },
      "Config": {
        "type": "object",
        "required": [
          "model",
          "modelConfigured",
          "previewsConfigured",
          "accountsConfigured",
          "computersPerAccount"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "The configured model name, or a placeholder when none is configured."
          },
          "modelConfigured": {
            "type": "boolean"
          },
          "previewsConfigured": {
            "type": "boolean"
          },
          "accountsConfigured": {
            "type": "boolean"
          },
          "computersPerAccount": {
            "type": "integer",
            "minimum": 1
          },
          "account": {
            "type": "object",
            "description": "Present for a dashboard session.",
            "required": [
              "email"
            ],
            "properties": {
              "email": {
                "$ref": "#/components/schemas/Email"
              },
              "name": {
                "type": "string"
              }
            }
          }
        }
      },
      "ComputerInfo": {
        "type": "object",
        "required": [
          "name",
          "provisioned"
        ],
        "properties": {
          "name": {
            "$ref": "#/components/schemas/ComputerName"
          },
          "provisioned": {
            "type": "boolean",
            "description": "Whether a VM disk exists."
          },
          "status": {
            "type": "string",
            "description": "Host-reported state such as `running`, `stopped`, `starting`, or `unavailable`."
          },
          "specs": {
            "type": "string",
            "description": "Human-readable machine size."
          }
        }
      },
      "ComputerListItem": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ComputerInfo"
          },
          {
            "type": "object",
            "required": [
              "createdAt",
              "taskRunning"
            ],
            "properties": {
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "taskRunning": {
                "type": "boolean"
              }
            }
          }
        ]
      },
      "TaskInput": {
        "type": "object",
        "required": [
          "instruction"
        ],
        "properties": {
          "instruction": {
            "type": "string",
            "minLength": 1,
            "maxLength": 16000
          },
          "threadId": {
            "$ref": "#/components/schemas/Identifier"
          }
        }
      },
      "Task": {
        "type": "object",
        "required": [
          "id",
          "computer",
          "instruction",
          "model",
          "state",
          "createdAt"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Identifier"
          },
          "computer": {
            "$ref": "#/components/schemas/ComputerName"
          },
          "instruction": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "running",
              "completed",
              "stopped",
              "failed"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "threadId": {
            "$ref": "#/components/schemas/Identifier"
          },
          "result": {
            "type": "string"
          },
          "steps": {
            "type": "integer",
            "minimum": 0
          },
          "error": {
            "type": "string"
          }
        }
      },
      "Capture": {
        "type": "object",
        "required": [
          "id",
          "computer",
          "kind",
          "state",
          "createdAt",
          "bytes"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Identifier"
          },
          "computer": {
            "$ref": "#/components/schemas/ComputerName"
          },
          "kind": {
            "type": "string",
            "enum": [
              "screenshot",
              "recording"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "recording",
              "uploading",
              "ready",
              "failed"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "bytes": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "BashInput": {
        "type": "object",
        "required": [
          "command"
        ],
        "properties": {
          "command": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32000
          },
          "timeoutSeconds": {
            "type": "integer",
            "minimum": 1,
            "maximum": 600
          }
        }
      },
      "BashResult": {
        "type": "object",
        "required": [
          "output",
          "exitCode"
        ],
        "properties": {
          "output": {
            "type": "string"
          },
          "exitCode": {
            "type": "integer"
          },
          "truncated": {
            "type": "boolean"
          }
        }
      },
      "ConnectionTicket": {
        "type": "object",
        "required": [
          "websocketUrl"
        ],
        "properties": {
          "websocketUrl": {
            "type": "string",
            "format": "uri",
            "description": "One-use `wss://…/connect/<ticket>` URL, valid for 60 seconds."
          },
          "password": {
            "type": "string",
            "description": "VNC password, for `live` only."
          }
        }
      },
      "TerminalSize": {
        "type": "object",
        "properties": {
          "rows": {
            "type": "integer",
            "minimum": 2,
            "maximum": 500
          },
          "cols": {
            "type": "integer",
            "minimum": 2,
            "maximum": 500
          }
        }
      },
      "BrowserInput": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "`http` or `https`, without credentials."
          }
        }
      },
      "LeaseInput": {
        "type": "object",
        "required": [
          "ttlSeconds"
        ],
        "properties": {
          "ttlSeconds": {
            "type": "integer",
            "minimum": 1,
            "maximum": 900
          }
        }
      },
      "Coordinate": {
        "type": "array",
        "prefixItems": [
          {
            "type": "integer",
            "minimum": 0,
            "maximum": 1279
          },
          {
            "type": "integer",
            "minimum": 0,
            "maximum": 719
          }
        ],
        "minItems": 2,
        "maxItems": 2,
        "description": "`[x, y]` on a 1280 by 720 desktop."
      },
      "KeyChord": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9_]+(?:\\+[a-zA-Z0-9_]+)*$",
        "maxLength": 200,
        "description": "An xdotool key name, or several joined with `+` such as `ctrl+shift+t`."
      },
      "DesktopAction": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "action"
            ],
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "screenshot",
                  "cursor_position",
                  "left_mouse_down",
                  "left_mouse_up"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "action",
              "region"
            ],
            "properties": {
              "action": {
                "type": "string",
                "const": "zoom"
              },
              "region": {
                "type": "array",
                "prefixItems": [
                  {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 1279
                  },
                  {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 719
                  },
                  {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1280
                  },
                  {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 720
                  }
                ],
                "minItems": 4,
                "maxItems": 4,
                "description": "`[x0, y0, x1, y1]` on the 1280 by 720 desktop, with `x1 > x0` and `y1 > y0`."
              }
            }
          },
          {
            "type": "object",
            "required": [
              "action",
              "coordinate"
            ],
            "properties": {
              "action": {
                "type": "string",
                "const": "mouse_move"
              },
              "coordinate": {
                "$ref": "#/components/schemas/Coordinate"
              },
              "text": {
                "$ref": "#/components/schemas/KeyChord"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "action"
            ],
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "left_click",
                  "right_click",
                  "middle_click",
                  "double_click",
                  "triple_click"
                ]
              },
              "coordinate": {
                "$ref": "#/components/schemas/Coordinate"
              },
              "text": {
                "$ref": "#/components/schemas/KeyChord",
                "description": "Keys held during the click."
              }
            }
          },
          {
            "type": "object",
            "required": [
              "action",
              "start_coordinate",
              "coordinate"
            ],
            "properties": {
              "action": {
                "type": "string",
                "const": "left_click_drag"
              },
              "start_coordinate": {
                "$ref": "#/components/schemas/Coordinate"
              },
              "coordinate": {
                "$ref": "#/components/schemas/Coordinate"
              },
              "text": {
                "$ref": "#/components/schemas/KeyChord"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "action",
              "text"
            ],
            "properties": {
              "action": {
                "type": "string",
                "const": "type"
              },
              "text": {
                "type": "string",
                "maxLength": 16000
              }
            }
          },
          {
            "type": "object",
            "required": [
              "action",
              "text"
            ],
            "properties": {
              "action": {
                "type": "string",
                "const": "key"
              },
              "text": {
                "$ref": "#/components/schemas/KeyChord"
              },
              "repeat": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100
              }
            }
          },
          {
            "type": "object",
            "required": [
              "action",
              "text",
              "duration"
            ],
            "properties": {
              "action": {
                "type": "string",
                "const": "hold_key"
              },
              "text": {
                "$ref": "#/components/schemas/KeyChord"
              },
              "duration": {
                "type": "number",
                "minimum": 0,
                "maximum": 30,
                "description": "Seconds."
              }
            }
          },
          {
            "type": "object",
            "required": [
              "action",
              "scroll_direction",
              "scroll_amount"
            ],
            "properties": {
              "action": {
                "type": "string",
                "const": "scroll"
              },
              "coordinate": {
                "$ref": "#/components/schemas/Coordinate"
              },
              "scroll_direction": {
                "type": "string",
                "enum": [
                  "up",
                  "down",
                  "left",
                  "right"
                ]
              },
              "scroll_amount": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100
              },
              "text": {
                "$ref": "#/components/schemas/KeyChord"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "action"
            ],
            "properties": {
              "action": {
                "type": "string",
                "const": "wait"
              },
              "duration": {
                "type": "number",
                "minimum": 0,
                "maximum": 30,
                "description": "Seconds."
              }
            }
          }
        ],
        "discriminator": {
          "propertyName": "action"
        }
      },
      "ActionResult": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "imageBase64"
            ],
            "properties": {
              "imageBase64": {
                "type": "string",
                "contentEncoding": "base64",
                "contentMediaType": "image/png"
              },
              "width": {
                "type": "integer"
              },
              "height": {
                "type": "integer"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "output"
            ],
            "properties": {
              "output": {
                "type": "string"
              }
            }
          }
        ]
      },
      "GuestPath": {
        "type": "string",
        "maxLength": 1024,
        "description": "Relative path of at most 32 segments, each 1 to 255 bytes, none `.` or `..`.",
        "examples": [
          "reports/result.csv"
        ]
      },
      "GuestFile": {
        "type": "object",
        "required": [
          "path",
          "bytes"
        ],
        "properties": {
          "path": {
            "$ref": "#/components/schemas/GuestPath"
          },
          "bytes": {
            "type": "integer",
            "minimum": 0,
            "maximum": 16777216
          }
        }
      },
      "PreviewInput": {
        "type": "object",
        "required": [
          "port"
        ],
        "properties": {
          "port": {
            "type": "integer",
            "minimum": 1024,
            "maximum": 65535
          },
          "ttlSeconds": {
            "type": "integer",
            "minimum": 1,
            "maximum": 900
          }
        }
      },
      "Preview": {
        "type": "object",
        "required": [
          "id",
          "name",
          "port",
          "expiresAt"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/PreviewId"
          },
          "name": {
            "$ref": "#/components/schemas/ComputerName"
          },
          "port": {
            "type": "integer"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PreviewLink": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Preview"
          },
          {
            "type": "object",
            "required": [
              "url"
            ],
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "description": "`https://p-<id>.<preview host>/_bezalel/launch#token=…`. Opening it sets the preview cookie."
              }
            }
          }
        ]
      },
      "KeyPermission": {
        "type": "string",
        "enum": [
          "read",
          "control",
          "files:write",
          "previews:manage"
        ],
        "description": "`read`: status, tasks, files. `control`: power, tasks, input, live, browser, terminal, captures. `files:write`: workspace uploads and capture deletion. `previews:manage`: preview links."
      },
      "CreateKeyInput": {
        "type": "object",
        "required": [
          "name",
          "computers",
          "permissions",
          "expiresAt"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "computers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComputerName"
            },
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true
          },
          "permissions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KeyPermission"
            },
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "In the future, within 90 days."
          }
        }
      },
      "AccessKey": {
        "type": "object",
        "required": [
          "id",
          "name",
          "computers",
          "permissions",
          "createdAt",
          "expiresAt",
          "revokedAt",
          "lastUsedAt"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/KeyId"
          },
          "name": {
            "type": "string"
          },
          "computers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComputerName"
            }
          },
          "permissions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KeyPermission"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "revokedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastUsedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "CreatedKey": {
        "type": "object",
        "required": [
          "key",
          "token"
        ],
        "properties": {
          "key": {
            "$ref": "#/components/schemas/AccessKey"
          },
          "token": {
            "type": "string",
            "pattern": "^bzc_[a-f0-9]{32}_[a-f0-9]{64}$",
            "description": "Shown once. Send it as `Authorization: Bearer`."
          }
        }
      },
      "DiagnosticCheck": {
        "type": "object",
        "required": [
          "id",
          "status",
          "message"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "`api`, `api_storage`, `capture_storage`, `fleet`, `host:<id>`, `model`, or `previews`."
          },
          "status": {
            "type": "string",
            "enum": [
              "pass",
              "warn",
              "fail"
            ]
          },
          "message": {
            "type": "string"
          },
          "availableBytes": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "Diagnostics": {
        "type": "object",
        "required": [
          "checks"
        ],
        "properties": {
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiagnosticCheck"
            }
          },
          "previewBaseUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "FleetHost": {
        "type": "object",
        "required": [
          "id",
          "origin",
          "draining"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "origin": {
            "type": "string",
            "format": "uri"
          },
          "draining": {
            "type": "boolean"
          },
          "capacity": {
            "type": "object",
            "description": "The host's capacity report, present when reachable.",
            "additionalProperties": true
          },
          "unavailable": {
            "type": "boolean",
            "const": true,
            "description": "Present when the host did not answer."
          }
        }
      }
    }
  }
}
