openapi: 3.1.0
info:
  title: "TaskCloud API"
  version: "1.0.0-beta.1"
  summary: Persistent cloud computers (Firecracker microVMs) for AI agents. Pay only while they work.
  description: |
    REST API for `TaskCloud` sandboxes. Every sandbox is a full Firecracker microVM with its own
    kernel, Ubuntu 24.04, root, systemd and Docker, a persistent disk, pause/resume with a RAM
    snapshot, fork, exec, files, public HTTPS ports, SSH and an optional desktop with a
    computer-use API.

    **Status:** private beta. Latency numbers in this document are targets, not guarantees.

    ## Conventions

    - **Base URL:** `https://api.task.cloud/v1`. JSON request and response bodies use `snake_case`.
    - **Auth:** `Authorization: Bearer <api_key>` (the scheme name is case-insensitive). Keys look like
      `taskcloud_sk_...` and carry scopes (see `ApiKeyScope`). A missing scope returns `403 insufficient_scope`.
    - **Console sessions:** the web console signs users in (`/auth/*`) and calls every operation with the
      `taskcloud_session` cookie instead of a key. The session acts in its current organization with the scopes of
      the user's `Role` (a missing one returns `403 forbidden`, `details.reason = insufficient_role`). Non-GET
      requests with a session need `X-CSRF-Token` (the `taskcloud_csrf` cookie value) and an allowed `Origin`
      (`403 forbidden`, `details.reason = csrf_failed | origin_not_allowed`). Operations marked
      `x-session-only` accept only a session (`403`, `details.reason = session_required` for API keys).
      Sessions slide for 30 days of inactivity and end at most 90 days after sign-in. In an organization that
      requires two-factor authentication, a session of a user without 2FA gets `403 forbidden`
      (`details.reason = two_factor_required`) on organization operations; `/me` operations keep working. An API
      key created by a person never exceeds that person's current role in the organization (its scopes are
      intersected with the role's at every request) and stops working (`401`) when the person leaves.
      Per-IP limits and the IP addresses in sessions and audit records use the real client address: the API
      honours `X-Forwarded-For` only from its configured trusted proxies.
    - **IDs** are prefixed strings: `sbx_` sandbox, `cmd_` command, `snap_` snapshot, `tpl_` template,
      `whk_` webhook, `evt_` event, `key_` API key, `dsk_` desktop stream, `pty_` PTY session.
    - **Timestamps** are RFC 3339 UTC strings.
    - **Errors** always use the `Error` envelope: `{"error": {"code", "message", "retryable", "status", "request_id", "details"}}`.
      Branch on `code`, not on `message`. Retry only when `retryable` is `true`, honouring `Retry-After`.
    - **Pagination** is cursor based: `?limit=` (1–100, default 20) and `?cursor=`. List responses are
      `{"data": [...], "has_more": bool, "next_cursor": string|null}`. Webhooks, API keys, SSH keys, members and
      invitations (unpaginated before 2026-11) default to 100 items per page instead of 20.
    - **Idempotency:** `POST` requests that create resources accept an `Idempotency-Key` header
      (up to 255 chars, kept for 24 h). Replaying the same key with a different body returns
      `409 idempotency_conflict`. Responses that contain a secret shown once (`createApiKey`,
      `createWebhook`) are never stored: replaying such a request returns `409 idempotency_conflict`
      with `details.reason = "secret_not_replayable"` and `details.resource_id` of the resource the first
      request created (rotate it to get a new secret). A replayed response has `Idempotent-Replayed: true`, its
      own `X-Request-Id`, and, for an error, the same ID in `error.request_id`.
    - **Rate limits:** every response carries `RateLimit-Policy` and `RateLimit` headers
      (IETF draft `draft-ietf-httpapi-ratelimit-headers`), including `401` and unknown routes; requests without a
      valid key count against a per-client-IP `default` quota. Lifecycle calls (create, resume, fork) carry an
      additional `starts` policy. Exceeding a limit returns `429 rate_limited` with `Retry-After`.
    - **Request IDs:** every response has `X-Request-Id`; include it when contacting support.
    - **Unknown fields** in a JSON body are rejected with `400 invalid_request` and `details.field`.
    - **Common errors:** every operation documents `401`, `403` (scoped operations), `429`, `400` (operations
      with a body) and `404` (operations addressing a resource by ID) through shared `components/responses`.
    - **Wake on request:** calls that need a running VM (exec, files, desktop, ports traffic, SSH) on a
      `paused` sandbox resume it transparently. The call waits for the resume (target p95 < 800 ms).
      Pass `auto_resume=false` (query) to get `409 sandbox_paused` instead.
  contact:
    name: "TaskCloud support"
    url: "https://task.cloud/support"
    email: "support@task.cloud"
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.task.cloud/v1
    description: Production (EU)
security:
  - bearerAuth: []
  - cookieAuth: []
tags:
  - name: Sandboxes
    description: Create, inspect and manage the lifecycle of sandboxes.
  - name: Exec
    description: Run commands (sync, background, SSE stream) and interactive PTY sessions.
  - name: Files
    description: Read, write, list, upload, download and watch files inside a sandbox.
  - name: Networking
    description: Public HTTPS URLs for ports and SSH access.
  - name: Desktop
    description: Desktop streaming (KasmVNC), screenshots and computer-use input.
  - name: Snapshots
    description: Point-in-time RAM + disk snapshots of a sandbox.
  - name: Templates
    description: Reusable starting points built from an OCI image or a snapshot.
  - name: Webhooks
    description: Signed event notifications.
  - name: Usage
    description: Metered usage, cost and account limits.
  - name: API keys
    description: Scoped API keys.
  - name: Account
    description: Account, plan and spend limits.
  - name: Auth
    description: Console sign-in (magic link, GitHub) and sign-out; cookie sessions.
  - name: Me
    description: The signed-in console user, their organizations and sessions.
  - name: Members
    description: Organization members, roles and invitations.
  - name: Billing
    description: Self-service billing for the console (plan, invoices, checkout, portal).

