openapi: 3.0.3
info:
  title: Anona Compute API (Anona routes)
  version: "0.1.0"
  description: |
    Routes the Anona Compute gateway serves next to the E2B-compatible API:
    live-view viewer tokens, SSH certificates, network policy, the credential
    vault, usage and billing, webhooks and telemetry export, thumbnails, preview links,
    public ports, pause when idle, template builds, and API key management.
servers:
  - url: https://api.compute.anonalabs.com
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Live view
  - name: SSH
  - name: Sandbox access
  - name: Templates
  - name: Network
  - name: Credential vault
  - name: Usage and billing
  - name: Webhooks and telemetry
  - name: API keys
  - name: Service
paths:
  /v1/sandboxes/{sandboxID}/viewer-tokens:
    post:
      tags: [Live view]
      operationId: createViewerToken
      summary: Mint a viewer token
      description: |
        Mints a short-lived, signed viewer token for one sandbox and returns the
        embed URL that opens the live view with it. The token travels in the URL
        fragment (`#t=...`), which browsers never send to a server.

        `control` scope needs an API key, or a dashboard role of member or above.
        The key needs the `sandboxes:use` scope and, if it is limited to a list of
        sandboxes, this sandbox must be on it.
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ViewerTokenRequest"
            example:
              scope: view
              channels: [dom]
              ttlSeconds: 600
      responses:
        "200":
          description: The token and its embed URL.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewerToken"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/sandboxes/{sandboxID}/viewer-tokens:revoke-all:
    post:
      tags: [Live view]
      operationId: revokeViewerTokens
      summary: Revoke every viewer
      description: |
        Closes every open live view of the sandbox and invalidates every viewer
        token issued for it so far, by moving the sandbox's revocation epoch
        forward. Needs the same access as a `control` token.
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      responses:
        "200":
          description: The sandbox's new revocation epoch.
          content:
            application/json:
              schema:
                type: object
                required: [epoch]
                properties:
                  epoch:
                    type: integer
                    format: int64
                    description: Tokens carrying an older epoch no longer work.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/sandboxes/{sandboxID}/ssh-certs:
    post:
      tags: [SSH]
      operationId: createSshCertificate
      summary: Sign an SSH certificate
      description: |
        Signs an OpenSSH user certificate for the given public key. It is valid
        for 10 minutes, for this sandbox only, and logs in as `user`. It permits a
        PTY and port forwarding, so `ssh -L/-R`, `scp`, `rsync` and editor remote
        extensions work. Connect through the stream relay with
        `ProxyCommand anona-compute ssh --proxy <sandbox id>`.

        Needs an API key or a dashboard role of member or above, with the
        `sandboxes:use` scope.
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [publicKey]
              additionalProperties: false
              properties:
                publicKey:
                  type: string
                  description: OpenSSH public key (`ssh-ed25519`, `ecdsa-sha2-nistp256` or `ssh-rsa`).
                  example: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIA... you@laptop
      responses:
        "200":
          description: The signed certificate and how to connect.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SshCertificate"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/sandboxes/{sandboxID}/thumbnail:
    get:
      tags: [Live view]
      operationId: getThumbnail
      summary: Latest thumbnail
      description: |
        The sandbox's latest 320 px WebP thumbnail (its screen, or its active
        Chrome page). The sandbox grabs frames only while someone asks. Same
        access as a view token.
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      responses:
        "200":
          description: The image. Send its `ETag` back as `If-None-Match` to get 304 when it did not change.
          content:
            image/webp:
              schema: { type: string, format: binary }
        "204":
          description: Nothing to show yet (no display and no Chrome page), or the sandbox is paused.
        "304":
          description: Not modified.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/webhooks:
    get:
      tags: [Webhooks and telemetry]
      operationId: listWebhooks
      summary: List webhook endpoints
      description: The organization's endpoints and the event catalog. Owners and admins, or keys with `integrations:manage`.
      responses:
        "200":
          description: Endpoints and event types.
          content:
            application/json:
              schema:
                type: object
                required: [webhooks, eventTypes, maxWebhooks]
                properties:
                  webhooks: { type: array, items: { $ref: "#/components/schemas/Webhook" } }
                  eventTypes:
                    type: array
                    items:
                      type: object
                      required: [type]
                      properties:
                        type: { type: string }
                        aliases: { type: array, items: { type: string }, nullable: true }
                  maxWebhooks: { type: integer }
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags: [Webhooks and telemetry]
      operationId: createWebhook
      summary: Create a webhook endpoint
      description: Returns the signing secret (`whsec_...`) once. URLs must be https with a public host.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, url, events]
              properties:
                name: { type: string }
                url: { type: string, format: uri }
                events: { type: array, items: { type: string } }
                enabled: { type: boolean, default: true }
            example: { name: lifecycle, url: "https://example.com/anona/webhooks", events: [sandbox.lifecycle.created, sandbox.lifecycle.killed] }
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                type: object
                required: [webhook, secret]
                properties:
                  webhook: { $ref: "#/components/schemas/Webhook" }
                  secret: { type: string, pattern: "^whsec_" }
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          description: 10 endpoints per organization.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /v1/webhooks/{webhookID}:
    parameters:
      - name: webhookID
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Webhooks and telemetry]
      operationId: getWebhook
      summary: Get a webhook endpoint
      responses:
        "200":
          description: The endpoint.
          content:
            application/json:
              schema:
                type: object
                required: [webhook]
                properties:
                  webhook: { $ref: "#/components/schemas/Webhook" }
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      tags: [Webhooks and telemetry]
      operationId: updateWebhook
      summary: Update a webhook endpoint
      description: Any of `name`, `url`, `events`, `enabled`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                url: { type: string, format: uri }
                events: { type: array, items: { type: string } }
                enabled: { type: boolean }
      responses:
        "200":
          description: The updated endpoint.
          content:
            application/json:
              schema:
                type: object
                required: [webhook]
                properties:
                  webhook: { $ref: "#/components/schemas/Webhook" }
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      tags: [Webhooks and telemetry]
      operationId: deleteWebhook
      summary: Delete a webhook endpoint
      responses:
        "204":
          description: Deleted.
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/webhooks/{webhookID}/rotate-secret:
    post:
      tags: [Webhooks and telemetry]
      operationId: rotateWebhookSecret
      summary: Rotate the signing secret
      description: Returns the new secret once; the previous one keeps signing for 24 hours.
      parameters:
        - { name: webhookID, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: The new secret.
          content:
            application/json:
              schema:
                type: object
                required: [webhook, secret]
                properties:
                  webhook: { $ref: "#/components/schemas/Webhook" }
                  secret: { type: string, pattern: "^whsec_" }
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/webhooks/{webhookID}/test:
    post:
      tags: [Webhooks and telemetry]
      operationId: testWebhook
      summary: Send a test event
      description: Queues a `webhook.test` event to this endpoint.
      parameters:
        - { name: webhookID, in: path, required: true, schema: { type: string } }
      responses:
        "202":
          description: Queued.
          content:
            application/json:
              schema:
                type: object
                required: [eventId, deliveryId]
                properties:
                  eventId: { type: string }
                  deliveryId: { type: string }
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/webhooks/{webhookID}/deliveries:
    get:
      tags: [Webhooks and telemetry]
      operationId: listWebhookDeliveries
      summary: Delivery log
      description: Newest first, with every attempt.
      parameters:
        - { name: webhookID, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: The deliveries.
          content:
            application/json:
              schema:
                type: object
                required: [deliveries]
                properties:
                  deliveries:
                    type: array
                    items:
                      type: object
                      required: [id, eventId, eventType, status, attempts, createdAt, log]
                      properties:
                        id: { type: string }
                        eventId: { type: string }
                        eventType: { type: string }
                        sandboxId: { type: string }
                        occurredAt: { type: string, format: date-time }
                        status: { type: string, example: pending }
                        attempts: { type: integer }
                        lastStatusCode: { type: integer, nullable: true }
                        lastError: { type: string, nullable: true }
                        createdAt: { type: string, format: date-time }
                        lastAttemptAt: { type: string, format: date-time, nullable: true }
                        nextAttemptAt: { type: string, format: date-time, nullable: true }
                        log: { type: array, nullable: true, items: { type: object } }
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/webhooks/{webhookID}/deliveries/{deliveryID}/resend:
    post:
      tags: [Webhooks and telemetry]
      operationId: resendWebhookDelivery
      summary: Resend a delivery
      description: Queues the delivery again, also a dead one; the retry budget starts over.
      parameters:
        - { name: webhookID, in: path, required: true, schema: { type: string } }
        - { name: deliveryID, in: path, required: true, schema: { type: string } }
      responses:
        "202":
          description: Queued.
          content:
            application/json:
              schema:
                type: object
                required: [deliveryId, status]
                properties:
                  deliveryId: { type: string }
                  status: { type: string, example: pending }
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/otel-export:
    get:
      tags: [Webhooks and telemetry]
      operationId: getOtelExport
      summary: Get the OpenTelemetry export
      responses:
        "200":
          description: The export (null when none is set), its interval and the metrics it sends.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OtelExportResponse" }
        "403":
          $ref: "#/components/responses/Forbidden"
    put:
      tags: [Webhooks and telemetry]
      operationId: putOtelExport
      summary: Set the OpenTelemetry export
      description: |
        The OTLP/HTTP base URL (protobuf to `<endpoint>/v1/metrics` and
        `/v1/traces`), headers (encrypted at rest, never returned; omit to keep
        the stored ones) and whether it is enabled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [endpoint]
              properties:
                endpoint: { type: string, format: uri }
                headers: { type: object, additionalProperties: { type: string } }
                enabled: { type: boolean }
      responses:
        "200":
          description: The stored export.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/OtelExportResponse" }
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
    delete:
      tags: [Webhooks and telemetry]
      operationId: deleteOtelExport
      summary: Remove the OpenTelemetry export
      responses:
        "204":
          description: Removed.
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/api-keys:
    get:
      tags: [API keys]
      operationId: listApiKeys
      summary: List API keys
      description: |
        Lists the organization's API keys (never their secrets). Dashboard
        sessions only: API keys cannot list or manage keys. Every role may list.
      security:
        - DashboardBearer: []
      responses:
        "200":
          description: Every key of the organization, including revoked and expired ones.
          content:
            application/json:
              schema:
                type: object
                required: [apiKeys]
                properties:
                  apiKeys:
                    type: array
                    items:
                      $ref: "#/components/schemas/ApiKey"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags: [API keys]
      operationId: createApiKey
      summary: Create an API key
      description: |
        Creates an API key and returns its secret once. Dashboard sessions with
        the owner or admin role only.
      security:
        - DashboardBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApiKeyCreate"
            example:
              name: ci
              preset: create_and_use
              expiresInDays: 90
      responses:
        "201":
          description: The new key. `key` is the secret, shown only in this response.
          content:
            application/json:
              schema:
                type: object
                required: [apiKey, key]
                properties:
                  apiKey:
                    $ref: "#/components/schemas/ApiKey"
                  key:
                    type: string
                    pattern: "^(ac|e2b)_[0-9a-f]+$"
                    description: The secret. Store it now; it cannot be shown again.
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          description: The organization reached its API key limit.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/api-keys/{keyID}:
    delete:
      tags: [API keys]
      operationId: revokeApiKey
      summary: Revoke an API key
      description: Revokes a key at once. Dashboard sessions with the owner or admin role only.
      security:
        - DashboardBearer: []
      parameters:
        - name: keyID
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Revoked.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/sandboxes/{sandboxID}/preview-links:
    post:
      tags: [Sandbox access]
      operationId: createPreviewLink
      summary: Create a preview link
      description: |
        A signed link that opens one port of the sandbox in a browser until it
        expires. The edge exchanges it for a cookie scoped to that port's host.
        Port 49983 (envd) cannot be shared. Needs `sandboxes:use`.
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [port]
              properties:
                port: { type: integer, minimum: 1, maximum: 65535 }
                ttlSeconds: { type: integer, minimum: 60, maximum: 86400, default: 3600 }
            example: { port: 3000, ttlSeconds: 900 }
      responses:
        "201":
          description: The link.
          content:
            application/json:
              schema:
                type: object
                required: [url, sandboxID, port, expiresAt]
                properties:
                  url: { type: string, format: uri }
                  sandboxID: { type: string }
                  port: { type: integer }
                  expiresAt: { type: string, format: date-time }
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/sandboxes/{sandboxID}/preview-links:revoke-all:
    post:
      tags: [Sandbox access]
      operationId: revokePreviewLinks
      summary: Revoke every preview link
      description: Ends every preview link and every live-view token of the sandbox.
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      responses:
        "204":
          description: Revoked.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/sandboxes/{sandboxID}/access:
    get:
      tags: [Sandbox access]
      operationId: getSandboxAccess
      summary: Access settings
      description: Public traffic, public ports and the idle-pause time of a sandbox. Needs `sandboxes:read`.
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      responses:
        "200":
          description: The settings.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SandboxAccess" }
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/sandboxes/{sandboxID}/ports/{port}:
    put:
      tags: [Sandbox access]
      operationId: setPortPublic
      summary: Make a port public or private
      parameters:
        - $ref: "#/components/parameters/sandboxID"
        - { name: port, in: path, required: true, schema: { type: integer, minimum: 1, maximum: 65535 } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [public]
              properties:
                public: { type: boolean }
      responses:
        "200":
          description: The sandbox's access settings.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SandboxAccess" }
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/sandboxes/{sandboxID}/auto-pause:
    put:
      tags: [Sandbox access]
      operationId: setIdlePause
      summary: Set pause when idle
      description: Pause the sandbox after this many minutes with no traffic, sessions or envd processes. 0 turns it off.
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [idleMinutes]
              properties:
                idleMinutes: { type: integer, minimum: 0, maximum: 10080 }
      responses:
        "200":
          description: The sandbox's access settings.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SandboxAccess" }
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/sandboxes/{sandboxID}/name:
    put:
      tags: [Sandbox access]
      operationId: setSandboxName
      summary: Rename a sandbox
      description: |
        Sets the sandbox's human name, which is the `name` key of its metadata.
        Set it at create time with `metadata: {"name": "..."}` and filter on it
        with the ordinary metadata filter. Other metadata keys are left alone;
        the sandbox ID stays the identifier. `""` removes the name.
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  maxLength: 64
                  description: 1 to 64 letters, digits, spaces, dots, dashes or underscores, starting with a letter or digit. Trimmed; "" removes the name.
      responses:
        "200":
          description: The sandbox's name after the change.
          content:
            application/json:
              schema:
                type: object
                required: [sandboxID, name]
                properties:
                  sandboxID: { type: string }
                  name: { type: string, description: '"" when the sandbox has no name.' }
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/network:
    get:
      tags: [Network]
      operationId: getTeamNetwork
      summary: Get team egress settings
      description: |
        The organization's default egress policy for new sandboxes (used when
        neither the create request nor the template has one), what it compiles
        to under your plan, and the plan's limits. Any role or key may read it.
      responses:
        "200":
          description: The settings. `revision` is 0 and `spec` is `{}` when they were never set.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamNetwork"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Network]
      operationId: putTeamNetwork
      summary: Set team egress settings
      description: |
        Replaces the team egress settings. The body is a network policy in the
        E2B shape (the fields of a create's `network` object, plus
        `allow_internet_access`). Owners and admins, or unrestricted API keys
        (no scopes and no sandbox list). Header values in `rules` may only be
        vault placeholders such as `Bearer ${vault.openai_key}`. A rule here
        makes one binding that every sandbox created under these settings
        uses.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NetworkSpec"
            example:
              allow_internet_access: false
              allowOut: [pypi.org, files.pythonhosted.org]
      responses:
        "200":
          description: Stored and compiled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PolicyResult"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/sandboxes/{sandboxID}/network/effective:
    get:
      tags: [Network]
      operationId: getEffectiveNetwork
      summary: Effective policy of a sandbox
      description: The policy the sandbox runs with, and which layer it came from.
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      responses:
        "200":
          description: The compiled policy.
          content:
            application/json:
              schema:
                type: object
                required: [sandboxID, source, tier, policy]
                properties:
                  sandboxID: { type: string }
                  source:
                    type: string
                    enum: [sandbox, template, tenant_default, tier_default]
                  tier: { type: string, example: paid }
                  policy: { $ref: "#/components/schemas/CompiledPolicy" }
                  warnings: { type: array, items: { type: string } }
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/templates/{templateID}/network:
    put:
      tags: [Network]
      operationId: putTemplateNetwork
      summary: Set a template's egress policy
      description: |
        The default policy of sandboxes created from one of your own templates.
        The built-in templates are read-only (403); custom templates are coming
        soon.
      parameters:
        - name: templateID
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NetworkSpec"
      responses:
        "200":
          description: Stored and compiled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PolicyResult"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/vault/secrets:
    get:
      tags: [Credential vault]
      operationId: listVaultSecrets
      summary: List secrets
      description: Names, versions and bindings of the organization's secrets. Values are never returned.
      responses:
        "200":
          description: The secrets, and whether the vault is configured on this deployment.
          content:
            application/json:
              schema:
                type: object
                required: [secrets, enabled]
                properties:
                  secrets:
                    type: array
                    items: { $ref: "#/components/schemas/VaultSecret" }
                  enabled: { type: boolean }
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Credential vault]
      operationId: createVaultSecret
      summary: Store a secret
      description: |
        Stores a secret, encrypted at rest. Reference it from a network rule as
        `${vault.<name>}`; the egress proxy adds it to requests to that host, and
        the sandbox never sees the value. `allowedHosts` is required: a body
        without it, or with an empty list, is refused with 400. Owners and
        admins, or unrestricted API keys (no scopes and no sandbox list).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, value, allowedHosts]
              additionalProperties: false
              properties:
                name:
                  type: string
                  pattern: "^[a-z][a-z0-9_]{0,62}$"
                value:
                  type: string
                  maxLength: 8192
                allowedHosts:
                  $ref: "#/components/schemas/VaultAllowedHosts"
            example: { name: openai_key, value: sk-..., allowedHosts: [api.openai.com] }
      responses:
        "201":
          description: Stored. The value is not echoed.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VaultSecret" }
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: A secret with this name exists; add a version to rotate it.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "503":
          description: The vault is not configured on this deployment.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /v1/vault/secrets/{name}/versions:
    post:
      tags: [Credential vault]
      operationId: rotateVaultSecret
      summary: Rotate a secret
      description: |
        Adds a new version. Egress proxies cache values for up to 60 seconds.
        With `allowedHosts`, the secret's allowed hosts are replaced in the
        same call; without it they stay as they are. Owners and admins, or
        unrestricted API keys (no scopes and no sandbox list).
      parameters:
        - name: name
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [value]
              additionalProperties: false
              properties:
                value: { type: string, maxLength: 8192 }
                allowedHosts:
                  $ref: "#/components/schemas/VaultAllowedHosts"
      responses:
        "201":
          description: The secret after the rotation, as the list shows it - the new version, its allowed hosts (the kept list when `allowedHosts` was left out) and its bindings, which carry on unchanged.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VaultSecret" }
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/vault/secrets/{name}/allowed-hosts:
    put:
      tags: [Credential vault]
      operationId: setVaultAllowedHosts
      summary: Set a secret's allowed hosts
      description: |
        Replaces the hosts a secret may be sent to. Narrowing takes effect at
        once: a binding whose host is no longer on the list stops working, and
        a rule naming that host is refused with 403. A secret stored before
        allowed hosts existed has an empty list and cannot be used until one is
        set here. Owners and admins, or unrestricted API keys (no scopes and no
        sandbox list).
      parameters:
        - name: name
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [allowedHosts]
              additionalProperties: false
              properties:
                allowedHosts:
                  $ref: "#/components/schemas/VaultAllowedHosts"
            example: { allowedHosts: [api.github.com, uploads.github.com] }
      responses:
        "200":
          description: The secret with its new list, and its bindings as the list shows them.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VaultSecret" }
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/vault/secrets/{name}:
    delete:
      tags: [Credential vault]
      operationId: deleteVaultSecret
      summary: Delete a secret
      parameters:
        - name: name
          in: path
          required: true
          schema: { type: string }
      responses:
        "204":
          description: Deleted. Policies that reference it stop compiling.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/vault/bindings/{bindingID}:
    delete:
      tags: [Credential vault]
      operationId: revokeVaultBinding
      summary: Revoke a binding
      description: Stops one secret from being injected for one host and header.
      parameters:
        - name: bindingID
          in: path
          required: true
          schema: { type: string }
      responses:
        "204":
          description: Revoked.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/templates/{templateID}/builds/{buildID}/dockerfile:
    post:
      tags: [Templates]
      operationId: startDockerfileBuild
      summary: Build from a Dockerfile
      description: |
        Starts a build from a Dockerfile and a build context uploaded through
        the E2B file links, instead of E2B's step list. This is what
        `anona-compute template build` uses.
      parameters:
        - { name: templateID, in: path, required: true, schema: { type: string } }
        - { name: buildID, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [dockerfile, contextHash]
              properties:
                dockerfile:
                  type: string
                  description: The Dockerfile's contents.
                contextHash:
                  type: string
                  description: sha256 of the uploaded build context, 64 lowercase hex characters.
                startCmd:
                  type: string
                  description: Command to run when a sandbox starts, after envd.
                noCache:
                  type: boolean
      responses:
        "202":
          description: The build was queued.
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/templates/{templateID}/builds/{buildID}/events:
    get:
      tags: [Templates]
      operationId: streamBuildEvents
      summary: Stream build events
      description: |
        Newline-delimited JSON: one object per log line and status change,
        ending when the build is ready or failed. `anona-compute template
        build` and the dashboard follow a build with it.
      parameters:
        - { name: templateID, in: path, required: true, schema: { type: string } }
        - { name: buildID, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: The event stream.
          content:
            application/x-ndjson:
              schema: { type: string }
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/usage:
    get:
      tags: [Usage and billing]
      operationId: getUsage
      summary: Usage and cost
      description: |
        Metered usage and its cost for a billing period: meters, totals (rated,
        not yet rated, credit, due) with a projection for the current month, a
        daily breakdown, every template, and the period's sandboxes, most
        expensive first, a page at a time.
        Dashboard sessions of any role; API keys with the `usage:read` scope.

        `sandboxes` holds `limit` rows (50 unless you pass it, at most 1000).
        `sandboxCount` is how many sandboxes had usage in the period, on every
        page. While more remain the response carries `nextCursor`: pass it back
        as `cursor`, with the same `period`, for the next page. A closed
        period pages the same way every time; in the current month costs are
        still moving, so a sandbox can change pages between requests. To read
        one sandbox's row wherever it ranks, pass `sandboxId` instead.

        Usage arrives a minute at a time: a minute is included within about 35
        seconds of its end, so the minute a sandbox was deleted in shows up
        that long after the minute is over, not at the delete. Read again after
        that before comparing running time with a sandbox's lifetime.
      parameters:
        - name: period
          in: query
          schema:
            type: string
            pattern: "^(current|\\d{4}-\\d{2})$"
            default: current
        - name: limit
          in: query
          description: Sandboxes per page.
          schema: { type: integer, minimum: 1, maximum: 1000, default: 50 }
        - name: cursor
          in: query
          description: >-
            The `nextCursor` of the previous page, for the same `period`.
            Opaque; a cursor from another period is a 400.
          schema: { type: string }
        - name: sandboxId
          in: query
          description: >-
            Return only this sandbox's row (an empty `sandboxes` if it had no
            usage in the period) instead of a page. Cannot be combined with
            `cursor`.
          schema: { type: string, maxLength: 128 }
      responses:
        "200":
          description: The usage document.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Usage" }
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "502":
          description: The usage service is unavailable; retry.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /v1/billing:
    get:
      tags: [Usage and billing]
      operationId: getBilling
      summary: Plan, rates and invoices
      description: Dashboard owners and admins; API keys with the `billing:read` scope.
      responses:
        "200":
          description: The billing document.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Billing" }
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "502":
          description: The usage service is unavailable; retry.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /.well-known/anona-ssh-user-ca.pub:
    get:
      tags: [SSH]
      operationId: getSshUserCa
      summary: SSH user CA public key
      description: The public key of the CA that signs sandbox SSH certificates, in authorized_keys form.
      security: []
      responses:
        "200":
          description: One line, `ssh-ed25519 AAAA...`.
          content:
            text/plain:
              schema:
                type: string
  /.well-known/stream-jwks.json:
    get:
      tags: [Live view]
      operationId: getStreamJwks
      summary: Viewer token keys
      description: The Ed25519 public keys (JWKS) that verify viewer tokens.
      security: []
      responses:
        "200":
          description: A JSON Web Key Set.
          content:
            application/json:
              schema:
                type: object
                required: [keys]
                properties:
                  keys:
                    type: array
                    items:
                      type: object
                      properties:
                        kty: { type: string, example: OKP }
                        crv: { type: string, example: Ed25519 }
                        x: { type: string }
                        kid: { type: string }
                        alg: { type: string, example: EdDSA }
                        use: { type: string, example: sig }
  /healthz:
    get:
      tags: [Service]
      operationId: healthz
      summary: Health check
      security: []
      responses:
        "200":
          description: The gateway is up.
  /version:
    get:
      tags: [Service]
      operationId: version
      summary: Gateway version
      security: []
      responses:
        "200":
          description: The running gateway build.
          content:
            application/json:
              schema:
                type: object
                required: [version]
                properties:
                  version:
                    type: string
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: An Anona Compute API key (`ac_` followed by lowercase hex; older keys start with `e2b_`).
    BearerAuth:
      type: http
      scheme: bearer
      description: "The same API key, sent as `Authorization: Bearer ac_...`."
    DashboardBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: A dashboard session token (EdDSA JWT issued by compute.anonalabs.com). API keys are refused.
  parameters:
    sandboxID:
      name: sandboxID
      in: path
      required: true
      schema:
        type: string
  responses:
    BadRequest:
      description: The request body is invalid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: No valid API key or session.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: The key's scopes or the caller's role do not allow this.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Not found, or not yours (the answer is the same, so IDs cannot be probed).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    SandboxAccess:
      type: object
      required: [sandboxID, allowPublicTraffic, publicPorts, idlePauseMinutes]
      properties:
        sandboxID: { type: string }
        allowPublicTraffic: { type: boolean }
        publicPorts: { type: array, items: { type: integer }, nullable: true }
        idlePauseMinutes: { type: integer, description: "0: off" }
    Webhook:
      type: object
      required: [id, name, url, events, enabled, secretHint, createdAt, updatedAt]
      properties:
        id: { type: string }
        name: { type: string }
        url: { type: string }
        events: { type: array, items: { type: string } }
        enabled: { type: boolean }
        secretHint: { type: string, description: The secret's last characters }
        previousSecretValidUntil: { type: string, format: date-time, nullable: true }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        lastDeliveryAt: { type: string, format: date-time, nullable: true }
        lastDeliveryStatus: { type: string, nullable: true }
        failingDeliveries: { type: integer }
        deadDeliveries: { type: integer }
    OtelExportResponse:
      type: object
      required: [export, intervalSeconds, metrics]
      properties:
        export:
          type: object
          nullable: true
          required: [endpoint, headerNames, enabled]
          properties:
            endpoint: { type: string }
            headerNames: { type: array, items: { type: string }, nullable: true }
            enabled: { type: boolean }
            updatedAt: { type: string, format: date-time }
            lastExportAt: { type: string, format: date-time, nullable: true }
            lastError: { type: string, nullable: true }
            lastErrorAt: { type: string, format: date-time, nullable: true }
        intervalSeconds: { type: integer }
        metrics: { type: array, items: { type: string } }
    NetworkSpec:
      type: object
      description: An egress policy in the E2B wire shape. Unknown keys are refused.
      properties:
        allow_internet_access: { type: boolean }
        allowOut: { type: array, items: { type: string }, description: "IPs, CIDRs or exact host names to allow. Wildcard names such as *.example.com are refused with 400." }
        denyOut: { type: array, items: { type: string }, description: "IPv4 addresses or CIDRs to block; 0.0.0.0/0 blocks all public egress" }
        dnsServers: { type: array, items: { type: string }, description: "Sandboxes always resolve through 1.1.1.1 and 1.0.0.1. Another IPv4 address here is allowed as a destination when allowOut has a host name and public egress is off; the free plan accepts only those two." }
        rules:
          type: object
          description: 'Per-host header transforms: {host: [{transform: {headers: {Name: "Bearer ${vault.name}"}}}]}. Each key is one exact host (a wildcard is refused with 400), and each header value one vault placeholder (a literal value is refused with 400).'
          additionalProperties:
            type: array
            items: { type: object }
        allowPublicTraffic: { type: boolean }
    CompiledPolicy:
      type: object
      description: The policy as it is enforced.
      properties:
        allow_internet_access: { type: boolean }
        allowOut: { type: array, items: { type: string }, nullable: true }
        denyOut: { type: array, items: { type: string }, nullable: true }
    PolicyResult:
      type: object
      required: [scope, scopeID, revision]
      properties:
        scope: { type: string, enum: [tenant_default, template, sandbox, tenant_ceiling] }
        scopeID: { type: string }
        revision: { type: integer }
        compiled: { $ref: "#/components/schemas/CompiledPolicy" }
        warnings: { type: array, items: { type: string } }
    TeamNetwork:
      type: object
      required: [tier, limits, revision, spec, compiled]
      properties:
        tier: { type: string, example: paid }
        limits:
          type: object
          required: [internetAllowed, defaultInternet, allowCustomDNS, maxAllowOut, maxDomainAllows, maxDenyOut, maxRules]
          properties:
            internetAllowed: { type: boolean }
            defaultInternet: { type: boolean }
            allowCustomDNS: { type: boolean }
            maxAllowOut: { type: integer }
            maxDomainAllows: { type: integer }
            maxDenyOut: { type: integer }
            maxRules: { type: integer }
        revision: { type: integer }
        spec: { $ref: "#/components/schemas/NetworkSpec" }
        ceiling: { type: object }
        compiled: { $ref: "#/components/schemas/CompiledPolicy" }
        warnings: { type: array, items: { type: string } }
    VaultAllowedHosts:
      type: array
      minItems: 1
      maxItems: 64
      items: { type: string }
      description: |
        The hosts this secret may be sent to. Each entry is one of:
        an exact host (`api.github.com`, that host only); `*.` and a domain
        (`*.github.com`, any host under `github.com` but not `github.com`
        itself, so list both when you need both); or `*` on its own, for any
        host. Entries are bare host names: no scheme, port or path. A rule
        that aims the secret at a host outside the list is refused with 403.
      example: [api.github.com]
    VaultSecret:
      type: object
      required: [name, version, allowedHosts, createdAt, updatedAt, bindings]
      properties:
        name: { type: string }
        version: { type: integer }
        allowedHosts:
          type: array
          items: { type: string }
          description: The hosts this secret may be sent to. Empty for a secret stored before allowed hosts existed, which cannot be used until a list is set.
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        bindings:
          type: array
          nullable: true
          description: |
            Where the secret is in use: one entry per host and header. A rule in
            a sandbox's create request or network update is bound for that
            sandbox alone (`scope` `sandbox`, `scopeID` the sandbox ID), so two
            sandboxes with the same rule have two bindings. A rule in the team
            egress settings or a template's policy is bound once (`scope`
            `tenant_default` or `template`) and used by every sandbox under it.
            A sandbox's own bindings are revoked when it ends (deleted, timed out
            or failed) and drop out of this list; a paused sandbox keeps them.
          items:
            type: object
            required: [id, secret, scope, scopeID, host, header, format]
            properties:
              id: { type: string }
              secret: { type: string }
              scope: { type: string, enum: [tenant_default, template, sandbox] }
              scopeID: { type: string }
              host: { type: string }
              header: { type: string }
              format: { type: string, example: "Bearer ${SECRET}" }
              createdAt: { type: string, format: date-time }
    Tenant:
      type: object
      required: [id, slug, planId]
      properties:
        id: { type: string }
        slug: { type: string }
        name: { type: string }
        planId: { type: string }
        planName: { type: string }
        billingModel: { type: string }
        status: { type: string }
    Usage:
      type: object
      required: [tenant, period, availablePeriods, meters, totals, daily, sandboxes, sandboxCount, templates]
      properties:
        tenant: { $ref: "#/components/schemas/Tenant" }
        period:
          type: object
          required: [key, start, end, asOf, current]
          properties:
            key: { type: string, example: 2026-10 }
            start: { type: string, format: date-time }
            end: { type: string, format: date-time }
            asOf: { type: string, format: date-time }
            ratedThrough: { type: string, format: date-time }
            current: { type: boolean }
        availablePeriods: { type: array, items: { type: string } }
        meters:
          type: array
          items:
            type: object
            required: [meter, unit, quantity, unitPriceUsd, amountUsd]
            properties:
              meter: { type: string, example: vcpu_hours }
              unit: { type: string }
              quantity: { type: number }
              unitPriceUsd: { type: number }
              ratedUsd: { type: number }
              pendingUsd: { type: number }
              amountUsd: { type: number }
        totals:
          type: object
          required: [ratedUsd, pendingUsd, amountUsd, creditUsd, dueUsd]
          properties:
            ratedUsd: { type: number }
            pendingUsd: { type: number }
            amountUsd: { type: number }
            creditUsd: { type: number }
            dueUsd: { type: number }
            projectedUsd: { type: number }
        included:
          type: object
          description: >-
            The month against what the plan includes, on the allocated rate card
            (absent for months before the current plans). vCPU-hours each include
            2 GiB-hours of memory; storage is never included. On this rate card
            `totals.dueUsd` is `overageUsd` for a plan that bills it and 0 for
            Free, which stops instead.
          properties:
            vcpuHours: { $ref: "#/components/schemas/UsageIncludedLine" }
            gibHours: { $ref: "#/components/schemas/UsageIncludedLine" }
            egressGb: { $ref: "#/components/schemas/UsageIncludedLine" }
            storageGibHours: { $ref: "#/components/schemas/UsageIncludedLine" }
            overageUsd: { type: number, description: "What is over the included usage at the rate card, storage included." }
            atLimit: { type: string, enum: [stop, bill], description: "stop: Free, new sandboxes refused and running ones paused until the month ends. bill: paid plans." }
            exhausted: { type: boolean, description: An included amount is used up. }
        daily: { type: array, items: { type: object } }
        sandboxes:
          type: array
          description: >-
            One page of the period's sandboxes, most expensive first (see
            `limit`, `cursor` and `sandboxId`).
          items: { $ref: "#/components/schemas/UsageSandbox" }
        sandboxCount:
          type: integer
          description: Sandboxes with usage in the period, whatever the page.
        nextCursor:
          type: string
          description: >-
            Pass as `cursor` for the next page. Absent on the last page and
            for a `sandboxId` lookup.
        templates:
          type: array
          description: Every template used in the period, most expensive first.
          items: { $ref: "#/components/schemas/UsageTemplate" }
        lifecycle: { type: object }
    UsageIncludedLine:
      type: object
      properties:
        used: { type: number }
        included: { type: number, description: "Absent for storage, which no plan includes." }
        over: { type: number }
        unitPriceUsd: { type: number }
        overageUsd: { type: number }
    UsageSandbox:
      type: object
      description: |
        One sandbox's usage in the period. Two kinds of quantity are here and
        they are easy to confuse. **Allocated** quantities are the size the
        sandbox was created at times its running time; from the allocated rate
        card they are what is billed. **Consumed** quantities were
        the billed meters before it, measured
        from the CPU time the sandbox used and the memory it actually held, so
        a 4 vCPU sandbox that sat idle for an hour has `allocatedVcpuHours` 4
        and `vcpuHours` near 0.

        Running time counts from the sandbox's start to its delete (or pause),
        measured from samples every 10 seconds and clipped to the start and
        delete times. It never exceeds that span for a sandbox that was not
        paused, and usually falls short of it by a few seconds at most. After
        a resume it can exceed the true time by up to 10 seconds.
      required: [sandboxId, template, state, vcpu, memMib, runningHours, allocatedVcpuHours,
        allocatedGibHours, vcpuHours, gibHours, egressGib, snapshotGibHours, amountUsd]
      properties:
        sandboxId: { type: string, description: The sandbox's ID. }
        template: { type: string, description: "Template name, or the template ID if it has none; `unknown` if the sandbox is not in the registry." }
        state: { type: string, description: "The sandbox's state now: `running`, `paused`, `killed` (deleted), and so on." }
        vcpu: { type: integer, description: "Allocated vCPUs, the size it was created at." }
        memMib: { type: integer, description: "Allocated memory in MiB, the size it was created at." }
        runningHours: { type: number, description: "Hours it ran in the period: start to delete, minus time paused." }
        allocatedVcpuHours: { type: number, description: "Allocated: `vcpu` x `runningHours`. Not billed." }
        allocatedGibHours: { type: number, description: "Allocated: `memMib` / 1024 x `runningHours`. Not billed." }
        vcpuHours: { type: number, description: "Consumed: CPU time used, in vCPU-hours. Billed." }
        gibHours: { type: number, description: "Consumed: memory actually resident, in GiB-hours. Billed." }
        egressGib: { type: number, description: "Consumed: bytes sent to the internet, in GiB. Billed." }
        snapshotGibHours: { type: number, description: "Consumed: storage its pause snapshots used, in GiB-hours. Billed." }
        amountUsd: { type: number, description: "What its usage costs at your plan's rates, in USD; an estimate, not an invoice line." }
    UsageTemplate:
      type: object
      description: >-
        The sandboxes of one template in the period, summed. Allocated and
        consumed mean what they mean on `UsageSandbox`.
      required: [template, sandboxes, allocatedVcpuHours, allocatedGibHours, vcpuHours, gibHours, egressGib, amountUsd]
      properties:
        template: { type: string, description: "Template name, or `unknown`." }
        sandboxes: { type: integer, description: Sandboxes of this template with usage in the period. }
        allocatedVcpuHours: { type: number, description: "Allocated: the sum of its sandboxes' size x running time, in vCPU-hours. Not billed." }
        allocatedGibHours: { type: number, description: "Allocated: the same in GiB-hours. Not billed." }
        vcpuHours: { type: number, description: "Consumed: CPU time used, in vCPU-hours. Billed." }
        gibHours: { type: number, description: "Consumed: memory actually resident, in GiB-hours. Billed." }
        egressGib: { type: number, description: "Consumed: bytes sent to the internet, in GiB. Billed." }
        amountUsd: { type: number, description: "What its sandboxes' usage costs at your plan's rates, in USD; an estimate." }
    Billing:
      type: object
      required: [tenant, provider, rates, limits, invoices, asOf]
      properties:
        tenant: { $ref: "#/components/schemas/Tenant" }
        provider: { type: string, description: "`manual` while no payment provider is connected" }
        rates:
          type: array
          items:
            type: object
            required: [meter, unit, unitPriceUsd]
            properties:
              meter: { type: string }
              tier: { type: string }
              unit: { type: string }
              unitPriceUsd: { type: number }
              effectiveFrom: { type: string, format: date-time }
        limits:
          type: object
          properties:
            monthlyCreditUsd: { type: number }
            spendCapUsd: { type: number, nullable: true }
            maxConcurrentSandboxes: { type: integer }
        state: { type: object, nullable: true }
        invoices: { type: array, items: { type: object } }
        asOf: { type: string, format: date-time }
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: integer
          description: The HTTP status code.
        message:
          type: string
        error_code:
          type: string
          description: Machine-readable reason, on some errors (for example `invalid_request`).
    ViewerTokenRequest:
      type: object
      additionalProperties: false
      properties:
        scope:
          type: string
          enum: [view, control]
          default: view
          description: "`view` watches; `control` also sends input (terminal keystrokes, desktop mouse and keyboard)."
        channels:
          type: array
          items:
            type: string
            enum: [dom, pty, desktop, thumb, ssh]
          default: [dom]
          description: What the token opens. The first channel picks the embed view (`pty` opens the terminal view).
        ttlSeconds:
          type: integer
          minimum: 30
          maximum: 600
          default: 600
    ViewerToken:
      type: object
      required: [token, expiresAt, embedUrl]
      properties:
        token:
          type: string
          description: Compact JWS (EdDSA, `typ` `anona-view+jwt`).
        expiresAt:
          type: string
          format: date-time
        embedUrl:
          type: string
          format: uri
          description: The live-view page for an iframe, with the token in the fragment.
    SshCertificate:
      type: object
      required: [certificate, user, host, proxyCommand, expiresAt]
      properties:
        certificate:
          type: string
          description: OpenSSH certificate (`ssh-ed25519-cert-v01@openssh.com ...`); save it as `<key>-cert.pub`.
        user:
          type: string
          example: user
        host:
          type: string
          description: The sandbox ID, used as the SSH host name.
        proxyCommand:
          type: string
          example: anona-compute ssh --proxy sbx_123
        expiresAt:
          type: string
          format: date-time
    ApiKey:
      type: object
      required: [id, name, prefix, preset, scopes, sandboxIds, createdAt, lastUsedAt, expiresAt, revokedAt]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        prefix:
          type: string
          description: The first 8 characters of the secret, for recognising it.
        preset:
          type: string
          enum: [read_only, use_existing, create_and_use, full_access, custom]
        scopes:
          type: array
          items:
            type: string
        sandboxIds:
          type: array
          items:
            type: string
          description: When not empty, the key works only on these sandboxes.
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
        revokedAt:
          type: string
          format: date-time
          nullable: true
    ApiKeyCreate:
      type: object
      required: [name, preset]
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
        preset:
          type: string
          enum: [read_only, use_existing, create_and_use, full_access, custom]
          description: |
            `read_only`: sandboxes:read, templates:read, usage:read.
            `use_existing`: sandboxes:read, sandboxes:use.
            `create_and_use`: sandboxes:read, use, create, delete; templates:read.
            `full_access`: sandboxes:*, templates:*, usage:read, billing:read.
            `custom`: the scopes you list.
        scopes:
          type: array
          description: Only with `preset` `custom`.
          items:
            type: string
            enum: [sandboxes:read, sandboxes:use, sandboxes:create, sandboxes:delete, templates:read, templates:write, usage:read, billing:read, integrations:manage, vault:bind]
        sandboxIds:
          type: array
          items:
            type: string
          description: Limit the key to these sandbox IDs.
        expiresInDays:
          type: integer
          nullable: true
          enum: [7, 30, 90, 365]
          description: Omit or null for a key that never expires.