paths:
  # ---------------------------------------------------------------- Sandboxes
  /sandboxes:
    get:
      tags: [Sandboxes]
      operationId: listSandboxes
      summary: List sandboxes
      x-required-scopes: [sandboxes:read]
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: state
          in: query
          description: Filter by state. Repeat the parameter for several states.
          schema:
            type: array
            items: { $ref: "#/components/schemas/SandboxState" }
          style: form
          explode: true
        - name: label
          in: query
          description: Filter by label, `key=value`. Repeat for AND.
          schema:
            type: array
            items: { type: string, example: "customer=acme" }
          style: form
          explode: true
        - name: name_prefix
          in: query
          schema: { type: string }
        - name: template_id
          in: query
          schema: { type: string }
      responses:
        "200":
          description: A page of sandboxes.
          headers:
            RateLimit-Policy: { $ref: "#/components/headers/RateLimit-Policy" }
            RateLimit: { $ref: "#/components/headers/RateLimit" }
            X-Request-Id: { $ref: "#/components/headers/X-Request-Id" }
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/Sandbox" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Sandboxes]
      operationId: createSandbox
      summary: Create a sandbox
      description: |
        Creates a sandbox from a template (default `base`), a snapshot, or an OCI image.
        Exactly one of `template`, `snapshot_id` or `image` may be set; when none is set, `template: "base"` is used.

        - With `wait: true` (default) the call returns `201` once the sandbox is `running`
          (target p95 < 500 ms from a template).
        - With `wait: false` it returns `202` immediately with state `creating`.
        - With `priority: "batch"` the sandbox may be held in state `queued` until capacity is
          available and is billed at the batch rate (−50%). Batch requests always return `202`.
        - When no host can take the sandbox the call returns `503 capacity_unavailable`; when the chosen
          host is unreachable it returns `503 service_unavailable`. Both are retryable, carry `Retry-After`,
          and no sandbox is created.
      x-required-scopes: [sandboxes:write]
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateSandboxRequest" }
            examples:
              fromTemplate:
                summary: From the base template
                value: { template: base, size: default, name: "user-42", labels: { customer: acme } }
              fromOfficialTemplate:
                summary: From an official template (Python 3.12 + data stack)
                value: { template: python }
              desktop:
                summary: Desktop template, never pauses
                value: { template: desktop, size: default, always_on: true }
              fromImage:
                summary: From an OCI image
                value: { image: { ref: "ghcr.io/acme/agent-env:1.4" }, size: large }
              batch:
                summary: Batch priority, may queue
                value: { template: base, priority: batch, wait: false }
      responses:
        "201":
          description: Sandbox is running.
          headers:
            Location: { schema: { type: string }, description: URL of the new sandbox. }
            RateLimit-Policy: { $ref: "#/components/headers/RateLimit-Policy" }
            RateLimit: { $ref: "#/components/headers/RateLimit" }
            X-Request-Id: { $ref: "#/components/headers/X-Request-Id" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Sandbox" }
        "202":
          description: Sandbox accepted; state is `creating` or `queued`.
          headers:
            Location: { schema: { type: string } }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Sandbox" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "503": { $ref: "#/components/responses/ServiceUnavailable" }

  /sandboxes/{sandbox_id}:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    get:
      tags: [Sandboxes]
      operationId: getSandbox
      summary: Get a sandbox
      description: Returns the sandbox. Does not wake a paused sandbox.
      x-required-scopes: [sandboxes:read]
      responses:
        "200":
          description: The sandbox.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Sandbox" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    patch:
      tags: [Sandboxes]
      operationId: updateSandbox
      summary: Update a sandbox
      description: |
        Updates mutable settings: `name`, `labels`, `auto_pause`, `always_on`, `ttl_seconds`.
        Setting `always_on: true` disables auto-pause and switches the sandbox to the always-on
        monthly price (`default` size only).
      x-required-scopes: [sandboxes:write]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateSandboxRequest" }
            examples:
              idleTimeout:
                summary: Pause after 15 minutes idle
                value: { auto_pause: { enabled: true, idle_timeout_seconds: 900 } }
              alwaysOn:
                value: { always_on: true }
      responses:
        "200":
          description: Updated sandbox.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Sandbox" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Sandboxes]
      operationId: deleteSandbox
      summary: Delete a sandbox
      description: |
        Permanently deletes the sandbox, its disk and its automatic pause snapshot. Named snapshots
        created with `POST /sandboxes/{sandbox_id}/snapshots` are kept. Returns `202`; the sandbox moves
        to `deleting` and then `deleted`, and a `sandbox.deleted` webhook is sent.
      x-required-scopes: [sandboxes:write]
      responses:
        "202":
          description: Deletion accepted.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Sandbox" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/pause:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Sandboxes]
      operationId: pauseSandbox
      summary: Pause a sandbox
      description: |
        Snapshots RAM and disk at the same instant and stops the VM. Processes, open windows and
        sessions survive. Compute billing stops when the state becomes `paused`.
        Pausing an already paused sandbox is a no-op (`200`).

        Concurrent calls: a call that finds the sandbox `pausing` waits for that pause. If the pause does
        not end in `paused` (the host refused it, or a resume won the race), the call returns
        `409 sandbox_busy` (retryable) at once; it never pauses the sandbox later. A call that finds it
        `creating` or `resuming` returns `409 sandbox_busy`. When the sandbox host is unreachable the call
        returns `503 service_unavailable` (retryable) and the sandbox stays `running`.
      x-required-scopes: [sandboxes:write]
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WaitRequest" }
      responses:
        "200":
          description: Sandbox is `paused` (when `wait` is true).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Sandbox" }
        "202":
          description: Pause started; state is `pausing`.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Sandbox" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "503": { $ref: "#/components/responses/ServiceUnavailable" }

  /sandboxes/{sandbox_id}/resume:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Sandboxes]
      operationId: resumeSandbox
      summary: Resume a sandbox
      description: |
        Restores RAM and disk from the pause snapshot (target p95 < 800 ms). You rarely need this call:
        any exec, file, desktop, port or SSH request wakes a paused sandbox automatically.
        Resuming a running sandbox is a no-op (`200`).

        A call that finds the sandbox `pausing` waits for that pause to end and then resumes it (or returns
        `200` if the pause failed and the sandbox is still `running`). When the host is unreachable or busy,
        the call returns `503 service_unavailable` or `409 sandbox_busy` (both retryable) and the sandbox
        stays `paused`. A snapshot written by another Firecracker version is resumed on a compatible host;
        without one the call returns `503 capacity_unavailable` with `details.reason = "incompatible_host"`
        and the sandbox stays `paused` with `pause_reason: incompatible_host`.
      x-required-scopes: [sandboxes:write]
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WaitRequest" }
      responses:
        "200":
          description: Sandbox is `running` (when `wait` is true).
          headers:
            RateLimit-Policy: { $ref: "#/components/headers/RateLimit-Policy" }
            RateLimit: { $ref: "#/components/headers/RateLimit" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Sandbox" }
        "202":
          description: Resume started; state is `resuming`.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Sandbox" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "503": { $ref: "#/components/responses/ServiceUnavailable" }

  /sandboxes/{sandbox_id}/fork:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Sandboxes]
      operationId: forkSandbox
      summary: Fork a sandbox
      description: |
        Creates a new sandbox from the current state of this one, **including memory** (target p95 < 2 s).
        A running source is paused for a few hundred milliseconds while its RAM and disk are captured, then
        continues. A paused source is forked from its pause snapshot. The fork gets its own IP, network
        namespace and copy-on-write disk; changes in the fork never affect the source.
        The fork has the same size as the source.

        **Bulk fork.** `count` creates that many forks from a single capture of the source, for RL rollouts
        and evals. The maximum depends on the account (`GET /limits` → `bulk_fork.max_count`): Free 2,
        Starter 10, Team 50, Enterprise 100; higher limits on request (up to 500). New Free accounts that are
        not verified yet (first 7 days, no card or GitHub verification) cannot bulk fork (`max_count` 1).
        Admission is all or nothing and atomic (parallel requests cannot together exceed the quota):

        - `count` above the account's limit: `403 forbidden` with `details.reason = "fork_count_limit"`,
          `details.limit` and `details.requested` (not retryable; ask for a higher limit);
        - the concurrency quota cannot take every fork: `409 concurrency_limit_reached`;
        - the capacity next to the source cannot take every fork: `503 capacity_unavailable` (retryable);
        - `count` outside 1–500: `400 invalid_request`.

        In every failure case nothing is created. With `count` omitted or `1`
        the response is the single `Sandbox` (unchanged); with `count > 1` it is `{"data": [Sandbox, ...]}`
        with exactly `count` items. `201` when every fork is running, `202` otherwise (`wait: false`, or
        `priority: batch`, where the forks wait in `queued` and are admitted as capacity frees up).
        `name`, `labels`, `env`, `metadata`, `auto_pause`, `priority` and `ttl_seconds` apply to every fork.
      x-required-scopes: [sandboxes:write]
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ForkSandboxRequest" }
      responses:
        "201":
          description: "The new sandbox (running), or with `count > 1` the list of new sandboxes (all running)."
          headers:
            RateLimit-Policy: { $ref: "#/components/headers/RateLimit-Policy" }
            RateLimit: { $ref: "#/components/headers/RateLimit" }
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Sandbox"
                  - $ref: "#/components/schemas/ForkSandboxesResponse"
        "202":
          description: "Fork accepted (when `wait` is false or `priority` is `batch`); with `count > 1` the list of new sandboxes."
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Sandbox"
                  - $ref: "#/components/schemas/ForkSandboxesResponse"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/PaymentRequired" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "503": { $ref: "#/components/responses/ServiceUnavailable" }

  # ---------------------------------------------------------------- Exec
  /sandboxes/{sandbox_id}/exec:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/AutoResume"
    post:
      tags: [Exec]
      operationId: execCommand
      summary: Run a command
      description: |
        Runs a command in the sandbox. Three modes:

        - **Sync** (default): waits for the command to exit and returns `200` with `ExecResult`.
          `timeout_seconds` defaults to 60, maximum 600. Captured output is limited to 8 MiB per stream
          (`truncated: true` when cut).
        - **Background** (`background: true`): returns `202` with a `Command` immediately. No time limit.
          Follow it with `GET .../commands/{command_id}` or `GET .../commands/{command_id}/stream`.
        - **Stream** (`stream: true` or `Accept: text/event-stream`): returns `200` with a Server-Sent Events
          stream of `ExecEvent`s (`start`, `stdout`, `stderr`, `exit`, `error`), without output limits.

        At least 10 commands can run concurrently per sandbox. Commands run through `/bin/bash -lc`
        when `command` is a string; pass `args` to execute a program directly without a shell.
      x-required-scopes: [exec]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ExecRequest" }
            examples:
              sync:
                value: { command: "npm test", cwd: "/home/user/app", timeout_seconds: 300 }
              background:
                value: { command: "npm run dev -- --port 3000", cwd: "/home/user/app", background: true }
              stream:
                value: { command: "pip install -r requirements.txt", stream: true }
      responses:
        "200":
          description: |
            Sync result (`application/json`) or SSE stream (`text/event-stream`). For a stream, each event has
            `event: <type>` and `data: <ExecEvent JSON>`. Base64 is used for non-UTF-8 output (`encoding: base64`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ExecResult" }
            text/event-stream:
              schema:
                type: string
                description: SSE stream; each `data:` line is an `ExecEvent`.
              example: |
                event: start
                data: {"type":"start","command_id":"cmd_9fz2cq4kd7mw","pid":4211}

                event: stdout
                data: {"type":"stdout","command_id":"cmd_9fz2cq4kd7mw","data":"added 312 packages\n"}

                event: exit
                data: {"type":"exit","command_id":"cmd_9fz2cq4kd7mw","exit_code":0,"duration_ms":8123}
        "202":
          description: Background command started.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Command" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "408": { $ref: "#/components/responses/Timeout" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "502": { $ref: "#/components/responses/BadGateway" }

  /sandboxes/{sandbox_id}/commands:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    get:
      tags: [Exec]
      operationId: listCommands
      summary: List commands
      description: Lists recent commands (running and finished in the last 7 days), newest first.
      x-required-scopes: [exec]
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: state
          in: query
          schema: { $ref: "#/components/schemas/CommandState" }
      responses:
        "200":
          description: A page of commands.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/Command" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/commands/{command_id}:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/CommandId"
    get:
      tags: [Exec]
      operationId: getCommand
      summary: Get a command
      x-required-scopes: [exec]
      responses:
        "200":
          description: The command.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Command" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/commands/{command_id}/stream:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/CommandId"
    get:
      tags: [Exec]
      operationId: streamCommand
      summary: Attach to a command's output (SSE)
      description: |
        Streams `ExecEvent`s for a running or finished command. Output produced before you attached is
        replayed first (up to 8 MiB per stream). Reconnect with the standard `Last-Event-ID` header to resume.
      x-required-scopes: [exec]
      parameters:
        - name: Last-Event-ID
          in: header
          required: false
          schema: { type: string }
      responses:
        "200":
          description: SSE stream of `ExecEvent`.
          content:
            text/event-stream:
              schema: { type: string }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/commands/{command_id}/stdin:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/CommandId"
    post:
      tags: [Exec]
      operationId: writeCommandStdin
      summary: Write to a command's stdin
      x-required-scopes: [exec]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [data]
              properties:
                data: { type: string, description: Bytes to write. }
                encoding: { type: string, enum: [utf8, base64], default: utf8 }
                eof: { type: boolean, default: false, description: Close stdin after writing. }
      responses:
        "204": { description: Written. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/commands/{command_id}/kill:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/CommandId"
    post:
      tags: [Exec]
      operationId: killCommand
      summary: Send a signal to a command
      x-required-scopes: [exec]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                signal:
                  type: string
                  enum: [SIGTERM, SIGKILL, SIGINT, SIGHUP, SIGQUIT, SIGUSR1, SIGUSR2]
                  default: SIGTERM
      responses:
        "200":
          description: Signal delivered.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Command" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/pty:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Exec]
      operationId: createPtySession
      summary: Create an interactive PTY session
      description: |
        Starts a pseudo-terminal and returns a short-lived WebSocket URL (`websocket_url`, valid for 60 s
        until first connect). Connect with any WebSocket client; no `Authorization` header is needed
        because the URL carries a signed token, so it can be opened from a browser.

        **The token is single-use.** A second connect with the same URL gets `401`. To reconnect to the
        same session, either call `getPtySession` for a fresh `websocket_url`, or present the reconnect
        ticket returned with the first `101` response: header `X-TaskCloud-Pty-Ticket` (send it back in the
        same header) and an `HttpOnly; SameSite=Strict` cookie `__Host-taskcloud_pty_<pty_id>` that same-site
        browsers send automatically. A ticket opens only its own session, lives for the session's
        `idle_timeout_seconds`, and every reconnect returns a fresh one.

        **WebSocket protocol** (`wss://api.task.cloud/v1/sandboxes/{sandbox_id}/pty/{pty_id}/connect?token=...`):

        - **Binary frames, client → server:** raw bytes written to the terminal (keystrokes).
        - **Binary frames, server → client:** raw terminal output (UTF-8 with ANSI escapes).
        - **Text frames** carry JSON control messages:
          - client → server: `{"type":"resize","cols":120,"rows":40}`, `{"type":"signal","signal":"SIGINT"}`, `{"type":"ping"}`
          - server → client: `{"type":"ready","pty_id":"pty_..."}`, `{"type":"exit","exit_code":0}`, `{"type":"pong"}`, `{"type":"error","error":{...Error}}`
        - The session ends when the process exits or after `idle_timeout_seconds` without traffic.
          An open PTY counts as activity, so it prevents auto-pause.
        - Reconnect to a live session within 60 s of a drop with `GET .../pty/{pty_id}` to get a fresh URL;
          up to 64 KiB of missed output is replayed.
      x-required-scopes: [exec]
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreatePtyRequest" }
      responses:
        "201":
          description: PTY session created.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PtySession" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "503": { $ref: "#/components/responses/ServiceUnavailable" }

  /sandboxes/{sandbox_id}/pty/{pty_id}:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - name: pty_id
        in: path
        required: true
        schema: { type: string, example: pty_7hc2zq5mxk3d }
    get:
      tags: [Exec]
      operationId: getPtySession
      summary: Get a PTY session (and a fresh connect URL)
      x-required-scopes: [exec]
      responses:
        "200":
          description: PTY session.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PtySession" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Exec]
      operationId: closePtySession
      summary: Close a PTY session
      x-required-scopes: [exec]
      responses:
        "204": { description: Closed. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/pty/{pty_id}/connect:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - name: pty_id
        in: path
        required: true
        schema: { type: string }
      - name: token
        in: query
        required: false
        description: Single-use signed token from `PtySession.websocket_url` (required unless a reconnect ticket is sent).
        schema: { type: string }
      - name: X-TaskCloud-Pty-Ticket
        in: header
        required: false
        description: Reconnect ticket from the `101` response of an earlier connect to this session (see `createPtySession`).
        schema: { type: string }
    get:
      tags: [Exec]
      operationId: connectPty
      summary: PTY WebSocket endpoint
      description: WebSocket upgrade endpoint. See `createPtySession` for the frame protocol.
      security: []
      responses:
        "101": { description: Switching Protocols (WebSocket). }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }

  # ---------------------------------------------------------------- Files
  /sandboxes/{sandbox_id}/files:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/AutoResume"
    get:
      tags: [Files]
      operationId: listFiles
      summary: List a directory
      x-required-scopes: [files:read]
      parameters:
        - $ref: "#/components/parameters/Path"
        - name: recursive
          in: query
          schema: { type: boolean, default: false }
        - name: max_depth
          in: query
          description: Maximum depth when `recursive` is true.
          schema: { type: integer, minimum: 1, maximum: 32, default: 8 }
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: Directory entries.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/FileEntry" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Files]
      operationId: deleteFile
      summary: Delete a file or directory
      x-required-scopes: [files:write]
      parameters:
        - $ref: "#/components/parameters/Path"
        - name: recursive
          in: query
          description: Required to delete a non-empty directory.
          schema: { type: boolean, default: false }
      responses:
        "204": { description: Deleted. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/files/content:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/AutoResume"
      - $ref: "#/components/parameters/Path"
    get:
      tags: [Files]
      operationId: readFile
      summary: Read a file
      description: |
        Returns the raw file bytes as a stream (`application/octet-stream`). Supports `Range` requests.
        Up to 1 GiB per request; use `POST .../files/download-url` for larger files.
      x-required-scopes: [files:read]
      parameters:
        - name: Range
          in: header
          required: false
          schema: { type: string, example: "bytes=0-1023" }
      responses:
        "200":
          description: File content.
          headers:
            Content-Length: { schema: { type: integer } }
            ETag: { schema: { type: string } }
            Last-Modified: { schema: { type: string } }
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        "206":
          description: Partial content.
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "416": { $ref: "#/components/responses/RangeNotSatisfiable" }
        "429": { $ref: "#/components/responses/RateLimited" }
    put:
      tags: [Files]
      operationId: writeFile
      summary: Write a file
      description: |
        Creates or replaces a file with the raw request body (streamed, up to 1 GiB). Parent directories are
        created by default. Use `If-Match` with an `ETag` for optimistic concurrency.
      x-required-scopes: [files:write]
      parameters:
        - name: mode
          in: query
          description: Octal permission bits for a new file.
          schema: { type: string, default: "0644", pattern: "^0?[0-7]{3}$" }
        - name: create_parents
          in: query
          schema: { type: boolean, default: true }
        - name: owner
          in: query
          description: Owner user of a new file.
          schema: { type: string, default: user }
        - name: If-Match
          in: header
          required: false
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema: { type: string, format: binary }
      responses:
        "200":
          description: Written.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/FileEntry" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "412": { $ref: "#/components/responses/PreconditionFailed" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "507": { $ref: "#/components/responses/InsufficientStorage" }

  /sandboxes/{sandbox_id}/files/stat:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/AutoResume"
      - $ref: "#/components/parameters/Path"
    get:
      tags: [Files]
      operationId: statFile
      summary: Get file metadata
      x-required-scopes: [files:read]
      responses:
        "200":
          description: Metadata.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/FileEntry" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/files/mkdir:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Files]
      operationId: makeDirectory
      summary: Create a directory
      x-required-scopes: [files:write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [path]
              properties:
                path: { type: string }
                parents: { type: boolean, default: true }
                mode: { type: string, default: "0755" }
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/FileEntry" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "507": { $ref: "#/components/responses/InsufficientStorage" }

  /sandboxes/{sandbox_id}/files/move:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Files]
      operationId: moveFile
      summary: Move or rename a file or directory
      x-required-scopes: [files:write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [from, to]
              properties:
                from: { type: string }
                to: { type: string }
                overwrite: { type: boolean, default: false }
      responses:
        "200":
          description: Moved.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/FileEntry" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "507": { $ref: "#/components/responses/InsufficientStorage" }

  /sandboxes/{sandbox_id}/files/upload:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/AutoResume"
    post:
      tags: [Files]
      operationId: uploadFiles
      summary: Upload files (multipart)
      description: |
        Uploads one or more files with `multipart/form-data` into the directory `path`. Each file part's
        filename may contain sub-directories (`src/index.ts`). Send a `.tar` or `.tar.gz` part with
        `extract=true` to unpack an archive. Up to 1 GiB per request.
      x-required-scopes: [files:write]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [path, files]
              properties:
                path: { type: string, description: Destination directory. }
                extract: { type: boolean, default: false }
                files:
                  type: array
                  items: { type: string, format: binary }
      responses:
        "200":
          description: Uploaded entries.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/FileEntry" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "507": { $ref: "#/components/responses/InsufficientStorage" }

  /sandboxes/{sandbox_id}/files/download:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/AutoResume"
      - $ref: "#/components/parameters/Path"
    get:
      tags: [Files]
      operationId: downloadArchive
      summary: Download a directory as an archive
      x-required-scopes: [files:read]
      parameters:
        - name: format
          in: query
          schema: { type: string, enum: [tar.gz, tar, zip], default: tar.gz }
      responses:
        "200":
          description: Archive stream.
          content:
            application/gzip:
              schema: { type: string, format: binary }
            application/x-tar:
              schema: { type: string, format: binary }
            application/zip:
              schema: { type: string, format: binary }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/files/upload-url:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Files]
      operationId: createUploadUrl
      summary: Create a signed upload URL
      description: Returns a pre-signed URL that accepts a single `PUT` of up to 10 GiB without an API key (the URL is consumed by the first `PUT`; a second one gets `401`).
      x-required-scopes: [files:write]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SignedUrlRequest" }
      responses:
        "201":
          description: Signed URL.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SignedUrl" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/files/download-url:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Files]
      operationId: createDownloadUrl
      summary: Create a signed download URL
      description: Returns a pre-signed URL for a single file (any size up to 10 GiB) usable without an API key.
      x-required-scopes: [files:read]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SignedUrlRequest" }
      responses:
        "201":
          description: Signed URL.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SignedUrl" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/files/watch:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/AutoResume"
      - $ref: "#/components/parameters/Path"
    get:
      tags: [Files]
      operationId: watchFiles
      summary: Watch a path for changes (SSE)
      description: |
        Streams `FileEvent`s (`created`, `modified`, `deleted`, `renamed`) as Server-Sent Events.
        An open watch does **not** count as activity, so it does not prevent auto-pause; the stream
        stays open across pause/resume and resumes delivering events after the VM wakes.
      x-required-scopes: [files:read]
      parameters:
        - name: recursive
          in: query
          schema: { type: boolean, default: true }
        - name: include_hidden
          in: query
          schema: { type: boolean, default: false }
      responses:
        "200":
          description: SSE stream; each `data:` line is a `FileEvent`.
          content:
            text/event-stream:
              schema: { type: string }
              example: |
                event: modified
                data: {"type":"modified","path":"/home/user/app/src/index.ts","is_dir":false,"timestamp":"2026-11-09T12:00:01Z"}
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ---------------------------------------------------------------- Networking
  /sandboxes/{sandbox_id}/ports:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    get:
      tags: [Networking]
      operationId: listPorts
      summary: List exposed ports
      x-required-scopes: [sandboxes:read]
      responses:
        "200":
          description: Exposed ports.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/Port" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Networking]
      operationId: exposePort
      summary: Expose a port on a public HTTPS URL
      description: |
        Publishes a port at `https://<short_id>-<port>.taskhost.cloud` (HTTP/1.1, HTTP/2 and WebSocket), where `<short_id>` is the
        sandbox ID without the `sbx_` prefix (`_` is not valid in hostnames).
        `visibility: private` requires a valid access token (header `X-Sandbox-Token` or query
        `sandbox_token`) or an API key with `sandboxes:read`; `public` is open to anyone.
        A request to the URL of a paused sandbox wakes it (wake on request).
        Exposing an already exposed port updates its settings.
        Sandbox URLs (ports, desktop, SSH gateway) use the separate domain `taskhost.cloud`, never the
        API domain `task.cloud`, so sandbox content is never same-site with the API.
      x-required-scopes: [sandboxes:write]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ExposePortRequest" }
      responses:
        "201":
          description: Port exposed.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Port" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/ports/{port}:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - name: port
        in: path
        required: true
        schema: { type: integer, minimum: 1, maximum: 65535 }
    delete:
      tags: [Networking]
      operationId: unexposePort
      summary: Remove a public URL
      x-required-scopes: [sandboxes:write]
      responses:
        "204": { description: Removed. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/access-tokens:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Networking]
      operationId: createAccessToken
      summary: Create an access token for private ports
      description: |
        Issues a short-lived token that grants HTTP access to this sandbox's **private** ports only.
        Give it to your end user's browser instead of an API key.
      x-required-scopes: [sandboxes:write]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                ttl_seconds: { type: integer, minimum: 60, maximum: 86400, default: 3600 }
                ports:
                  type: array
                  description: Restrict to these ports. Default is all private ports.
                  items: { type: integer }
      responses:
        "201":
          description: Token.
          content:
            application/json:
              schema:
                type: object
                required: [token, expires_at]
                properties:
                  token: { type: string, example: "sbt_4fQ...", description: Shown once. }
                  expires_at: { type: string, format: date-time }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/ssh:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Networking]
      operationId: createSshAccess
      summary: Get SSH access
      description: |
        Returns connection details for the SSH gateway `ssh.taskhost.cloud:22`. Authenticate either with a
        public key registered via `POST /ssh-keys` (or passed in `public_key` here, valid for `ttl_seconds`),
        or with the one-time `password` returned when `public_key` is omitted and no account key exists.
        Connecting to a paused sandbox wakes it. SSH supports port forwarding (`-L`, `-R`), `scp`, `sftp`
        and VS Code / Cursor Remote-SSH.
      x-required-scopes: [ssh]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                public_key: { type: string, description: "OpenSSH public key, e.g. `ssh-ed25519 AAAA...`." }
                ttl_seconds: { type: integer, minimum: 60, maximum: 604800, default: 3600 }
                user: { type: string, default: user, description: Linux user to log in as. }
      responses:
        "201":
          description: SSH access.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SshAccess" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /ssh-keys:
    get:
      tags: [Networking]
      operationId: listSshKeys
      summary: List account SSH keys
      x-required-scopes: [ssh]
      parameters:
        - $ref: "#/components/parameters/LimitDefault100"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: SSH keys.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/SshKey" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Networking]
      operationId: addSshKey
      summary: Add an account SSH key
      description: The key can log in to every sandbox of the account through the SSH gateway.
      x-required-scopes: [ssh]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [public_key]
              properties:
                name: { type: string, maxLength: 120 }
                public_key: { type: string }
      responses:
        "201":
          description: Added.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SshKey" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /ssh-keys/{ssh_key_id}:
    parameters:
      - name: ssh_key_id
        in: path
        required: true
        schema: { type: string }
    delete:
      tags: [Networking]
      operationId: deleteSshKey
      summary: Remove an account SSH key
      x-required-scopes: [ssh]
      responses:
        "204": { description: Removed. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ---------------------------------------------------------------- Desktop
  /sandboxes/{sandbox_id}/desktop:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Desktop]
      operationId: createDesktopStream
      summary: Create a desktop stream URL
      description: |
        Returns a signed URL that opens the sandbox desktop (KasmVNC, 1920x1080) in a browser, at
        `https://<short_id>-desktop.taskhost.cloud/?token=...`. Requires a desktop-capable template
        (e.g. `desktop`) and size `default` or larger. Opening the URL wakes a paused sandbox.
        An active viewer counts as activity (no auto-pause); an idle desktop with no viewers pauses normally.
        The URL can be embedded in an `<iframe>`.
      x-required-scopes: [desktop]
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateDesktopStreamRequest" }
      responses:
        "201":
          description: Stream URL.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DesktopStream" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
    get:
      tags: [Desktop]
      operationId: listDesktopStreams
      summary: List active desktop stream URLs
      x-required-scopes: [desktop]
      responses:
        "200":
          description: Stream URLs that have not expired or been revoked.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/DesktopStream" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/desktop/{stream_id}:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - name: stream_id
        in: path
        required: true
        schema: { type: string, example: dsk_7zab3kq2mxw5 }
    delete:
      tags: [Desktop]
      operationId: revokeDesktopStream
      summary: Revoke a desktop stream URL
      description: Invalidates the URL and disconnects any viewer using it.
      x-required-scopes: [desktop]
      responses:
        "204": { description: Revoked. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/screenshot:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/AutoResume"
    get:
      tags: [Desktop]
      operationId: takeScreenshot
      summary: Take a screenshot
      description: |
        Captures the desktop (target p95 < 300 ms). Returns the image directly (`image/png` or `image/jpeg`),
        or a JSON object with base64 data when `Accept: application/json`.
        Coordinates for `POST /input` are always in full-screen pixels (1920x1080 by default); if you request
        `scale` < 1, divide the coordinates the model returns by `scale` before sending input, or pass
        `coordinate_scale` to `POST /input`.
      x-required-scopes: [desktop]
      parameters:
        - name: format
          in: query
          schema: { type: string, enum: [png, jpeg], default: png }
        - name: quality
          in: query
          description: JPEG quality.
          schema: { type: integer, minimum: 1, maximum: 100, default: 80 }
        - name: scale
          in: query
          description: Downscale factor applied to the output image.
          schema: { type: number, minimum: 0.1, maximum: 1, default: 1 }
        - name: region
          in: query
          description: "Crop to `x0,y0,x1,y1` in full-screen pixels (useful for a computer-use `zoom` action)."
          schema: { type: string, example: "0,0,960,540" }
        - name: include_cursor
          in: query
          schema: { type: boolean, default: true }
      responses:
        "200":
          description: Screenshot.
          headers:
            X-Screen-Width: { schema: { type: integer }, description: Full screen width in pixels. }
            X-Screen-Height: { schema: { type: integer } }
          content:
            image/png:
              schema: { type: string, format: binary }
            image/jpeg:
              schema: { type: string, format: binary }
            application/json:
              schema: { $ref: "#/components/schemas/Screenshot" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/input:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
      - $ref: "#/components/parameters/AutoResume"
    post:
      tags: [Desktop]
      operationId: sendInput
      summary: Send mouse and keyboard input
      description: |
        Executes one or more input actions in order (a batch). Action names and fields follow the
        Anthropic computer-use tool (`mouse_move`, `left_click`, `double_click`, `right_click`, `scroll`,
        `type`, `key`, ... with `coordinate: [x, y]`, `text`, `scroll_direction`, `scroll_amount`), so a
        model's tool call can be forwarded as `{ "action": <tool name>, ...input }`.
        If an action fails, later actions are not executed and are reported with `status: "skipped"`.
        Set `return_screenshot: true` to get a screenshot taken after the last action.
      x-required-scopes: [desktop]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/InputRequest" }
            example:
              actions:
                - { action: left_click, coordinate: [640, 412] }
                - { action: type, text: "hello world" }
                - { action: key, text: "Return" }
              return_screenshot: true
      responses:
        "200":
          description: Results per action.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/InputResult" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/cursor:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    get:
      tags: [Desktop]
      operationId: getCursorPosition
      summary: Get the cursor position
      x-required-scopes: [desktop]
      responses:
        "200":
          description: Cursor position in full-screen pixels.
          content:
            application/json:
              schema:
                type: object
                required: [x, y]
                properties:
                  x: { type: integer }
                  y: { type: integer }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ---------------------------------------------------------------- Snapshots
  /sandboxes/{sandbox_id}/snapshots:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    post:
      tags: [Snapshots]
      operationId: createSnapshot
      summary: Create a named snapshot
      description: |
        Captures RAM and disk of the sandbox at one instant. A running sandbox is paused briefly
        (typically a few hundred ms) and then continues; a paused sandbox is snapshotted from its pause state.
        Named snapshots outlive the sandbox and can be used with `POST /sandboxes` (`snapshot_id`) or turned into
        a template.
      x-required-scopes: [snapshots:write]
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, maxLength: 120 }
                labels: { $ref: "#/components/schemas/Labels" }
                memory:
                  type: boolean
                  default: true
                  description: Include RAM. `false` makes a disk-only snapshot (smaller; restores with a boot).
      responses:
        "201":
          description: Snapshot (state `ready`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Snapshot" }
        "202":
          description: Snapshot accepted (state `creating`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Snapshot" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /snapshots:
    get:
      tags: [Snapshots]
      operationId: listSnapshots
      summary: List snapshots
      x-required-scopes: [snapshots:read]
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: sandbox_id
          in: query
          schema: { type: string }
      responses:
        "200":
          description: A page of snapshots.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/Snapshot" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /snapshots/{snapshot_id}:
    parameters:
      - name: snapshot_id
        in: path
        required: true
        schema: { type: string, example: snap_3kd7wq2mzn5x }
    get:
      tags: [Snapshots]
      operationId: getSnapshot
      summary: Get a snapshot
      x-required-scopes: [snapshots:read]
      responses:
        "200":
          description: The snapshot.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Snapshot" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Snapshots]
      operationId: deleteSnapshot
      summary: Delete a snapshot
      description: Fails with `409 snapshot_in_use` while a template references the snapshot.
      x-required-scopes: [snapshots:write]
      responses:
        "204": { description: Deleted. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ---------------------------------------------------------------- Templates
  /templates:
    get:
      tags: [Templates]
      operationId: listTemplates
      summary: List templates
      description: |
        Lists the official templates and your own. Official templates (`official: true`) are the curated
        gallery built and smoke-tested by TaskCloud: `base`, `python`, `node`, `browser`, `coding-agent`, `jupyter`,
        `desktop` (see https://task.cloud/docs/templates.html). Use `owner=builtin` to list only the gallery.
        Create a sandbox from one with `template: "<name>"` (e.g. `python`) or its ID (`tpl_python`).
      x-required-scopes: [templates:read]
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: owner
          in: query
          schema: { type: string, enum: [all, builtin, account], default: all }
      responses:
        "200":
          description: A page of templates.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/Template" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Templates]
      operationId: createTemplate
      summary: Create a template
      description: |
        Creates a template from **either** an OCI/Docker image (`image`) **or** a snapshot (`snapshot_id`).

        - From an image: we pull the image, convert it into a VM root filesystem (systemd and our guest agent
          are added), boot it, run `start_command` if set, wait for `ready_check`, and take a RAM snapshot.
          Build logs: `GET /templates/{template_id}/logs`.
        - From a snapshot: the template is ready immediately and starts with that exact RAM and disk state.

        Creating a template with an existing `name` adds a new version; sandboxes created with
        `template: "<name>"` use the latest `ready` version, or pin one with `"<name>:<version>"`.
      x-required-scopes: [templates:write]
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateTemplateRequest" }
            examples:
              fromImage:
                value:
                  name: agent-env
                  image: { ref: "ghcr.io/acme/agent-env:1.4", registry_auth: { username: acme-bot, password: "ghp_..." } }
                  start_command: "/usr/local/bin/warmup.sh"
                  ready_check: { command: "curl -sf localhost:8080/health", timeout_seconds: 120 }
                  size: default
              fromSnapshot:
                value: { name: python-preinstalled, snapshot_id: snap_3kd7wq2mzn5x }
      responses:
        "201":
          description: Template created from a snapshot (state `ready`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Template" }
        "202":
          description: Build started (state `building`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Template" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /templates/{template_id}:
    parameters:
      - $ref: "#/components/parameters/TemplateId"
    get:
      tags: [Templates]
      operationId: getTemplate
      summary: Get a template
      x-required-scopes: [templates:read]
      responses:
        "200":
          description: The template.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Template" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Templates]
      operationId: deleteTemplate
      summary: Delete a template
      description: Existing sandboxes created from the template are not affected.
      x-required-scopes: [templates:write]
      responses:
        "204": { description: Deleted. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /templates/{template_id}/logs:
    parameters:
      - $ref: "#/components/parameters/TemplateId"
    get:
      tags: [Templates]
      operationId: getTemplateLogs
      summary: Get template build logs
      description: "Plain text, or an SSE stream while building when `Accept: text/event-stream`."
      x-required-scopes: [templates:read]
      responses:
        "200":
          description: Build log.
          content:
            text/plain:
              schema: { type: string }
            text/event-stream:
              schema: { type: string }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ---------------------------------------------------------------- Webhooks
  /webhooks:
    get:
      tags: [Webhooks]
      operationId: listWebhooks
      summary: List webhook endpoints
      x-required-scopes: [webhooks:manage]
      parameters:
        - $ref: "#/components/parameters/LimitDefault100"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: Webhook endpoints.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/Webhook" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Webhooks]
      operationId: createWebhook
      summary: Create a webhook endpoint
      description: |
        Registers an HTTPS endpoint (port 443, public IP, no redirects). Up to 10 endpoints per account.
        The response contains the signing `secret` (`whsec_...`) **once**.
      x-required-scopes: [webhooks:manage]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateWebhookRequest" }
      responses:
        "201":
          description: Webhook created (includes `secret`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/WebhookWithSecret" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /webhooks/{webhook_id}:
    parameters:
      - $ref: "#/components/parameters/WebhookId"
    get:
      tags: [Webhooks]
      operationId: getWebhook
      summary: Get a webhook endpoint
      x-required-scopes: [webhooks:manage]
      responses:
        "200":
          description: The webhook.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Webhook" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    patch:
      tags: [Webhooks]
      operationId: updateWebhook
      summary: Update a webhook endpoint
      x-required-scopes: [webhooks:manage]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url: { type: string, format: uri }
                events:
                  type: array
                  items: { $ref: "#/components/schemas/WebhookEventType" }
                enabled: { type: boolean }
                description: { type: string, maxLength: 200 }
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Webhook" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Webhooks]
      operationId: deleteWebhook
      summary: Delete a webhook endpoint
      x-required-scopes: [webhooks:manage]
      responses:
        "204": { description: Deleted. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /webhooks/{webhook_id}/rotate-secret:
    parameters:
      - $ref: "#/components/parameters/WebhookId"
    post:
      tags: [Webhooks]
      operationId: rotateWebhookSecret
      summary: Rotate the signing secret
      description: |
        Issues a new secret. For 24 hours deliveries are signed with **both** secrets
        (two `v1=` entries in `Webhook-Signature`), so you can roll over without downtime.
      x-required-scopes: [webhooks:manage]
      responses:
        "200":
          description: New secret.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/WebhookWithSecret" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /webhooks/{webhook_id}/test:
    parameters:
      - $ref: "#/components/parameters/WebhookId"
    post:
      tags: [Webhooks]
      operationId: testWebhook
      summary: Send a test event
      description: Sends a signed `webhook.test` event and returns the delivery result.
      x-required-scopes: [webhooks:manage]
      responses:
        "200":
          description: Delivery attempt.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/WebhookDelivery" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /webhooks/{webhook_id}/deliveries:
    parameters:
      - $ref: "#/components/parameters/WebhookId"
    get:
      tags: [Webhooks]
      operationId: listWebhookDeliveries
      summary: List recent deliveries
      description: Delivery attempts from the last 30 days.
      x-required-scopes: [webhooks:manage]
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of deliveries.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/WebhookDelivery" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ---------------------------------------------------------------- Usage & account
  /usage:
    get:
      tags: [Usage]
      operationId: getUsage
      summary: Get usage and cost
      description: |
        Metered usage for a period (default: the current billing period), optionally grouped.
        Seconds are metered per second. Costs are in USD before plan credit is applied; `totals.credit_applied_usd`
        and `totals.amount_due_usd` show the effect of plan credit.
      x-required-scopes: [usage:read]
      parameters:
        - name: from
          in: query
          schema: { type: string, format: date-time }
        - name: to
          in: query
          schema: { type: string, format: date-time }
        - name: group_by
          in: query
          schema: { type: string, enum: [none, sandbox, day, size, label, template], default: none }
        - name: label_key
          in: query
          description: Label key to group by when `group_by=label` (e.g. `customer`).
          schema: { type: string }
        - name: sandbox_id
          in: query
          schema: { type: string }
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: Usage report.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UsageReport" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /sandboxes/{sandbox_id}/usage:
    parameters:
      - $ref: "#/components/parameters/SandboxId"
    get:
      tags: [Usage]
      operationId: getSandboxUsage
      summary: Get usage for one sandbox
      x-required-scopes: [usage:read]
      parameters:
        - name: from
          in: query
          schema: { type: string, format: date-time }
        - name: to
          in: query
          schema: { type: string, format: date-time }
      responses:
        "200":
          description: Usage for the sandbox.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UsageItem" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /limits:
    get:
      tags: [Usage]
      operationId: getLimits
      summary: Get account limits and current consumption
      x-required-scopes: [usage:read]
      responses:
        "200":
          description: Limits.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Limits" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /account:
    get:
      tags: [Account]
      operationId: getAccount
      summary: Get the account
      x-required-scopes: [account:read]
      responses:
        "200":
          description: Account.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Account" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /account/spend-limit:
    put:
      tags: [Account]
      operationId: setSpendLimit
      summary: Set the monthly spend limit
      description: |
        When metered spend in the billing period reaches `monthly_limit_usd`, new sandboxes are rejected
        with `402 spend_limit_reached` and running sandboxes are paused (`on_limit: pause_running`) or kept
        running (`on_limit: block_new`). Notifications are emailed at each `alert_thresholds` percentage.
        Set `monthly_limit_usd: null` to remove the limit.
      x-required-scopes: [account:manage]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SpendLimit" }
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SpendLimit" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ---------------------------------------------------------------- API keys
  /api-keys:
    get:
      tags: [API keys]
      operationId: listApiKeys
      summary: List API keys
      x-required-scopes: [api_keys:manage]
      parameters:
        - $ref: "#/components/parameters/LimitDefault100"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: API keys (secrets never included).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/ApiKey" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [API keys]
      operationId: createApiKey
      summary: Create an API key
      description: |
        Creates a key with explicit `scopes` or a `preset`. A key can never have more scopes than the key that
        created it. The `secret` is returned **once**. Optionally restrict the key to specific sandboxes or to
        sandboxes carrying given labels (e.g. one key per end user).
      x-required-scopes: [api_keys:manage]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateApiKeyRequest" }
            example:
              name: end-user-42
              preset: full-sandbox
              restrict: { labels: { user: "42" } }
              expires_in_days: 30
      responses:
        "201":
          description: Key created (includes `secret`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiKeyWithSecret" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /api-keys/{api_key_id}:
    parameters:
      - name: api_key_id
        in: path
        required: true
        schema: { type: string, example: key_6qe2mz4kxb7w }
    get:
      tags: [API keys]
      operationId: getApiKey
      summary: Get an API key
      x-required-scopes: [api_keys:manage]
      responses:
        "200":
          description: The key.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiKey" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [API keys]
      operationId: revokeApiKey
      summary: Revoke an API key
      description: Takes effect within 10 seconds.
      x-required-scopes: [api_keys:manage]
      responses:
        "204": { description: Revoked. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /api-keys/{api_key_id}/rotate:
    parameters:
      - name: api_key_id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [API keys]
      operationId: rotateApiKey
      summary: Rotate an API key
      description: Issues a new secret with the same settings. The old secret stays valid for `grace_period_seconds`.
      x-required-scopes: [api_keys:manage]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                grace_period_seconds: { type: integer, minimum: 0, maximum: 604800, default: 3600 }
      responses:
        "200":
          description: Rotated key (includes new `secret`).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiKeyWithSecret" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ---------------------------------------------------------------- Console: auth (cookie sessions)
  /auth/magic-link:
    post:
      tags: [Auth]
      operationId: requestMagicLink
      summary: E-mail a sign-in link
      description: |
        Sends a single-use sign-in link (valid 15 minutes) to the address. The response is always `202`, whether
        or not an account exists (no account enumeration); the first sign-in of a new address creates the account
        and a personal organization on the Free plan. Rate limited per e-mail address and client IP
        (`429 rate_limited`). A browser request must come from the console (`Origin`), otherwise `403`.
        On development deployments (`--dev`) the response also contains `dev_login_url`.
        Optional `next` is a console path (relative, e.g. `/invite?token=…`) appended to the e-mailed link
        (`/auth/verify?token=…&next=…`); absolute URLs, `//host`, backslashes, whitespace and `/login`, `/signup`,
        `/auth/…` are refused with `400`.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MagicLinkRequest" }
            example: { email: ada@example.com }
      responses:
        "202":
          description: Accepted (sent if the address can sign in).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/MagicLinkSent" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /auth/magic-link/verify:
    post:
      tags: [Auth]
      operationId: verifyMagicLink
      summary: Sign in with a magic-link token
      description: |
        Consumes the token from the e-mailed link (single use) and starts a console session: sets the
        `taskcloud_session` cookie (HttpOnly, Secure, SameSite=Lax, 30 days sliding) and the `taskcloud_csrf` cookie
        (readable by the console; send its value as `X-CSRF-Token` on non-GET requests). Every sign-in issues
        a new session ID; a session cookie sent with this request is revoked. Sessions end at most 90 days after
        sign-in, however active.

        When the user has two-factor authentication, no session is created yet: the response is
        `{"two_factor_required": true, "methods": [...]}` with an HttpOnly `taskcloud_mfa` cookie (path
        `/v1/auth/2fa`, 5 minutes) and the sign-in continues with `verifyTwoFactorLogin`.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TokenRequest" }
      responses:
        "200":
          description: Signed in, or the second factor is required.
          headers:
            Set-Cookie:
              description: "`taskcloud_session` and `taskcloud_csrf`, or `taskcloud_mfa` when a second factor is required."
              schema: { type: string }
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/SignedIn"
                  - $ref: "#/components/schemas/TwoFactorChallenge"
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /auth/2fa/verify:
    post:
      tags: [Auth]
      operationId: verifyTwoFactorLogin
      summary: Finish sign-in with a two-factor code
      description: |
        Second step of a sign-in (magic link or GitHub) for a user with two-factor authentication. Needs the
        `taskcloud_mfa` cookie set by the first step and either a 6-digit `code` from the authenticator app or one of
        the `recovery_code`s (each works once). A code's 30-second step is accepted once. On success the session
        cookies are set as in `verifyMagicLink`. A sign-in step allows 5 attempts and expires after 5 minutes:
        then `401` with `details.reason = challenge_expired` (sign in again); a wrong code is `401` with
        `details.reason = invalid_code`.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code: { type: string, pattern: "^[0-9]{6}$", example: "492039" }
                recovery_code: { type: string, maxLength: 32, example: abcde-fghij }
      responses:
        "200":
          description: Signed in.
          headers:
            Set-Cookie:
              description: "`taskcloud_session` and `taskcloud_csrf`; `taskcloud_mfa` is cleared."
              schema: { type: string }
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SignedIn"
                  - type: object
                    properties:
                      recovery_codes_remaining: { type: integer, description: Unused recovery codes, when one was used. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /auth/github/start:
    get:
      tags: [Auth]
      operationId: startGithubLogin
      summary: Start GitHub sign-in
      description: |
        Redirects the browser to GitHub (OAuth web flow with a `state` cookie). `404 not_found`
        (`details.reason = github_not_configured`) when GitHub sign-in is not configured. The callback URL is on
        the console origin by default (`https://app.task.cloud/v1/auth/github/callback`, proxied to the API), so the
        state and session cookies are first-party for the console. After sign-in the browser goes to `next`
        (a relative console path; anything else is ignored) or `/`.
      security: []
      parameters:
        - name: next
          in: query
          required: false
          schema: { type: string, maxLength: 512, example: /sandboxes }
      responses:
        "302":
          description: Redirect to GitHub.
          headers:
            Location: { description: GitHub authorization URL., schema: { type: string } }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /auth/github/callback:
    get:
      tags: [Auth]
      operationId: githubCallback
      summary: GitHub sign-in callback
      description: |
        GitHub redirects here. The account is found by GitHub ID, else by the verified primary e-mail (linking
        it), else created. On success the session cookies are set and the browser is redirected to the console
        (to `/auth/2fa?next=…` with the `taskcloud_mfa` cookie when the user has two-factor authentication). A GitHub
        account older than 90 days verifies the user (stricter limits for new accounts stop, a held Free pool is
        released). On failure to `<console>/login?error=github_denied|github_state|github_email|github_failed`.
      security: []
      parameters:
        - { name: code, in: query, schema: { type: string } }
        - { name: state, in: query, schema: { type: string } }
      responses:
        "302":
          description: Redirect to the console.
          headers:
            Location: { description: Console URL., schema: { type: string } }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /auth/logout:
    post:
      tags: [Auth]
      operationId: logout
      summary: Sign out
      description: Revokes the current session and clears the cookies.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      responses:
        "204": { description: Signed out. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ---------------------------------------------------------------- Console: the signed-in user
  /me:
    get:
      tags: [Me]
      operationId: getMe
      summary: Get the signed-in user
      description: The user, their organizations (with role and plan), the session's current organization and the CSRF token.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      responses:
        "200":
          description: The signed-in user.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Me" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    patch:
      tags: [Me]
      operationId: updateMe
      summary: Update the profile
      security: [{ cookieAuth: [] }]
      x-session-only: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, maxLength: 120 }
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Me" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Me]
      operationId: deleteMe
      summary: Delete my account
      description: |
        Erases the signed-in user (GDPR): memberships, sessions, two-factor settings, magic links and pending
        invitations of the address, and the profile. Audit records are kept but pseudonymized (the user ID becomes
        `deleted_<hex>`, details such as IP addresses are dropped). Organizations where the user is the only member
        are deleted too (retention purge after 30 days). `confirm_email` must equal the account's address; with
        two-factor authentication `code` (TOTP or recovery code) is required (`400`, `details.reason =
        code_required | invalid_code`). Refused with `409 invalid_state` while the user is the only owner of an
        organization with sandboxes (`org_has_sandboxes`), an active subscription (`active_subscription`) or other
        members (`sole_owner`: make someone else owner first); `details.org_id` and `details.org_name` name it.
        On success the cookies are cleared and a confirmation e-mail is sent.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [confirm_email]
              properties:
                confirm_email: { type: string, maxLength: 254 }
                code: { type: string, maxLength: 32 }
      responses:
        "204": { description: Deleted. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /me/export:
    get:
      tags: [Me]
      operationId: exportMe
      summary: Export my personal data
      description: |
        A JSON file (`Content-Disposition: attachment`) with the user's personal data: profile, organizations and
        roles, sessions (with IP addresses and user agents), two-factor status, invitations the user sent, API keys
        the user created (never their secrets) and audit records by or about the user (up to 1000). Sandboxes,
        files and usage belong to organizations and are exported through the API. 10 exports per hour.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      responses:
        "200":
          description: The export.
          headers:
            Content-Disposition: { description: "`attachment; filename=\"taskcloud-export-<user>-<date>.json\"`", schema: { type: string } }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PersonalDataExport" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /me/2fa:
    get:
      tags: [Me]
      operationId: getTwoFactor
      summary: Get my two-factor status
      security: [{ cookieAuth: [] }]
      x-session-only: true
      responses:
        "200":
          description: Status.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TwoFactorStatus" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Me]
      operationId: disableTwoFactor
      summary: Turn two-factor authentication off
      description: Needs a current `code` (TOTP or recovery code). Removes the authenticator and the recovery codes and e-mails the user.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TwoFactorCode" }
      responses:
        "204": { description: Disabled. }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /me/2fa/totp:
    post:
      tags: [Me]
      operationId: beginTotpEnrollment
      summary: Start authenticator enrollment
      description: |
        Returns a new TOTP secret (RFC 6238: SHA-1, 6 digits, 30 s) and its `otpauth://` URI for a QR code. The
        enrollment is pending until `confirmTotpEnrollment` (10 minutes). `409 invalid_state`
        (`details.reason = two_factor_enabled`) when 2FA is already on.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      responses:
        "200":
          description: Pending enrollment.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TotpEnrollment" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /me/2fa/totp/confirm:
    post:
      tags: [Me]
      operationId: confirmTotpEnrollment
      summary: Confirm the authenticator and turn 2FA on
      description: |
        A valid `code` from the app enables two-factor authentication and returns 10 recovery codes, shown once
        (stored hashed). `400` with `details.reason = invalid_code`; `409` with `details.reason =
        no_pending_enrollment`. The user gets an e-mail.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TwoFactorCode" }
      responses:
        "200":
          description: Enabled.
          content:
            application/json:
              schema:
                type: object
                required: [enabled, recovery_codes]
                properties:
                  enabled: { type: boolean }
                  enabled_at: { type: [string, "null"], format: date-time }
                  recovery_codes: { type: array, items: { type: string, example: abcde-fghij } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /me/2fa/recovery-codes:
    post:
      tags: [Me]
      operationId: regenerateRecoveryCodes
      summary: Replace my recovery codes
      description: Needs a current `code`. The previous recovery codes stop working; the user gets an e-mail.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TwoFactorCode" }
      responses:
        "200":
          description: New codes (shown once).
          content:
            application/json:
              schema:
                type: object
                required: [recovery_codes]
                properties:
                  recovery_codes: { type: array, items: { type: string } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /me/switch-org:
    post:
      tags: [Me]
      operationId: switchOrganization
      summary: Switch the session's organization
      description: Later requests of this session act in `org_id` (the user must be a member).
      security: [{ cookieAuth: [] }]
      x-session-only: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [org_id]
              properties:
                org_id: { type: string, example: acc_7kq2mxa9b3cd }
      responses:
        "200":
          description: Switched.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Me" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /me/sessions:
    get:
      tags: [Me]
      operationId: listMySessions
      summary: List my active sessions
      security: [{ cookieAuth: [] }]
      x-session-only: true
      responses:
        "200":
          description: Active sessions, newest first.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/ConsoleSession" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

    delete:
      tags: [Me]
      operationId: revokeOtherSessions
      summary: Sign out all my other sessions
      description: Revokes every active session of the user except the current one.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      responses:
        "200":
          description: Revoked.
          content:
            application/json:
              schema:
                type: object
                required: [revoked]
                properties:
                  revoked: { type: integer, minimum: 0, description: Number of sessions signed out. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /me/sessions/{session_id}:
    parameters:
      - name: session_id
        in: path
        required: true
        schema: { type: string, example: ses_3ht7qm2zkx5d }
    delete:
      tags: [Me]
      operationId: revokeMySession
      summary: Revoke one of my sessions
      description: Signs that browser out. Revoking the current session also clears its cookies.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      responses:
        "204": { description: Revoked. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /organizations:
    post:
      tags: [Me]
      operationId: createOrganization
      summary: Create a team organization
      description: |
        Creates an organization owned by the caller, on the Free plan. The one-time Free allowance (20 h)
        belongs to the user's first organization, so a new one starts with an empty pool until it is upgraded
        (`POST /billing/checkout`). A user can own at most 10 organizations.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string, minLength: 1, maxLength: 120 }
      responses:
        "201":
          description: Created (the session stays in its current organization).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OrganizationSummary" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /organizations/{org_id}:
    parameters:
      - name: org_id
        in: path
        required: true
        schema: { type: string, example: acc_7kq2mxa5b3cd }
    patch:
      tags: [Me]
      operationId: renameOrganization
      summary: Update an organization (name, require 2FA)
      description: |
        `name`: admin or owner; an organization name cannot contain a URL or an e-mail address (it goes into
        invitation e-mails). `require_2fa`: owner only; turning it on needs two-factor authentication on the
        owner's own account (`409 invalid_state`, `details.reason = two_factor_not_enabled`). Members without 2FA
        then get `403 two_factor_required` on organization operations until they enable it; API keys are not
        affected. `404` when the caller is not a member.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                name: { type: string, minLength: 1, maxLength: 120 }
                require_2fa: { type: boolean }
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OrganizationSummary" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Me]
      operationId: deleteOrganization
      summary: Delete an organization
      description: |
        Owner only. Refused with `409 invalid_state` while the organization still has sandboxes in any state
        (`details.reason = org_has_sandboxes`; delete them first, paused ones too: we never delete disks on the
        user's behalf), has an active paid subscription (`active_subscription`; cancel it in the billing portal)
        or is the caller's only organization (`last_organization`). On success the organization disappears for
        every member, its API keys and pending invitations are revoked, and the caller's sessions in it move to
        another of their organizations. After 30 days the rest is purged: snapshots, templates, the organization's
        data keys (offloaded snapshot data becomes unreadable), memberships and invitations. Usage records and
        invoices are kept.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      responses:
        "204": { description: Deleted. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /invitations/accept:
    post:
      tags: [Members]
      operationId: acceptInvitation
      summary: Accept an invitation
      description: |
        Joins the inviting organization with the invited role and switches the session to it. The invitation
        must be pending and addressed to the signed-in user's e-mail (`403`, `details.reason = email_mismatch`);
        revoked or expired invitations return `409 invalid_state`.
      security: [{ cookieAuth: [] }]
      x-session-only: true
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TokenRequest" }
      responses:
        "200":
          description: Joined.
          content:
            application/json:
              schema:
                type: object
                required: [organization, current_org_id]
                properties:
                  organization: { $ref: "#/components/schemas/OrganizationSummary" }
                  current_org_id: { type: string }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ---------------------------------------------------------------- Members & invitations
  /members:
    get:
      tags: [Members]
      operationId: listMembers
      summary: List organization members
      x-required-scopes: [account:read]
      parameters:
        - $ref: "#/components/parameters/LimitDefault100"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: Members.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/Member" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /members/{user_id}:
    parameters:
      - name: user_id
        in: path
        required: true
        schema: { type: string, example: usr_5pq2kz7mwb3x }
    patch:
      tags: [Members]
      operationId: updateMember
      summary: Change a member's role
      description: |
        Admins and owners change roles; only an owner grants or takes away `owner`. An organization always keeps
        at least one owner (`409 invalid_state`, `details.reason = last_owner`). API keys act as admins.
      x-required-scopes: [account:manage]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [role]
              properties:
                role: { $ref: "#/components/schemas/Role" }
      responses:
        "200":
          description: Updated member.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Member" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Members]
      operationId: removeMember
      summary: Remove a member (or leave)
      description: |
        Removing someone else needs `account:manage` (admin or owner; only an owner removes an owner). Any
        signed-in member may remove themselves (leave). The last owner cannot leave (`409 invalid_state`).
      x-required-scopes: [account:manage]
      responses:
        "204": { description: Removed. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /invitations:
    get:
      tags: [Members]
      operationId: listInvitations
      summary: List invitations
      x-required-scopes: [account:read]
      parameters:
        - $ref: "#/components/parameters/LimitDefault100"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: Invitations, newest first (all statuses).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/Invitation" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Members]
      operationId: createInvitation
      summary: Invite someone to the organization
      description: |
        E-mails an invitation link (valid 7 days). Admins and owners invite; only an owner invites an `owner`.
        `409 already_exists` when the address is already a member or has a pending invitation. On development
        deployments the response also contains `dev_accept_url`. Invitation e-mails are limited (`429 rate_limited`):
        20 per organization per hour, 3 per address per organization per day (revoking does not reset it) and 10
        per address per day overall.
      x-required-scopes: [account:manage]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email, maxLength: 254 }
                role: { $ref: "#/components/schemas/Role" }
            example: { email: grace@example.com, role: member }
      responses:
        "201":
          description: Invitation sent.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Invitation" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /invitations/{invitation_id}:
    parameters:
      - name: invitation_id
        in: path
        required: true
        schema: { type: string, example: inv_6kd2qz5mxw3b }
    delete:
      tags: [Members]
      operationId: revokeInvitation
      summary: Revoke a pending invitation
      x-required-scopes: [account:manage]
      responses:
        "204": { description: Revoked. }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ---------------------------------------------------------------- Billing (console)
  /billing:
    get:
      tags: [Billing]
      operationId: getBilling
      summary: Get the billing overview
      description: Plan, credit of the current period, overage, spend limit, default card and invoices.
      x-required-scopes: [account:read]
      responses:
        "200":
          description: Billing overview.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Billing" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /billing/invoices:
    get:
      tags: [Billing]
      operationId: listInvoices
      summary: List invoices
      description: All invoices of the organization, newest first (cursor pagination, default 20 per page).
      x-required-scopes: [account:read]
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of invoices.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListMeta"
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/Invoice" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /billing/checkout:
    post:
      tags: [Billing]
      operationId: createCheckoutSession
      summary: Upgrade to a paid plan
      description: |
        Returns a hosted checkout URL (Stripe Checkout) for `starter` or `team`. An organization that already pays
        for a plan switches directly (prorated) and gets the console's success URL.
      x-required-scopes: [account:manage]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plan]
              properties:
                plan: { type: string, enum: [starter, team] }
      responses:
        "200":
          description: Checkout URL.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RedirectUrl" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "503": { $ref: "#/components/responses/ServiceUnavailable" }

  /billing/portal:
    post:
      tags: [Billing]
      operationId: createBillingPortalSession
      summary: Open the billing portal
      description: Returns a URL of the payment provider's portal (card, invoices, cancellation).
      x-required-scopes: [account:manage]
      responses:
        "200":
          description: Portal URL.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RedirectUrl" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "503": { $ref: "#/components/responses/ServiceUnavailable" }

# ------------------------------------------------------------------ Webhooks (outgoing)
webhooks:
  sandboxEvent:
    post:
      summary: Webhook event (sandbox lifecycle, usage thresholds, test)
      description: |
        Sent to every enabled endpoint subscribed to the event type. Delivery is at-least-once and unordered;
        de-duplicate on `Webhook-Id`. Respond `2xx` within 10 s. Failed deliveries are retried with
        exponential backoff for up to 24 hours (8 attempts).

        **Signature:** `Webhook-Signature: v1=<hex>` where
        `hex = HMAC-SHA256(key = webhook secret (the full "whsec_..." string, UTF-8), message = Webhook-Id + "." + Webhook-Timestamp + "." + raw_body)`.
        During secret rotation the header holds two space-separated `v1=` values; accept if any matches.
        Reject requests whose `Webhook-Timestamp` is more than 300 s from your clock.
      parameters:
        - name: Webhook-Id
          in: header
          required: true
          description: Unique event ID (`evt_...`), stable across retries.
          schema: { type: string }
        - name: Webhook-Timestamp
          in: header
          required: true
          description: Unix time in seconds when this attempt was signed.
          schema: { type: string }
        - name: Webhook-Signature
          in: header
          required: true
          schema: { type: string, example: "v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }
        - name: Webhook-Event
          in: header
          required: true
          schema: { $ref: "#/components/schemas/WebhookEventType" }
        - name: Webhook-Attempt
          in: header
          required: true
          schema: { type: integer, minimum: 1 }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/WebhookEvent" }
      responses:
        "200": { description: Acknowledged. Any 2xx status counts as success. }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: "taskcloud_sk_..."
      description: "API key in the `Authorization: Bearer` header."
    cookieAuth:
      type: apiKey
      in: cookie
      name: taskcloud_session
      description: |
        Console session (set by `verifyMagicLink` or the GitHub callback). Non-GET requests also need the
        `X-CSRF-Token` header equal to the `taskcloud_csrf` cookie and an allowed `Origin`.

  headers:
    RateLimit-Policy:
      description: 'Quota policies, e.g. `"default";q=6000;w=60, "starts";q=300;w=60`.'
      schema: { type: string }
    RateLimit:
      description: 'Remaining quota, e.g. `"default";r=5987;t=42`.'
      schema: { type: string }
    Retry-After:
      description: Seconds to wait before retrying.
      schema: { type: integer }
    X-Request-Id:
      description: Unique request ID.
      schema: { type: string }

  parameters:
    SandboxId:
      name: sandbox_id
      in: path
      required: true
      schema: { type: string, example: sbx_2fqxnt4bkq7m }
    CommandId:
      name: command_id
      in: path
      required: true
      schema: { type: string, example: cmd_9fz2cq4kd7mw }
    TemplateId:
      name: template_id
      in: path
      required: true
      description: Template ID (`tpl_...`, e.g. `tpl_python`) or name (`base`, `python`, `my-env`, `my-env:3`).
      schema: { type: string }
    WebhookId:
      name: webhook_id
      in: path
      required: true
      schema: { type: string, example: whk_5mz2qk7hbd4x }
    Path:
      name: path
      in: query
      required: true
      description: Absolute path inside the sandbox, or relative to `/home/user`.
      schema: { type: string, example: /home/user/app/package.json }
    Limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
    LimitDefault100:
      name: limit
      in: query
      description: |
        Page size. These lists were unpaginated before 2026-11; without `limit` they return up to 100 items
        so that clients reading only `data` keep seeing everything.
      schema: { type: integer, minimum: 1, maximum: 100, default: 100 }
    Cursor:
      name: cursor
      in: query
      description: Opaque cursor from `next_cursor` of the previous page.
      schema: { type: string }
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema: { type: string, maxLength: 255 }
    AutoResume:
      name: auto_resume
      in: query
      description: Wake a paused sandbox automatically (default). `false` returns `409 sandbox_paused` instead.
      schema: { type: boolean, default: true }

  responses:
    BadRequest:
      description: Invalid request (`invalid_request`, `invalid_path`, `invalid_template`, ...).
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example:
            error:
              code: invalid_request
              message: "size must be one of: small, default, large"
              retryable: false
              status: 400
              request_id: req_01HF3X
              details: { field: size }
    Unauthorized:
      description: |
        Missing, invalid, expired or revoked API key (`unauthorized`). The scheme name is case-insensitive
        (`Bearer`, `bearer`). Requests without a valid key are rate limited per client IP, so this response
        also carries `RateLimit` headers.
      headers:
        RateLimit-Policy: { $ref: "#/components/headers/RateLimit-Policy" }
        RateLimit: { $ref: "#/components/headers/RateLimit" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    PaymentRequired:
      description: "`payment_required`, `spend_limit_reached`, `free_hours_exhausted`."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Forbidden:
      description: |
        `forbidden` or `insufficient_scope` (see `details.required_scopes`). Not retryable. `details.reason` tells why:

        - `account_suspended`: the account is suspended (acceptable use review). Every call except reads of the
          account, usage, limits and sandboxes returns this; all sandboxes are paused and their data kept.
          `details.suspended_at` (RFC 3339) and `details.contact` (where to appeal) are set.
        - `fork_count_limit`: bulk fork `count` above the account's limit (`details.limit`, `details.requested`,
          `details.plan`).
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    NotFound:
      description: "`not_found` (resource does not exist or is not visible to this key)."
      headers:
        RateLimit-Policy: { $ref: "#/components/headers/RateLimit-Policy" }
        RateLimit: { $ref: "#/components/headers/RateLimit" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Timeout:
      description: "`exec_timeout`: a sync command exceeded `timeout_seconds` and was killed. Partial output is in `details`."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Conflict:
      description: |
        State conflict: `invalid_state` (e.g. fork of a `deleting` sandbox), `sandbox_paused` (with `auto_resume=false`),
        `sandbox_busy` (retryable, with `Retry-After`: another lifecycle operation is in progress on the sandbox),
        `concurrency_limit_reached`, `idempotency_conflict`, `already_exists`, `desktop_not_available`, `snapshot_in_use`.
        `sandbox_busy` responses carry a `Retry-After` header.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    PreconditionFailed:
      description: "`precondition_failed`: `If-Match` did not match."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    RangeNotSatisfiable:
      description: |
        The `Range` starts at or after the end of the file (RFC 9110 §15.5.17). Error code `invalid_request`;
        `details.size` is the file size in bytes.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    PayloadTooLarge:
      description: "`payload_too_large`: use signed upload/download URLs."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    RateLimited:
      description: |
        `rate_limited` (retryable). Usually the per-key policy in `RateLimit-Policy` (`default` per key,
        `starts` per account: 300 per minute, 30 per minute for new unverified Free accounts). With
        `details.reason = "too_many_operations"` (`details.scope = "sandbox"`) it is the limit of concurrent
        operations on one sandbox (exec, files, PTY, ...): the request waited in the sandbox's queue and timed
        out or the queue was full. Retry after `Retry-After`; other sandboxes are not affected.
      headers:
        Retry-After: { $ref: "#/components/headers/Retry-After" }
        RateLimit-Policy: { $ref: "#/components/headers/RateLimit-Policy" }
        RateLimit: { $ref: "#/components/headers/RateLimit" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    BadGateway:
      description: "`sandbox_unreachable`: the guest did not answer. `retryable` tells whether the command may be retried safely."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    InsufficientStorage:
      description: |
        `insufficient_storage` (not retryable): the sandbox's disk is full (or a quota is reached). Free space,
        e.g. with `DELETE .../files`, or use a sandbox with a larger `disk_gb`.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example:
            error:
              code: insufficient_storage
              message: "the sandbox disk is full; free space or create the sandbox with a larger disk_gb"
              retryable: false
              status: 507
              request_id: req_01HF3X
    ServiceUnavailable:
      description: |
        `capacity_unavailable` (retryable; consider `priority: batch`) or `service_unavailable` (retryable: the
        sandbox host is temporarily unreachable, maintenance, or an operation not available on this host yet,
        then `details.todo` says what). Nothing was changed; retry after `Retry-After`.
        `capacity_unavailable` with `details.reason = "incompatible_host"`: the sandbox's pause snapshot was
        written by another Firecracker version and no compatible host can restore it right now; the sandbox stays
        `paused` (`pause_reason: incompatible_host`) with its data intact.
      headers:
        Retry-After: { $ref: "#/components/headers/Retry-After" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }

  schemas:
    # ---------- common
    Error:
      type: object
      required: [error]
      properties:
        error: { $ref: "#/components/schemas/ErrorBody" }
    ErrorBody:
      type: object
      required: [code, message, retryable, status, request_id]
      properties:
        code: { $ref: "#/components/schemas/ErrorCode" }
        message: { type: string, description: Human-readable; may change. }
        retryable: { type: boolean, description: Safe to retry the same request (after `Retry-After` if present). }
        status: { type: integer, description: HTTP status code. }
        request_id: { type: string }
        details:
          type: object
          additionalProperties: true
          description: Code-specific details, e.g. `field`, `required_scopes`, `state`, `retry_after_seconds`.
    ErrorCode:
      type: string
      enum:
        - invalid_request
        - invalid_path
        - invalid_template
        - invalid_image
        - unauthorized
        - insufficient_scope
        - forbidden
        - payment_required
        - spend_limit_reached
        - free_hours_exhausted
        - not_found
        - exec_timeout
        - invalid_state
        - sandbox_paused
        - sandbox_busy
        - concurrency_limit_reached
        - idempotency_conflict
        - already_exists
        - desktop_not_available
        - snapshot_in_use
        - precondition_failed
        - payload_too_large
        - rate_limited
        - internal_error
        - sandbox_unreachable
        - capacity_unavailable
        - service_unavailable
        - insufficient_storage
    ListMeta:
      type: object
      required: [has_more, next_cursor]
      properties:
        has_more: { type: boolean }
        next_cursor: { type: [string, "null"] }
    Labels:
      type: object
      description: Up to 32 key/value labels. Keys `^[a-z0-9_.-]{1,63}$`, values up to 255 chars.
      maxProperties: 32
      additionalProperties: { type: string, maxLength: 255 }
    EnvVars:
      type: object
      description: Environment variables (up to 100, 64 KiB total). Write-only; never returned.
      maxProperties: 100
      additionalProperties: { type: string }
    WaitRequest:
      type: object
      properties:
        wait:
          type: boolean
          default: true
          description: Block until the transition finishes (max 60 s; after that `202` is returned).

    # ---------- sandboxes
    SandboxState:
      type: string
      description: |
        `queued` (batch only, waiting for capacity) → `creating` → `running` ⇄ `pausing` → `paused` → `resuming` → `running`.
        Terminal: `deleting` → `deleted`. `error` means the VM failed; see `error` on the sandbox.
      enum: [queued, creating, running, pausing, paused, resuming, deleting, deleted, error]
    Size:
      type: string
      description: "`small` 2 vCPU / 4 GB / 20 GB; `default` 4 vCPU / 8 GB / 50 GB; `large` 8 vCPU / 16 GB / 100 GB."
      enum: [small, default, large]
      default: default
    Priority:
      type: string
      description: "`batch` is billed −50% and may wait in `queued` until capacity is available."
      enum: [standard, batch]
      default: standard
    Region:
      type: string
      description: "`eu-de` (Germany) or `eu-fi` (Finland). Default: automatic placement within the EU."
      enum: [auto, eu-de, eu-fi]
      default: auto
    AutoPause:
      type: object
      description: |
        Pause automatically after `idle_timeout_seconds` with no activity. Activity = a running exec/PTY,
        inbound traffic on exposed ports or SSH, a connected desktop viewer or desktop input, or CPU usage above
        a low threshold. Ignored when `always_on` is true.
      properties:
        enabled: { type: boolean, default: true }
        idle_timeout_seconds: { type: integer, minimum: 60, maximum: 86400, default: 300 }
    ImageSource:
      type: object
      required: [ref]
      properties:
        ref: { type: string, example: "ghcr.io/acme/agent-env:1.4", description: OCI image reference (linux/amd64). }
        registry_auth:
          type: object
          description: Credentials for a private registry. Write-only.
          properties:
            username: { type: string }
            password: { type: string, writeOnly: true }
    CreateSandboxRequest:
      type: object
      properties:
        template:
          type: string
          description: |
            Template name or ID, optionally `name:version`. Default `base`. Official templates: `base`, `python`,
            `node`, `browser`, `coding-agent`, `jupyter`, `desktop` (`GET /templates?owner=builtin`). If your account
            has its own template with the same name as an official one, the name resolves to yours; the official
            one stays reachable by ID (`tpl_python`).
          example: python
        snapshot_id: { type: string, description: Start from a named snapshot (restores RAM and disk). }
        image: { $ref: "#/components/schemas/ImageSource" }
        size: { $ref: "#/components/schemas/Size" }
        name: { type: string, maxLength: 120 }
        labels: { $ref: "#/components/schemas/Labels" }
        env: { $ref: "#/components/schemas/EnvVars" }
        auto_pause: { $ref: "#/components/schemas/AutoPause" }
        always_on:
          type: boolean
          default: false
          description: Never auto-pause; billed at the always-on monthly price. `default` size only.
        priority: { $ref: "#/components/schemas/Priority" }
        region: { $ref: "#/components/schemas/Region" }
        ttl_seconds:
          type: [integer, "null"]
          minimum: 60
          description: Delete the sandbox automatically this many seconds after creation. `null` = keep until deleted.
        disk_gb:
          type: integer
          description: Disk size; above the size's included disk is billed per GB-month.
          minimum: 20
          maximum: 1000
        ports:
          type: array
          description: Ports to expose at creation.
          maxItems: 20
          items: { $ref: "#/components/schemas/ExposePortRequest" }
        metadata:
          type: object
          description: Free-form JSON (up to 16 KiB) returned as-is, e.g. your own user ID.
          additionalProperties: true
        wait:
          type: boolean
          default: true
          description: "Wait until `running` (max 60 s). Ignored for `priority: batch`."
    UpdateSandboxRequest:
      type: object
      minProperties: 1
      properties:
        name: { type: string, maxLength: 120 }
        labels: { $ref: "#/components/schemas/Labels" }
        auto_pause: { $ref: "#/components/schemas/AutoPause" }
        always_on: { type: boolean }
        ttl_seconds: { type: [integer, "null"], minimum: 60 }
        metadata: { type: object, additionalProperties: true }
    ForkSandboxRequest:
      type: object
      properties:
        name: { type: string, maxLength: 120 }
        labels: { $ref: "#/components/schemas/Labels" }
        env:
          $ref: "#/components/schemas/EnvVars"
        auto_pause: { $ref: "#/components/schemas/AutoPause" }
        priority: { $ref: "#/components/schemas/Priority" }
        ttl_seconds: { type: [integer, "null"], minimum: 60 }
        metadata: { type: object, additionalProperties: true }
        wait: { type: boolean, default: true }
        count:
          type: integer
          minimum: 1
          maximum: 500
          default: 1
          description: |
            Number of forks to create from one capture of the source (bulk fork). All or nothing.
            `1` returns a single `Sandbox`; more than `1` returns `ForkSandboxesResponse`.
            The account's limit (`GET /limits` → `bulk_fork.max_count`; Free 2, Starter 10, Team 50,
            Enterprise 100, higher on request) applies; above it the call returns `403 forbidden` with
            `details.reason = "fork_count_limit"`.
    ForkSandboxesResponse:
      type: object
      required: [data]
      description: Response of `forkSandbox` with `count > 1`.
      properties:
        data:
          type: array
          minItems: 2
          items: { $ref: "#/components/schemas/Sandbox" }
    Sandbox:
      type: object
      required: [id, state, size, created_at, auto_pause, always_on, priority, region]
      properties:
        id: { type: string, example: sbx_2fqxnt4bkq7m }
        name: { type: [string, "null"] }
        state: { $ref: "#/components/schemas/SandboxState" }
        size: { $ref: "#/components/schemas/Size" }
        vcpus: { type: integer, example: 4 }
        memory_mb: { type: integer, example: 8192 }
        disk_gb: { type: integer, example: 50 }
        template_id: { type: [string, "null"] }
        snapshot_id: { type: [string, "null"], description: Snapshot the sandbox was created from. }
        image: { type: [string, "null"], description: "OCI image reference, if created from an image." }
        forked_from:
          type: [object, "null"]
          properties:
            sandbox_id: { type: string }
            snapshot_id: { type: string }
        labels: { $ref: "#/components/schemas/Labels" }
        metadata: { type: object, additionalProperties: true }
        auto_pause: { $ref: "#/components/schemas/AutoPause" }
        always_on: { type: boolean }
        priority: { $ref: "#/components/schemas/Priority" }
        region: { type: string, example: eu-de }
        ttl_seconds: { type: [integer, "null"] }
        expires_at: { type: [string, "null"], format: date-time }
        url_template:
          type: string
          description: Pattern for public port URLs (sandbox domain `taskhost.cloud`).
          example: "https://a2b3c4d5e6f7-{port}.taskhost.cloud"
        ports:
          type: array
          items: { $ref: "#/components/schemas/Port" }
        desktop: { type: boolean, description: True if the sandbox has a desktop (e.g. `desktop` template). }
        error:
          type: [object, "null"]
          description: |
            Set in state `error`. Codes include `vm_start_failed`, `resume_failed` and `limits_apply_failed`
            (the account's network/CPU restrictions could not be applied, so the sandbox was not started).
          properties:
            code: { type: string }
            message: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        started_at: { type: [string, "null"], format: date-time, description: Last transition to `running`. }
        paused_at: { type: [string, "null"], format: date-time }
        pause_reason:
          type: [string, "null"]
          description: |
            Set while a `paused` sandbox needs attention, otherwise `null`. `incompatible_host`: the pause snapshot
            was written by another Firecracker version and cannot be restored on its host; TaskCloud resumes it on a
            compatible host when one is available, otherwise resume returns a retryable `503 capacity_unavailable`
            (`details.reason = "incompatible_host"`). RAM and disk are intact. Other values may be added.
          example: null
        last_activity_at: { type: [string, "null"], format: date-time }

    # ---------- exec
    ExecRequest:
      type: object
      properties:
        command: { type: string, description: Shell command run with `/bin/bash -lc`. }
        args:
          type: array
          description: Program and arguments executed directly (no shell). Use instead of `command`.
          items: { type: string }
        cwd: { type: string, default: /home/user }
        env: { $ref: "#/components/schemas/EnvVars" }
        user: { type: string, default: user, description: "Linux user. `user` has passwordless sudo; `root` is allowed." }
        stdin: { type: string, description: "Data written to stdin, then closed (sync and stream modes)." }
        timeout_seconds:
          type: integer
          minimum: 1
          maximum: 600
          default: 60
          description: Sync and stream mode only. Background commands have no time limit.
        background: { type: boolean, default: false }
        stream: { type: boolean, default: false, description: Respond with an SSE stream. }
      oneOf:
        - required: [command]
        - required: [args]
    ExecResult:
      type: object
      required: [command_id, exit_code, stdout, stderr, duration_ms]
      properties:
        command_id: { type: string }
        exit_code: { type: integer }
        stdout: { type: string }
        stderr: { type: string }
        encoding: { type: string, enum: [utf8, base64], default: utf8 }
        truncated: { type: boolean, description: Output exceeded 8 MiB per stream and was cut. }
        duration_ms: { type: integer }
    CommandState:
      type: string
      enum: [running, exited, killed, timed_out, lost]
    Command:
      type: object
      required: [id, state, created_at]
      properties:
        id: { type: string, example: cmd_9fz2cq4kd7mw }
        sandbox_id: { type: string }
        command: { type: string }
        args: { type: array, items: { type: string } }
        cwd: { type: string }
        user: { type: string }
        pid: { type: [integer, "null"] }
        state: { $ref: "#/components/schemas/CommandState" }
        background: { type: boolean }
        exit_code: { type: [integer, "null"] }
        signal: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
        finished_at: { type: [string, "null"], format: date-time }
    ExecEvent:
      type: object
      required: [type, command_id]
      properties:
        type: { type: string, enum: [start, stdout, stderr, exit, error] }
        command_id: { type: string }
        pid: { type: integer, description: "`start` only." }
        data: { type: string, description: "`stdout`/`stderr` chunk." }
        encoding: { type: string, enum: [utf8, base64], default: utf8 }
        exit_code: { type: integer, description: "`exit` only." }
        duration_ms: { type: integer }
        error: { $ref: "#/components/schemas/ErrorBody" }
    CreatePtyRequest:
      type: object
      properties:
        command: { type: string, default: "/bin/bash -l" }
        cwd: { type: string, default: /home/user }
        env: { $ref: "#/components/schemas/EnvVars" }
        user: { type: string, default: user }
        cols: { type: integer, minimum: 10, maximum: 1000, default: 80 }
        rows: { type: integer, minimum: 5, maximum: 500, default: 24 }
        idle_timeout_seconds: { type: integer, minimum: 30, maximum: 86400, default: 1800 }
    PtySession:
      type: object
      required: [id, websocket_url, expires_at, state]
      properties:
        id: { type: string, example: pty_7hc2zq5mxk3d }
        sandbox_id: { type: string }
        state:
          type: string
          enum: [waiting, connected, disconnected, exited]
          description: |
            `waiting`: nobody has connected yet; `connected`: a WebSocket client is attached; `disconnected`: the
            client left and the process keeps running (reconnect within `idle_timeout_seconds`); `exited`: the
            process ended (`exit_code`).
        pid: { type: [integer, "null"] }
        websocket_url:
          type: string
          example: "wss://api.task.cloud/v1/sandboxes/sbx_2fqxnt4bkq7m/pty/pty_7hc2zq5mxk3d/connect?token=pt_..."
        expires_at: { type: string, format: date-time, description: The connect URL must be used before this time. }
        exit_code: { type: [integer, "null"] }

    # ---------- files
    FileEntry:
      type: object
      required: [name, path, type]
      properties:
        name: { type: string }
        path: { type: string }
        type: { type: string, enum: [file, dir, symlink, other] }
        size: { type: integer, description: Bytes. }
        mode: { type: string, example: "0644" }
        owner: { type: string }
        modified_at: { type: string, format: date-time }
        symlink_target: { type: [string, "null"] }
        etag: { type: string }
    SignedUrlRequest:
      type: object
      required: [path]
      properties:
        path: { type: string }
        expires_in_seconds: { type: integer, minimum: 60, maximum: 3600, default: 900 }
    SignedUrl:
      type: object
      required: [url, method, expires_at]
      properties:
        url: { type: string, format: uri }
        method: { type: string, enum: [GET, PUT] }
        expires_at: { type: string, format: date-time }
    FileEvent:
      type: object
      required: [type, path, timestamp]
      properties:
        type: { type: string, enum: [created, modified, deleted, renamed] }
        path: { type: string }
        old_path: { type: string, description: "`renamed` only." }
        is_dir: { type: boolean }
        timestamp: { type: string, format: date-time }

    # ---------- networking
    ExposePortRequest:
      type: object
      required: [port]
      properties:
        port: { type: integer, minimum: 1, maximum: 65535 }
        visibility: { type: string, enum: [private, public], default: private }
        protocol: { type: string, enum: [http], default: http, description: "HTTP(S) and WebSocket. Raw TCP/UDP: Coming soon." }
    Port:
      type: object
      required: [port, url, visibility]
      properties:
        port: { type: integer }
        url: { type: string, example: "https://a2b3c4d5e6f7-3000.taskhost.cloud" }
        visibility: { type: string, enum: [private, public] }
        protocol: { type: string, enum: [http] }
        created_at: { type: string, format: date-time }
    SshAccess:
      type: object
      required: [host, port, username, expires_at, command]
      properties:
        host: { type: string, example: "ssh.taskhost.cloud" }
        port: { type: integer, example: 22 }
        username: { type: string, example: "sbx_2fqxnt4bkq7m", description: Gateway username; routes to the sandbox. }
        password: { type: [string, "null"], description: "One-time password, only when no key was supplied." }
        expires_at: { type: string, format: date-time }
        command: { type: string, example: "ssh sbx_2fqxnt4bkq7m@ssh.taskhost.cloud" }
        host_key_fingerprint: { type: string, example: "SHA256:..." }
    SshKey:
      type: object
      required: [id, fingerprint, created_at]
      properties:
        id: { type: string }
        name: { type: string }
        fingerprint: { type: string }
        created_at: { type: string, format: date-time }

    # ---------- desktop
    CreateDesktopStreamRequest:
      type: object
      properties:
        ttl_seconds:
          type: integer
          minimum: 60
          maximum: 86400
          default: 600
          description: URL lifetime. An open session is disconnected when the URL expires.
        read_only: { type: boolean, default: false, description: Viewer can watch but not send input. }
        single_use: { type: boolean, default: false, description: URL can be opened once. }
    DesktopStream:
      type: object
      required: [id, url, expires_at, read_only]
      properties:
        id: { type: string, example: dsk_7zab3kq2mxw5 }
        url: { type: string, example: "https://a2b3c4d5e6f7-desktop.taskhost.cloud/?token=dt_..." }
        read_only: { type: boolean }
        single_use: { type: boolean }
        expires_at: { type: string, format: date-time }
        created_at: { type: string, format: date-time }
    Screenshot:
      type: object
      required: [data, media_type, width, height]
      properties:
        data: { type: string, contentEncoding: base64 }
        media_type: { type: string, enum: [image/png, image/jpeg] }
        width: { type: integer, description: Width of the returned image. }
        height: { type: integer }
        screen_width: { type: integer, description: Full screen width (coordinate space). }
        screen_height: { type: integer }
        taken_at: { type: string, format: date-time }
    Coordinate:
      type: array
      description: "`[x, y]` in screen pixels, origin top-left."
      items: { type: integer, minimum: 0 }
      minItems: 2
      maxItems: 2
    InputAction:
      type: object
      required: [action]
      description: |
        One input action. Fields by action:
        - `mouse_move`: `coordinate`
        - `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`: optional `coordinate`
          (default: current cursor), optional `text` = held modifiers (`shift`, `ctrl`, `alt`, `super`, joined with `+`)
        - `left_click_drag`: `start_coordinate`, `coordinate`
        - `left_mouse_down`, `left_mouse_up`: no fields
        - `scroll`: `scroll_direction`, `scroll_amount` (wheel clicks), optional `coordinate`, optional `text` modifiers
        - `type`: `text` (typed as Unicode, any length up to 64 KiB)
        - `key`: `text` = key or chord in xdotool syntax (`Return`, `ctrl+s`, `ctrl+shift+t`), optional `repeat`
        - `hold_key`: `text`, `duration` (seconds)
        - `wait`: `duration` (seconds)
      properties:
        action:
          type: string
          enum: [mouse_move, left_click, right_click, middle_click, double_click, triple_click, left_click_drag,
                 left_mouse_down, left_mouse_up, scroll, type, key, hold_key, wait]
        coordinate: { $ref: "#/components/schemas/Coordinate" }
        start_coordinate: { $ref: "#/components/schemas/Coordinate" }
        text: { type: string, maxLength: 65536 }
        scroll_direction: { type: string, enum: [up, down, left, right] }
        scroll_amount: { type: integer, minimum: 1, maximum: 100, default: 3 }
        repeat: { type: integer, minimum: 1, maximum: 100, default: 1 }
        duration: { type: number, minimum: 0, maximum: 300 }
    InputRequest:
      type: object
      required: [actions]
      properties:
        actions:
          type: array
          minItems: 1
          maxItems: 100
          items: { $ref: "#/components/schemas/InputAction" }
        coordinate_scale:
          type: number
          minimum: 0.1
          maximum: 1
          default: 1
          description: If coordinates come from a screenshot taken with `scale`, pass the same value; they are divided by it.
        return_screenshot: { type: boolean, default: false }
        screenshot_delay_ms:
          type: integer
          minimum: 0
          maximum: 5000
          default: 300
          description: Wait before the final screenshot so the UI can settle.
    InputResult:
      type: object
      required: [results, cursor]
      properties:
        results:
          type: array
          items:
            type: object
            required: [index, action, status]
            properties:
              index: { type: integer }
              action: { type: string }
              status: { type: string, enum: [ok, error, skipped] }
              error: { type: [string, "null"] }
        cursor:
          type: object
          properties:
            x: { type: integer }
            y: { type: integer }
        screenshot:
          oneOf:
            - $ref: "#/components/schemas/Screenshot"
            - type: "null"

    # ---------- snapshots & templates
    Snapshot:
      type: object
      required: [id, state, sandbox_id, created_at, memory]
      properties:
        id: { type: string, example: snap_3kd7wq2mzn5x }
        name: { type: [string, "null"] }
        sandbox_id: { type: string, description: Source sandbox (may since have been deleted). }
        state: { type: string, enum: [creating, ready, failed, deleting] }
        memory: { type: boolean, description: Includes RAM. }
        size: { $ref: "#/components/schemas/Size" }
        storage_bytes: { type: integer, description: Billable stored size after compression and deduplication. }
        labels: { $ref: "#/components/schemas/Labels" }
        created_at: { type: string, format: date-time }
        free_storage_until: { type: string, format: date-time, description: "Storage is free until this time (30 days), then billed per GB-month." }
    CreateTemplateRequest:
      type: object
      required: [name]
      properties:
        name: { type: string, pattern: "^[a-z0-9][a-z0-9-]{1,62}$" }
        description: { type: string, maxLength: 500 }
        image: { $ref: "#/components/schemas/ImageSource" }
        snapshot_id: { type: string }
        size: { $ref: "#/components/schemas/Size" }
        env: { $ref: "#/components/schemas/EnvVars" }
        start_command: { type: string, description: "Image builds only: started (as a systemd service) before the snapshot is taken." }
        ready_check:
          type: object
          description: "Image builds only: command that must exit 0 before the snapshot is taken."
          properties:
            command: { type: string }
            timeout_seconds: { type: integer, minimum: 1, maximum: 1800, default: 300 }
        desktop: { type: boolean, default: false, description: "Image builds only: add the XFCE + KasmVNC desktop stack." }
      oneOf:
        - required: [image]
        - required: [snapshot_id]
    Template:
      type: object
      required: [id, name, version, state, builtin, created_at]
      properties:
        id: { type: string, example: tpl_base }
        name: { type: string, example: base }
        version: { type: integer }
        description: { type: [string, "null"] }
        builtin: { type: boolean }
        state: { type: string, enum: [building, ready, failed] }
        source:
          type: object
          properties:
            type: { type: string, enum: [builtin, image, snapshot] }
            image: { type: [string, "null"] }
            snapshot_id: { type: [string, "null"] }
        size: { $ref: "#/components/schemas/Size" }
        desktop: { type: boolean }
        storage_bytes: { type: integer, description: "Stored size. Official templates: the image size budget." }
        error: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
        official:
          type: boolean
          description: Part of the official gallery (curated, reproducible, smoke-tested by TaskCloud). Official templates are also `builtin`.
        tags:
          type: array
          items: { type: string }
          description: Gallery tags (e.g. `python`, `browser`, `computer-use`). Empty for your own templates.
        ports:
          type: array
          items: { $ref: "#/components/schemas/TemplatePort" }
          description: |
            Ports the template serves out of the box (e.g. `jupyter`: 8888). Expose them with
            `POST /sandboxes/{sandbox_id}/ports` or `ports` at create. Empty when none.
        docs_url: { type: [string, "null"], format: uri, description: Documentation of an official template. }
        example_command: { type: [string, "null"], description: "A command that shows the template working (official templates). Every official template also has `taskcloud-smoke`, its in-sandbox smoke test." }
    TemplatePort:
      type: object
      required: [port, name, protocol]
      properties:
        port: { type: integer, minimum: 1, maximum: 65535, example: 8888 }
        name: { type: string, example: jupyterlab }
        protocol: { type: string, enum: [http] }
        description: { type: string }

    # ---------- webhooks
    WebhookEventType:
      type: string
      description: |
        - `sandbox.ready`: the sandbox reached `running` for the first time after create or fork.
        - `sandbox.paused`: the sandbox reached `paused` (API call, auto-pause, spend limit).
        - `sandbox.resumed`: a paused sandbox is `running` again (API call or wake on request).
        - `sandbox.error`: the sandbox entered `error`.
        - `sandbox.deleted`: the sandbox reached `deleted` (API call or `ttl_seconds` expiry).
        - `usage.threshold`: account usage crossed a threshold: a spend-limit alert (`alert_thresholds` of
          `PUT /account/spend-limit`, default 50/80/100% of `monthly_limit_usd`), 80% or 100% of the plan credit of
          the billing period, or 80% or 100% of the Free plan's 20 hours. Sent once per threshold and period
          (Free allowance: once per account). `data` is a `UsageThresholdData`.
        - `webhook.test`: sent by `POST /webhooks/{webhook_id}/test`.
        - `sandbox.restored_from_checkpoint`: the sandbox was restored from an older saved state and runs again: its
          host failed while it was running (`reason: host_lost`), or restoring its memory on a new host could not
          finish (`reason: restore_interrupted`). Work done after `checkpoint.taken_at` is lost; with
          `ram_lost: true` processes restarted (disk checkpoint), otherwise memory and processes are as at the
          checkpoint (pause snapshot). `data` is a `RestoredFromCheckpointData`.
      enum: [sandbox.ready, sandbox.paused, sandbox.resumed, sandbox.error, sandbox.deleted, usage.threshold, webhook.test,
        sandbox.restored_from_checkpoint]
    CreateWebhookRequest:
      type: object
      required: [url, events]
      properties:
        url: { type: string, format: uri, description: "HTTPS URL on port 443." }
        events:
          type: array
          minItems: 1
          items: { $ref: "#/components/schemas/WebhookEventType" }
        description: { type: string, maxLength: 200 }
        enabled: { type: boolean, default: true }
    Webhook:
      type: object
      required: [id, url, events, enabled, created_at]
      properties:
        id: { type: string, example: whk_5mz2qk7hbd4x }
        url: { type: string, format: uri }
        events:
          type: array
          items: { $ref: "#/components/schemas/WebhookEventType" }
        description: { type: [string, "null"] }
        enabled: { type: boolean }
        created_at: { type: string, format: date-time }
    WebhookWithSecret:
      allOf:
        - $ref: "#/components/schemas/Webhook"
        - type: object
          required: [secret]
          properties:
            secret: { type: string, example: "whsec_kq3...", description: Shown once. }
    WebhookEvent:
      type: object
      required: [id, type, created_at, data]
      properties:
        id: { type: string, example: evt_2af7cd3ka7zq }
        type: { $ref: "#/components/schemas/WebhookEventType" }
        created_at: { type: string, format: date-time }
        data:
          description: |
            Depends on `type`: `SandboxEventData` for `sandbox.*` (`RestoredFromCheckpointData` for
            `sandbox.restored_from_checkpoint`), `UsageThresholdData` for `usage.threshold`,
            `WebhookTestData` for `webhook.test`.
          oneOf:
            - $ref: "#/components/schemas/SandboxEventData"
            - $ref: "#/components/schemas/RestoredFromCheckpointData"
            - $ref: "#/components/schemas/UsageThresholdData"
            - $ref: "#/components/schemas/WebhookTestData"
      example:
        id: evt_2af7cd3ka7zq
        type: sandbox.paused
        created_at: "2026-11-09T12:00:00Z"
        data:
          sandbox: { id: sbx_2fqxnt4bkq7m, name: user-42, state: paused, size: default, labels: { customer: acme } }
          previous_state: pausing
          state: paused
          reason: auto_pause
    SandboxEventData:
      type: object
      required: [sandbox]
      properties:
        sandbox: { $ref: "#/components/schemas/Sandbox" }
        previous_state: { $ref: "#/components/schemas/SandboxState" }
        state: { $ref: "#/components/schemas/SandboxState" }
        reason:
          type: [string, "null"]
          description: "Why the transition happened: `api`, `auto_pause`, `wake_on_request`, `spend_limit`, `ttl_expired`, `host_maintenance`, `host_lost` (restored from a checkpoint after a host failure), `restore_interrupted`, or an error code."
    RestoredFromCheckpointData:
      type: object
      description: |
        Payload of `sandbox.restored_from_checkpoint`. Sent once per rollback, when the sandbox runs again. A running
        sandbox is checkpointed (disk only, crash-consistent, no pause) after about 15 minutes of activity since its
        last resume or checkpoint, and every pause snapshot is saved too; the newest of them is used.
      required: [sandbox, reason, ram_lost, checkpoint]
      properties:
        sandbox: { $ref: "#/components/schemas/Sandbox" }
        reason:
          type: string
          enum: [host_lost, restore_interrupted, resume]
          description: |
            - `host_lost`: the host running the sandbox failed; it was restored on another host;
            - `restore_interrupted`: memory of a paused sandbox could not be fully restored on its new host, so it
              was restored again from the same saved state;
            - `resume`: a resume used a disk checkpoint because no newer saved state existed.
        ram_lost:
          type: boolean
          description: "`true`: restored from a disk checkpoint, the sandbox booted (processes and `/dev/shm` restarted, files kept as of `taken_at`)."
        checkpoint:
          type: object
          required: [generation, kind]
          properties:
            generation: { type: integer, description: Generation of the saved state that was restored. }
            kind:
              type: string
              enum: [disk, memory]
              description: "`disk`: periodic disk checkpoint; `memory`: pause snapshot (memory and disk)."
            taken_at: { type: [string, "null"], format: date-time, description: When the state was saved. }
        data_loss_window_seconds:
          type: integer
          description: Seconds between `checkpoint.taken_at` and the restore (work in that window is lost).
      example:
        sandbox: { id: sbx_2fqxnt4bkq7m, state: running, size: default }
        reason: host_lost
        ram_lost: true
        checkpoint: { generation: 14, kind: disk, taken_at: "2026-11-09T11:42:00Z" }
        data_loss_window_seconds: 1080
    UsageThresholdData:
      type: object
      description: Payload of `usage.threshold`.
      required: [kind, percent, threshold_usd, amount_usd, limit_usd, action, period_start, period_end]
      properties:
        kind:
          type: string
          enum: [spend_limit, credit, free_allowance]
          description: |
            - `spend_limit`: amount due in the period reached `percent` of `monthly_limit_usd`;
            - `credit`: usage reached `percent` of the plan credit of the period;
            - `free_allowance`: usage reached `percent` of the Free plan's one-time allowance (20 h of `default`).
        percent: { type: integer, example: 80 }
        threshold_usd: { type: number, description: "`limit_usd × percent / 100`.", example: 15.2 }
        amount_usd: { type: number, description: Amount at the moment the threshold was crossed (amount due, credit used or allowance used)., example: 15.24 }
        limit_usd: { type: number, description: "`monthly_limit_usd`, the plan credit or the Free allowance ($0.60).", example: 19 }
        action:
          type: string
          enum: [none, paused_running, blocked_new]
          description: |
            What TaskCloud did: `paused_running` (running sandboxes are being paused, each also sends `sandbox.paused`
            with `reason: spend_limit` or `free_hours_exhausted`), `blocked_new` (new starts get `402`), or `none`.
        period_start: { type: string, format: date-time }
        period_end: { type: string, format: date-time }
      example:
        kind: spend_limit
        percent: 100
        threshold_usd: 50
        amount_usd: 50.02
        limit_usd: 50
        action: paused_running
        period_start: "2026-11-09T00:00:00Z"
        period_end: "2026-12-09T00:00:00Z"
    WebhookTestData:
      type: object
      required: [webhook_id, message]
      properties:
        webhook_id: { type: string }
        message: { type: string }
    WebhookDelivery:
      type: object
      required: [id, event_id, event_type, attempt, status, created_at]
      properties:
        id: { type: string }
        event_id: { type: string }
        event_type: { $ref: "#/components/schemas/WebhookEventType" }
        attempt: { type: integer }
        status: { type: string, enum: [succeeded, failed, pending] }
        response_status: { type: [integer, "null"] }
        duration_ms: { type: [integer, "null"] }
        created_at: { type: string, format: date-time }

    # ---------- usage & account
    UsageItem:
      type: object
      properties:
        key: { type: string, description: "Group key: sandbox ID, date, size, label value or template." }
        sandbox_id: { type: [string, "null"] }
        size: { $ref: "#/components/schemas/Size" }
        running_seconds: { type: integer, description: Seconds billed at the standard rate. }
        batch_seconds: { type: integer, description: Seconds billed at the batch/off-peak rate (−50%). }
        paused_seconds: { type: integer, description: Seconds paused ($0 compute). }
        always_on_days: { type: number, description: Days billed at the always-on monthly price (prorated). }
        snapshot_gb_months: { type: number, description: Billable snapshot storage after the 30-day free period. }
        extra_disk_gb_months: { type: number }
        compute_cost_usd: { type: number }
        storage_cost_usd: { type: number }
        always_on_cost_usd: { type: number }
        total_cost_usd: { type: number }
    UsageReport:
      type: object
      required: [from, to, data, totals, has_more, next_cursor]
      properties:
        from: { type: string, format: date-time }
        to: { type: string, format: date-time }
        group_by: { type: string }
        data:
          type: array
          items: { $ref: "#/components/schemas/UsageItem" }
        totals:
          allOf:
            - $ref: "#/components/schemas/UsageItem"
            - type: object
              properties:
                credit_applied_usd: { type: number, description: Plan credit consumed this period. }
                credit_remaining_usd: { type: number, description: Unused plan credit; expires at period end (Starter/Team). }
                amount_due_usd: { type: number }
        has_more: { type: boolean }
        next_cursor: { type: [string, "null"] }
    Limits:
      type: object
      properties:
        plan: { type: string, enum: [free, starter, team, enterprise] }
        concurrent_sandboxes: { type: object, properties: { limit: { type: integer }, used: { type: integer } } }
        bulk_fork:
          type: object
          description: "Maximum `count` of one bulk fork for this account (plan default or a raised limit)."
          properties:
            max_count: { type: integer, example: 50 }
        new_account:
          type: object
          description: |
            Stricter defaults for new Free accounts that are not verified yet (no card, no GitHub verification):
            no bulk fork and 30 starts per minute, until `until` or verification.
          properties:
            active: { type: boolean }
            until: { type: [string, "null"], format: date-time }
            verified: { type: boolean }
        free_hours_remaining: { type: [number, "null"], description: "Free plan only: remaining one-time `default` hours." }
        can_create: { type: boolean }
        rate_limits:
          type: object
          properties:
            requests_per_minute: { type: integer }
            starts_per_minute: { type: integer }
        spend_limit: { $ref: "#/components/schemas/SpendLimit" }
        period_spend_usd: { type: number }
    SpendLimit:
      type: object
      properties:
        monthly_limit_usd: { type: [number, "null"], minimum: 0 }
        on_limit: { type: string, enum: [pause_running, block_new], default: pause_running }
        alert_thresholds:
          type: array
          items: { type: integer, minimum: 1, maximum: 100 }
          default: [50, 80, 100]
    Account:
      type: object
      required: [id, plan]
      properties:
        id: { type: string, example: acc_7kq2mxa9b3cd }
        name: { type: string }
        plan: { type: string, enum: [free, starter, team, enterprise] }
        billing_period_start: { type: string, format: date-time }
        billing_period_end: { type: string, format: date-time }
        created_at: { type: string, format: date-time }

    # ---------- api keys
    ApiKeyScope:
      type: string
      enum:
        - sandboxes:read
        - sandboxes:write
        - exec
        - files:read
        - files:write
        - ssh
        - desktop
        - snapshots:read
        - snapshots:write
        - templates:read
        - templates:write
        - webhooks:manage
        - usage:read
        - account:read
        - account:manage
        - api_keys:manage
    CreateApiKeyRequest:
      type: object
      required: [name]
      properties:
        name: { type: string, maxLength: 120 }
        scopes:
          type: array
          items: { $ref: "#/components/schemas/ApiKeyScope" }
        preset:
          type: string
          description: |
            `read-only`: all `:read` scopes. `full-sandbox`: sandboxes:read/write, exec, files:read/write, ssh, desktop,
            snapshots:read/write, templates:read. `ci`: full-sandbox without ssh and desktop. `admin`: all scopes.
          enum: [read-only, full-sandbox, ci, admin]
        restrict:
          type: object
          description: Limit the key to specific sandboxes. Sandboxes created with the key automatically receive the `labels`.
          properties:
            sandbox_ids: { type: array, items: { type: string } }
            labels: { $ref: "#/components/schemas/Labels" }
        expires_in_days:
          type: [integer, "null"]
          minimum: 1
          maximum: 365
          default: 90
          description: "`null` = never expires."
    ApiKey:
      type: object
      required: [id, name, scopes, prefix, created_at]
      properties:
        id: { type: string, example: key_6qe2mz4kxb7w }
        name: { type: string }
        prefix: { type: string, example: "taskcloud_sk_4Fh2", description: "First characters of the secret, for identification." }
        scopes:
          type: array
          items: { $ref: "#/components/schemas/ApiKeyScope" }
        restrict:
          type: [object, "null"]
          properties:
            sandbox_ids: { type: array, items: { type: string } }
            labels: { $ref: "#/components/schemas/Labels" }
        created_at: { type: string, format: date-time }
        expires_at: { type: [string, "null"], format: date-time }
        last_used_at: { type: [string, "null"], format: date-time }
        created_by_user_id: { type: [string, "null"], description: "Console user who created the key (list only; null for keys made with an API key)." }
    ApiKeyWithSecret:
      allOf:
        - $ref: "#/components/schemas/ApiKey"
        - type: object
          required: [secret]
          properties:
            secret: { type: string, example: "taskcloud_sk_4Fh2...", description: Shown once. }

    # ---------- console accounts
    Role:
      type: string
      enum: [owner, admin, member]
      description: |
        `owner`: everything, including granting `owner` and removing owners. `admin`: everything else
        (members, invitations, API keys of everyone, webhooks, spend limit, billing). `member`: sandboxes and
        their resources, usage and billing overview, own API keys only.
    MagicLinkRequest:
      type: object
      required: [email]
      properties:
        email: { type: string, format: email, maxLength: 254 }
        next: { type: string, maxLength: 512, pattern: "^/[^/\\\\]", description: "Console path to open after sign-in (relative only).", example: /sandboxes }
    MagicLinkSent:
      type: object
      required: [status]
      properties:
        status: { type: string, enum: [sent] }
        message: { type: string }
        dev_login_url: { type: string, description: Only on development deployments. }
    TokenRequest:
      type: object
      required: [token]
      properties:
        token: { type: string, maxLength: 128 }
    User:
      type: object
      required: [id, email, name, avatar_url]
      properties:
        id: { type: string, example: usr_5pq2kz7mwb3x }
        email: { type: string }
        name: { type: string }
        avatar_url: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
        two_factor_enabled: { type: boolean }
    OrganizationSummary:
      type: object
      required: [id, name, role, plan]
      properties:
        id: { type: string, example: acc_7kq2mxa9b3cd }
        name: { type: string }
        role: { $ref: "#/components/schemas/Role" }
        plan: { type: string, enum: [free, starter, team, enterprise] }
        require_2fa: { type: boolean, description: Members must use two-factor authentication. }
    Me:
      type: object
      required: [user, organizations, current_org_id]
      properties:
        user: { $ref: "#/components/schemas/User" }
        organizations:
          type: array
          items: { $ref: "#/components/schemas/OrganizationSummary" }
        current_org_id:
          type: [string, "null"]
          description: Organization the session acts in; `null` after the user was removed from it (switch to another one).
        csrf_token: { type: string, description: "Value for `X-CSRF-Token` (same as the `taskcloud_csrf` cookie)." }
        session_id: { type: string }
        two_factor_required:
          type: boolean
          description: The current organization requires 2FA and the user has not enabled it (organization operations return `403`).
    SignedIn:
      allOf:
        - $ref: "#/components/schemas/Me"
        - type: object
          properties:
            signup: { type: boolean, description: "`true` when this sign-in created the account." }
    TwoFactorChallenge:
      type: object
      required: [two_factor_required]
      properties:
        two_factor_required: { type: boolean, enum: [true] }
        methods: { type: array, items: { type: string, enum: [totp, recovery_code] } }
    TwoFactorCode:
      type: object
      required: [code]
      properties:
        code: { type: string, maxLength: 32, description: 6-digit TOTP code or a recovery code., example: "492039" }
    TwoFactorStatus:
      type: object
      required: [enabled, recovery_codes_remaining]
      properties:
        enabled: { type: boolean }
        enabled_at: { type: [string, "null"], format: date-time }
        recovery_codes_remaining: { type: integer, minimum: 0 }
    TotpEnrollment:
      type: object
      required: [secret, otpauth_uri, expires_at]
      properties:
        secret: { type: string, description: Base32 secret for manual entry., example: JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP }
        otpauth_uri: { type: string, example: "otpauth://totp/TaskCloud:ada@example.com?algorithm=SHA1&digits=6&issuer=TaskCloud&period=30&secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP" }
        expires_at: { type: string, format: date-time }
    PersonalDataExport:
      type: object
      required: [format, generated_at, user, organizations, sessions, two_factor, invitations, api_keys_created, audit_log]
      properties:
        format: { type: string, enum: [taskcloud.personal-data-export.v1] }
        generated_at: { type: string, format: date-time }
        user: { type: object }
        organizations: { type: array, items: { type: object } }
        sessions: { type: array, items: { type: object } }
        two_factor: { type: object }
        invitations: { type: array, items: { type: object } }
        api_keys_created: { type: array, items: { type: object } }
        audit_log: { type: array, items: { type: object } }
        notes: { type: array, items: { type: string } }
    ConsoleSession:
      type: object
      required: [id, current, created_at, last_seen_at, expires_at]
      properties:
        id: { type: string, example: ses_3ht7qm2zkx5d }
        current: { type: boolean }
        method: { type: string, enum: [magic_link, github] }
        ip: { type: string }
        user_agent: { type: string }
        created_at: { type: string, format: date-time }
        last_seen_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }
    Member:
      type: object
      required: [user_id, email, role, joined_at]
      properties:
        user_id: { type: string }
        email: { type: string }
        name: { type: string }
        avatar_url: { type: [string, "null"] }
        role: { $ref: "#/components/schemas/Role" }
        joined_at: { type: string, format: date-time }
        two_factor_enabled: { type: boolean }
    Invitation:
      type: object
      required: [id, email, role, status, created_at, expires_at]
      properties:
        id: { type: string, example: inv_6kd2qz5mxw3b }
        email: { type: string }
        role: { $ref: "#/components/schemas/Role" }
        status: { type: string, enum: [pending, accepted, revoked, expired] }
        invited_by: { type: string, description: "User ID, or `key:<id>` when an API key invited." }
        created_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }
        accepted_at: { type: [string, "null"], format: date-time }
        dev_accept_url: { type: string, description: Only on development deployments (create response). }
    Billing:
      type: object
      required: [plan, monthly_credit_usd, credit_remaining_usd, period_start, period_end, overage_usd, spend_limit_usd, payment_method, invoices]
      properties:
        plan: { type: string, enum: [free, starter, team, enterprise] }
        monthly_credit_usd: { type: number, description: "Plan credit per period ($0 on Free)." }
        credit_remaining_usd: { type: number, description: "Credit left in the period; on Free the one-time allowance left in $." }
        free_hours_remaining: { type: number, description: Free plan only. }
        free_hours_hold:
          type: [object, "null"]
          description: |
            Free plan only: the one-time Free hours are held until the account is verified (a card through checkout,
            or sign-in with a GitHub account older than 90 days). Reasons: a disposable e-mail domain, or many
            sign-ups from one network.
          required: [reason, hours]
          properties:
            reason: { type: string, enum: [disposable_email, signup_velocity] }
            hours: { type: integer, example: 20 }
        period_start: { type: string, format: date-time }
        period_end: { type: string, format: date-time }
        overage_usd: { type: number, description: Amount due above the credit in this period. }
        spend_limit_usd: { type: [number, "null"] }
        billing_status: { type: string, enum: [ok, past_due, unpaid] }
        payment_method:
          type: [object, "null"]
          required: [brand, last4]
          properties:
            brand: { type: string, example: visa }
            last4: { type: string, example: "4242" }
        invoices:
          type: array
          description: The newest invoices (up to 24). All of them, paginated, are at `GET /billing/invoices`.
          items: { $ref: "#/components/schemas/Invoice" }
    Invoice:
      type: object
      required: [id, date, amount_usd, status, pdf_url]
      properties:
        id: { type: string }
        date: { type: string, format: date-time }
        amount_usd: { type: number }
        status: { type: string }
        pdf_url: { type: [string, "null"] }
    RedirectUrl:
      type: object
      required: [url]
      properties:
        url: { type: string }