components:
  parameters:
    BlaxelVersion:
      description: API version (e.g., 2026-04-16). Defaults to the earliest stable
        version if omitted. See https://docs.blaxel.ai/api-reference/introduction#api-versioning.
      in: header
      name: Blaxel-Version
      required: false
      schema:
        type: string
    ExternalIdFilter:
      description: Filter resources by metadata.externalId. When set, only resources
        matching this caller-owned external ID are returned.
      in: query
      name: externalId
      required: false
      schema:
        maxLength: 64
        pattern: ^[a-zA-Z0-9-]*$
        type: string
    ListingStatus:
      description: Comma-separated list of statuses to filter on (e.g. `DEPLOYED,FAILED`).
        Values are case-insensitive; unknown values are rejected with a 400. Selecting
        every status is equivalent to omitting the parameter. Bound into the cursor
        fingerprint so a cursor opened with one selection cannot be reused with another.
        Filtering itself requires the 2026-04-28 Blaxel-Version (the paginated listing);
        on earlier versions the value is still validated but the listing is unfiltered,
        except for sandboxes where it is applied on every version.
      example: DEPLOYED,FAILED
      in: query
      name: status
      required: false
      schema:
        type: string
    PaginationAnchor:
      description: Start from a known pagination boundary. `end` is only supported
        for `createdAt` listings (asc or desc) and returns the tail page directly
        without walking every cursor from the first page.
      in: query
      name: anchor
      required: false
      schema:
        enum:
        - end
        type: string
    PaginationCursor:
      description: Opaque cursor returned by a previous response's meta.nextCursor.
        Only valid for the same query (workspace + filters); the server rejects cursors
        bound to a different query or older than 24h. Omit on the first page.
      in: query
      name: cursor
      required: false
      schema:
        type: string
      x-stainless-pagination-property:
        purpose: next_cursor_param
    PaginationLimit:
      description: Maximum number of items to return per page. Defaults to 50, clamped
        to 200.
      in: query
      name: limit
      required: false
      schema:
        default: 50
        maximum: 200
        minimum: 1
        type: integer
    PaginationQuery:
      description: Substring search across `metadata.name`, `metadata.displayName`
        and labels (keys + values). Trimmed and lowercased server-side; queries shorter
        than 2 characters fall back to the unfiltered listing. Bound into the cursor
        fingerprint so a cursor opened with one query cannot be reused with another.
        Only honoured starting on Blaxel-Version 2026-04-28.
      in: query
      name: q
      required: false
      schema:
        maxLength: 200
        type: string
    PaginationSort:
      description: Sort spec, formatted as `<key>:<direction>`. Allowed values are
        `createdAt:desc` (default), `createdAt:asc`, `name:asc`, `name:desc`. The
        cursor fingerprint is bound to the sort, so a cursor opened with one value
        cannot be reused with another. Only honoured starting on Blaxel-Version 2026-04-28.
      in: query
      name: sort
      required: false
      schema:
        enum:
        - createdAt:desc
        - createdAt:asc
        - name:asc
        - name:desc
        type: string
  schemas:
    Agent:
      type: object
      description: Serverless AI agent deployment that runs your custom agent code
        as an auto-scaling API endpoint. Agents are deployed from your code repository
        and expose a global inference URL for querying.
      properties:
        events:
          $ref: '#/components/schemas/CoreEvents'
        metadata:
          $ref: '#/components/schemas/Metadata'
        spec:
          $ref: '#/components/schemas/AgentSpec'
        status:
          $ref: '#/components/schemas/Status'
      required:
      - metadata
      - spec
    AgentList:
      type: object
      description: Cursor-paginated list of agents. Returned starting with API version
        2026-04-28; older API versions return a bare array of agents instead.
      properties:
        data:
          type: array
          description: Page of agents.
          items:
            $ref: '#/components/schemas/Agent'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    AgentRuntime:
      type: object
      description: Runtime configuration defining how the AI agent is deployed and
        scaled globally
      properties:
        envs:
          type: array
          description: Environment variables injected into the agent. Supports Kubernetes
            EnvVar format with valueFrom references.
          items:
            $ref: '#/components/schemas/Env'
        generation:
          type: string
          description: 'Infrastructure generation: mk2 (containers, 2-10s cold starts,
            15+ global regions) or mk3 (microVMs, sub-25ms cold starts)'
          enum:
          - mk2
          - mk3
          example: mk3
        image:
          type: string
          description: Container image built by Blaxel when deploying with 'bl deploy'.
            This field is auto-populated during deployment.
        maxScale:
          type: integer
          description: Maximum number of concurrent agent instances for auto-scaling
            under load
          example: 10
        memory:
          type: integer
          description: Memory allocation in megabytes. Also determines CPU allocation
            (CPU cores = memory in MB / 2048, e.g., 4096MB = 2 CPUs).
          example: 2048
        minScale:
          type: integer
          description: Minimum instances to keep warm. Set to 1+ to eliminate cold
            starts, 0 for scale-to-zero.
          example: 0
    AgentSpec:
      type: object
      description: Configuration for an AI agent including runtime settings, repository
        source, and deployment triggers
      properties:
        enabled:
          type: boolean
          description: When false, the agent is disabled and will not serve inference
            requests
          example: true
          default: true
        policies:
          $ref: '#/components/schemas/PoliciesList'
        public:
          type: boolean
          description: When true, the agent is publicly accessible without authentication.
            Only available for mk3 generation.
          example: false
          default: false
        region:
          type: string
          description: Region where the agent should be deployed (e.g. us-pdx-1, eu-lon-1).
            Required when volumes are attached.
          example: us-pdx-1
        repository:
          $ref: '#/components/schemas/Repository'
        revision:
          $ref: '#/components/schemas/RevisionConfiguration'
        runtime:
          $ref: '#/components/schemas/AgentRuntime'
        triggers:
          $ref: '#/components/schemas/Triggers'
        volumes:
          $ref: '#/components/schemas/VolumeAttachments'
    ApiKey:
      type: object
      description: Long-lived API key for accessing Blaxel
      allOf:
      - $ref: '#/components/schemas/TimeFields'
      - $ref: '#/components/schemas/OwnerFields'
      - properties:
          apiKey:
            type: string
            description: Api key
            readOnly: true
          expires_in:
            type: string
            description: Duration until expiration. Supports formats like '30d' (30
              days), '24h' (24 hours), '1w' (1 week). Must be positive and at most
              10 years. If not set, the API key never expires.
            example: 30d
          id:
            type: string
            description: Api key id, to retrieve it from the API
            readOnly: true
            example: ak_abc123def456
          name:
            type: string
            description: Name for the API key
            example: CI/CD Pipeline Key
          sub:
            type: string
            description: User subject identifier
            readOnly: true
          sub_type:
            type: string
            description: Subject type (user or service_account)
            example: user
    AppRevision:
      type: object
      description: A single application revision containing the deployed image and
        configuration
      properties:
        createdAt:
          type: string
          description: When this revision was created
        createdBy:
          type: string
          description: Who created this revision
        envs:
          type: array
          description: Environment variables for this revision
          items:
            $ref: '#/components/schemas/Env'
        id:
          type: string
          description: Unique revision identifier
        image:
          type: string
          description: Container image for this revision (mandatory)
        memory:
          type: integer
          description: Memory allocation in megabytes. Determines CPU allocation (CPU
            = memory / 2048).
          example: 2048
        port:
          type: integer
          description: Port the application listens on for this revision (default
            uses spec-level port or 8080)
          example: 8080
        snapshot:
          type: string
          description: Snapshot ID this revision was forked from (optional, only set
            when created via fork)
      required:
      - image
    AppRevisionConfiguration:
      type: object
      description: Routing configuration controlling which revision is active and
        canary traffic splitting
      properties:
        active:
          type: string
          description: Active revision id
        canary:
          type: string
          description: Canary revision id
        canaryPercent:
          type: integer
          description: Canary revision percent (0-100)
          example: 10
        stickySessionTtl:
          type: integer
          description: Sticky session TTL in seconds (0 = disabled)
          example: 0
        traffic:
          type: integer
          description: Traffic percentage for deployment
          example: 100
    AppRevisions:
      type: array
      items:
        $ref: '#/components/schemas/AppRevision'
    AppUrl:
      type: object
      description: A single URL entry for the application. If the domain is a wildcard
        custom domain (e.g. *.sandbox.vybe.build), use subdomain to pick a specific
        subdomain. If the domain is a direct custom domain (e.g. app.vybe.build),
        subdomain is not needed.
      properties:
        domain:
          type: string
          description: Custom domain (must be a verified custom domain in the workspace).
            Can be a wildcard domain (e.g. sandbox.vybe.build registered as *.sandbox.vybe.build)
            or a direct domain (e.g. app.vybe.build).
          example: app.example.com
        subdomain:
          type: string
          description: Subdomain to use with a wildcard custom domain (optional)
          example: www
      required:
      - domain
    AppUrls:
      type: array
      description: URL configuration for the application. Each entry defines a custom
        URL through which the application is accessible. The domain must be a verified
        custom domain in the workspace.
      items:
        $ref: '#/components/schemas/AppUrl'
    Application:
      type: object
      description: Long-running application deployment that runs your custom code
        as a publicly accessible endpoint. Applications are always public and use
        mk3 generation.
      properties:
        events:
          $ref: '#/components/schemas/CoreEvents'
        metadata:
          $ref: '#/components/schemas/Metadata'
        nodeGeneration:
          type: string
          description: Infrastructure generation this application is deployed on (mk3.0
            or mk3.1).
          readOnly: true
        spec:
          $ref: '#/components/schemas/ApplicationSpec'
        status:
          type: string
          description: Application status computed from events
          readOnly: true
      required:
      - metadata
      - spec
    ApplicationExtension:
      type: object
      description: Configuration for a single application extension. The fields used
        depend on the extension key; for ai.blaxel.experimental/bind-to-sandbox only
        "sandbox" is used.
      properties:
        sandbox:
          type: string
          description: Name of the sandbox this application binds to (used by the
            ai.blaxel.experimental/bind-to-sandbox extension).
          example: my-sandbox
    ApplicationExtensions:
      type: object
      description: Map of experimental, opt-in application extensions keyed by fully-qualified
        extension name (e.g. "ai.blaxel.experimental/bind-to-sandbox").
      additionalProperties:
        $ref: '#/components/schemas/ApplicationExtension'
    ApplicationList:
      type: object
      description: Cursor-paginated list of applications. Returned starting with API
        version 2026-04-28; older API versions return a bare array of applications
        instead.
      properties:
        data:
          type: array
          description: Page of applications.
          items:
            $ref: '#/components/schemas/Application'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ApplicationSpec:
      type: object
      description: Configuration for an application including revision management,
        URL routing, and deployment region
      properties:
        enabled:
          type: boolean
          description: When false, the application is disabled and will not serve
            requests
          example: true
          default: true
        envs:
          type: array
          description: Environment variables for the application
          items:
            $ref: '#/components/schemas/Env'
        extensions:
          $ref: '#/components/schemas/ApplicationExtensions'
        image:
          type: string
          description: Container image for the application. The backend generates
            a revision from the spec-level compute (image, memory, envs, port) on
            every create/update — clients set the compute here, exactly like agents
            and functions, and never craft revisions by hand.
          example: my-registry/my-app:latest
        memory:
          type: integer
          description: Memory allocation in megabytes for the application (default
            2048). Determines CPU allocation (CPU = memory / 2048).
          example: 2048
        port:
          type: integer
          description: Port the application listens on (default 8080)
          example: 8080
        proxy:
          type: boolean
          description: When true, the application proxies to an existing sandbox (the
            active revision image is the sandbox name) instead of building and deploying
            its own compute. Proxy applications have no deployment pipeline and are
            always reported as deployed. Deprecated — prefer the ai.blaxel.experimental/bind-to-sandbox
            extension.
          example: false
          default: false
        region:
          type: string
          description: Region where the application is deployed (e.g. us-pdx-1, eu-lon-1)
          example: us-pdx-1
        revision:
          $ref: '#/components/schemas/AppRevisionConfiguration'
        revisions:
          $ref: '#/components/schemas/AppRevisions'
        urls:
          $ref: '#/components/schemas/AppUrls'
    Applications:
      type: array
      items:
        $ref: '#/components/schemas/Application'
    ChangelogEntry:
      type: object
      description: Changelog entry shown in the controlplane UI.
      properties:
        content:
          type: string
          description: Markdown body for the changelog entry.
        date:
          type: string
          description: Release date for the changelog entry in YYYY-MM-DD format.
          example: "2026-07-07"
        title:
          type: string
          description: Changelog entry title.
          example: New sandbox scheduling controls
      x-stainless-ignore: true
    ChangelogResponse:
      type: object
      description: Latest changelog entries shown in the controlplane UI.
      properties:
        entries:
          type: array
          description: Latest changelog entries, newest first.
          items:
            $ref: '#/components/schemas/ChangelogEntry'
      x-stainless-ignore: true
    Configuration:
      type: object
      description: Configuration
      properties:
        continents:
          type: array
          description: Continents
          items:
            $ref: '#/components/schemas/Continent'
        countries:
          type: array
          description: Countries
          items:
            $ref: '#/components/schemas/Country'
        detectedRegion:
          type: string
          description: Auto-detected closest region based on viewer geolocation (from
            CloudFront headers). Empty when geo headers are not available.
        privateLocations:
          type: array
          description: Private locations managed with blaxel operator
          items:
            $ref: '#/components/schemas/PrivateLocation'
        regions:
          type: array
          description: Regions
          items:
            $ref: '#/components/schemas/Region'
      x-stainless-ignore: true
    Continent:
      type: object
      description: Continent
      properties:
        displayName:
          type: string
          description: Continent display name
        name:
          type: string
          description: Continent code
      x-stainless-ignore: true
    CoreEvent:
      type: object
      description: Core event
      properties:
        canaryRevision:
          type: string
          description: Canary revisionID link to the event
        message:
          type: string
          description: Event message
          example: Deployment successful
        revision:
          type: string
          description: RevisionID link to the event
          example: rev-abc123
        status:
          type: string
          description: Event status
          example: DEPLOYED
        time:
          type: string
          description: Event time
          example: "2025-01-15T10:30:00Z"
        type:
          type: string
          description: Event type
          example: deployment
      readOnly: true
    CoreEvents:
      type: array
      description: Events happening on a resource deployed on Blaxel
      items:
        $ref: '#/components/schemas/CoreEvent'
      readOnly: true
    Country:
      type: object
      description: Configuration
      properties:
        displayName:
          type: string
          description: Country display name
        name:
          type: string
          description: Country code
      x-stainless-ignore: true
    CreateJobExecutionOutput:
      type: object
      description: Response returned when a job execution is successfully created.
        Contains identifiers and the tasks that will be executed.
      properties:
        executionId:
          type: string
          description: Unique identifier for the created execution. Use this ID to
            track execution status, retrieve logs, or cancel the execution.
          example: exec-abc123
        id:
          type: string
          description: Unique identifier for this request, used for idempotency and
            tracking. Auto-generated if not provided in the request.
          example: 550e8400-e29b-41d4-a716-446655440000
        jobId:
          type: string
          description: Name of the job that this execution belongs to
          example: data-processing-job
        tasks:
          type: array
          description: Array of task configurations that will be executed in parallel
            according to the job's concurrency settings. Each task can have custom
            parameters.
          items:
            type: object
        workspaceId:
          type: string
          description: Name of the workspace where the job execution was created
          example: my-workspace
    CreateJobExecutionRequest:
      type: object
      description: Request to create a job execution
      properties:
        allowQueue:
          type: boolean
          description: When false, capacity is checked synchronously and the request
            is rejected immediately with a 429 error if the execution cannot start
            right now, instead of being queued and retried in the background. No execution
            is created on rejection. Defaults to true (queue and retry).
        env:
          type: object
          description: Environment variable overrides (optional, will merge with job's
            environment variables)
          additionalProperties:
            type: string
          example: '{"MY_VAR": "custom_value", "BATCH_SIZE": "100"}'
        executionId:
          type: string
          description: Execution ID (optional, will be generated if not provided)
        id:
          type: string
          description: Unique message ID
        jobId:
          type: string
          description: Job ID
          example: data-processing-job
        memory:
          type: integer
          description: Memory override in megabytes (optional, must be lower than
            or equal to job's configured memory)
          example: 2048
        tasks:
          type: array
          description: Array of task parameters for parallel execution
          items:
            type: object
        workspaceId:
          type: string
          description: Workspace ID
    CustomDomain:
      type: object
      description: |-
        Custom domain for preview deployments
        The custom domain represents a base domain (e.g., example.com) that will be used
        to serve preview deployments. Each preview will be accessible at a subdomain:
        <preview-id>.preview.<base-domain> (e.g., abc123.preview.example.com)
      properties:
        metadata:
          $ref: '#/components/schemas/CustomDomainMetadata'
        spec:
          $ref: '#/components/schemas/CustomDomainSpec'
      required:
      - metadata
      - spec
      x-stainless-ignore: true
    CustomDomainMetadata:
      type: object
      description: Custom domain metadata
      allOf:
      - $ref: '#/components/schemas/TimeFields'
      - $ref: '#/components/schemas/OwnerFields'
      - properties:
          displayName:
            type: string
            description: Display name for the custom domain
            example: Preview Domain
          labels:
            $ref: '#/components/schemas/MetadataLabels'
          name:
            type: string
            description: Domain name (e.g., "example.com")
            example: preview.example.com
          sharedFromWorkspace:
            type: string
            description: If this custom domain is shared from another workspace of
              the same account, this field contains the name of the source (owning)
              workspace. Empty for owned domains.
            readOnly: true
          workspace:
            type: string
            description: Workspace name
    CustomDomainShareTarget:
      type: object
      description: A workspace (or the whole account) a custom domain is shared with
      properties:
        status:
          type: string
          description: Share status; always "active" for same-account custom domain
            shares.
        workspace:
          type: string
          description: The workspace the domain is shared with, or "account" for an
            account-wide share.
        workspaceDisplayName:
          type: string
          description: Display name of the target workspace (empty for an account-wide
            share).
      required:
      - workspace
      - status
      x-stainless-ignore: true
    CustomDomainSpec:
      type: object
      description: Custom domain specification
      properties:
        cnameRecords:
          type: string
          description: CNAME target for the domain
        domainType:
          type: string
          description: Type of custom domain (previews or applications)
          enum:
          - previews
          - applications
          example: applications
        fallbackPreviewId:
          type: string
          description: Preview ID to route to when a preview lookup fails on this
            custom domain
          example: my-fallback-preview
        lastVerifiedAt:
          type: string
          description: Last verification attempt timestamp
          readOnly: true
        region:
          type: string
          description: Region that the custom domain is associated with
          example: us-pdx-1
        status:
          type: string
          description: Current status of the domain (pending, verified, failed)
          enum:
          - pending
          - verified
          - failed
          readOnly: true
          example: verified
        subjectAlternativeNames:
          type: array
          description: Subject Alternative Names (SANs) for the ACM certificate. Only
            applicable for application domains.
          items:
            type: object
            additionalProperties: true
        txtRecords:
          type: object
          description: Map of TXT record names to values for domain verification
          additionalProperties:
            type: string
        validationMethod:
          type: string
          description: How the TLS certificate is validated. "dns" (default) requires
            the certificate validation CNAME records to be published; "http" validates
            over HTTP once the domain points to Blaxel and requires no validation
            record. HTTP validation is not available for wildcard domains (previews
            or "*." names) and cannot be changed after creation.
          enum:
          - dns
          - http
          example: dns
          default: dns
        verificationError:
          type: string
          description: Error message if verification failed
          readOnly: true
      x-stainless-ignore: true
    Drive:
      type: object
      description: Drive providing persistent storage that can be attached to agents,
        functions, and sandboxes. Drives can be mounted at runtime via the sbx API.
      properties:
        events:
          $ref: '#/components/schemas/CoreEvents'
        metadata:
          $ref: '#/components/schemas/Metadata'
        spec:
          $ref: '#/components/schemas/DriveSpec'
        state:
          $ref: '#/components/schemas/DriveState'
        status:
          type: string
          description: Drive status computed from events
          readOnly: true
      required:
      - metadata
      - spec
    DriveList:
      type: object
      description: Cursor-paginated list of drives. Returned starting with API version
        2026-04-28; older API versions return a bare array.
      properties:
        data:
          type: array
          description: Page of drives.
          items:
            $ref: '#/components/schemas/Drive'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    DrivePermission:
      type: object
      description: Permission that controls which workloads can access a drive. A
        workload must have ALL specified labels (AND logic). Permissions are evaluated
        with OR logic — the first matching permission grants access.
      properties:
        labels:
          type: object
          description: Labels that the workload must have. All labels must match (AND
            logic). Empty labels match all workloads.
        mode:
          type: string
          description: Access mode granted by this permission
          enum:
          - read
          - read-write
        path:
          type: string
          description: Subfolder path to restrict access to. Defaults to / (full drive).
          example: /data
    DriveSpec:
      type: object
      description: Immutable drive configuration set at creation time
      properties:
        permissions:
          type: array
          description: Permissions controlling which workloads can access this drive.
            Empty means all workloads in the workspace can access the drive. Maximum
            3 permissions.
          items:
            $ref: '#/components/schemas/DrivePermission'
        region:
          type: string
          description: Deployment region for the drive (e.g., us-pdx-1, eu-lon-1).
            Must match the region of resources it attaches to.
          example: us-pdx-1
    DriveState:
      type: object
      description: Current runtime state of the drive
      properties:
        s3Url:
          type: string
          description: S3-compatible endpoint URL for accessing drive contents
          readOnly: true
      readOnly: true
    EgressConfig:
      type: object
      description: Egress configuration for routing sandbox outbound traffic through
        a dedicated IP gateway
      properties:
        gateway:
          type: string
          description: Name of the egress gateway to route traffic through. The gateway
            must exist in the default VPC.
          example: egress-ip-gw-1
        mode:
          type: string
          description: Egress mode. Use 'dedicated' for a dedicated egress IP.
          example: dedicated
        policies:
          type: array
          description: Per-destination egress policies (not yet supported)
          items:
            $ref: '#/components/schemas/EgressPolicy'
    EgressGateway:
      type: object
      description: An egress gateway that manages outbound traffic routing within
        a VPC. Multiple egress IPs can be allocated from a single gateway.
      properties:
        events:
          $ref: '#/components/schemas/CoreEvents'
        metadata:
          $ref: '#/components/schemas/EgressGatewayMetadata'
        spec:
          $ref: '#/components/schemas/EgressGatewaySpec'
        status:
          $ref: '#/components/schemas/Status'
      required:
      - metadata
      - spec
    EgressGatewayMetadata:
      type: object
      description: Metadata for an egress gateway resource including workspace, VPC,
        and name
      allOf:
      - $ref: '#/components/schemas/TimeFields'
      - $ref: '#/components/schemas/OwnerFields'
      - properties:
          displayName:
            type: string
            description: Human-readable name for display in the UI. Can contain spaces
              and special characters, max 63 characters.
            example: My Egress Gateway
          name:
            type: string
            description: Unique identifier for the egress gateway within the VPC.
              Must be lowercase alphanumeric with hyphens, max 49 characters. Immutable
              after creation.
            example: my-egress-gateway
          vpcName:
            type: string
            description: Name of the VPC this egress gateway belongs to
            readOnly: true
          workspace:
            type: string
            description: Name of the workspace this resource belongs to (read-only,
              set automatically)
            readOnly: true
        required:
        - name
    EgressGatewaySpec:
      type: object
      description: Specification for an egress gateway including region and capacity
        configuration
      properties:
        region:
          type: string
          description: Region where the egress gateway is provisioned (e.g. us-pdx-1,
            eu-lon-1)
          example: us-pdx-1
      required:
      - region
    EgressGatewayUsage:
      type: object
      description: Sandboxes currently bound to each egress gateway. Returned by GET
        /egressgateways/usage so the egress-IPs UI can render attachment counts without
        fetching the sandboxes listing full. Keys are gateway names; values are sandbox
        names.
      additionalProperties:
        items:
          type: string
        type: array
    EgressIP:
      type: object
      description: An individual IP address allocated from an egress gateway for dedicated
        outbound traffic
      properties:
        events:
          $ref: '#/components/schemas/CoreEvents'
        metadata:
          $ref: '#/components/schemas/EgressIPMetadata'
        spec:
          $ref: '#/components/schemas/EgressIPSpec'
        status:
          $ref: '#/components/schemas/Status'
      required:
      - metadata
      - spec
    EgressIPMetadata:
      type: object
      description: Metadata for an egress IP address including gateway association
        and name
      allOf:
      - $ref: '#/components/schemas/TimeFields'
      - $ref: '#/components/schemas/OwnerFields'
      - properties:
          displayName:
            type: string
            description: Human-readable name for display in the UI. Can contain spaces
              and special characters, max 63 characters.
            example: My Egress IP
          gatewayName:
            type: string
            description: Name of the egress gateway this IP is allocated from
            readOnly: true
          name:
            type: string
            description: Unique identifier for the egress IP within the gateway. Must
              be lowercase alphanumeric with hyphens, max 49 characters. Immutable
              after creation.
            example: my-egress-ip
          vpcName:
            type: string
            description: Name of the VPC this egress IP belongs to
            readOnly: true
          workspace:
            type: string
            description: Name of the workspace this resource belongs to (read-only,
              set automatically)
            readOnly: true
        required:
        - name
    EgressIPSpec:
      type: object
      description: Specification for an egress IP including IP family and the provisioned
        address
      properties:
        ipFamily:
          type: string
          description: IP address family, either IPv4 or IPv6
          enum:
          - IPv4
          - IPv6
          example: IPv4
          default: IPv4
        publicIp:
          type: string
          description: Public IP address assigned to this egress IP (read-only, set
            after provisioning)
          readOnly: true
      required:
      - ipFamily
    EgressPolicy:
      type: object
      description: Egress policy routing specific destinations through dedicated or
        shared gateways (not yet supported)
      properties:
        destinations:
          type: array
          description: Destination domains or IPs this policy applies to
          items:
            type: string
          example: '["api.stripe.com"]'
        mode:
          type: string
          description: Egress mode for these destinations (dedicated or shared)
          example: dedicated
        name:
          type: string
          description: Name of this egress policy
          example: payment-apis
    Entrypoint:
      type: object
      description: Entrypoint of the artifact
      properties:
        args:
          type: array
          description: Args of the entrypoint
          items:
            type: object
            additionalProperties: true
        command:
          type: string
          description: Command of the entrypoint
        env:
          type: object
          description: Env of the entrypoint
          additionalProperties:
            type: string
        superGatewayArgs:
          type: array
          description: Super Gateway args of the entrypoint
          items:
            type: object
            additionalProperties: true
    Env:
      type: object
      description: Environment variable with name and value
      properties:
        name:
          type: string
          description: Name of the environment variable
          example: MY_ENV_VAR
        secret:
          type: boolean
          description: Whether the value is a secret
          example: true
        value:
          type: string
          description: Value of the environment variable
          example: my-value
    Error:
      type: object
      description: Standard error response returned by the API when a request fails
      properties:
        code:
          type: integer
          description: HTTP status code of the error
          example: 409
        error:
          type: string
          description: Error type or code identifying the kind of error
          example: Resource already exists
        message:
          type: string
          description: Human-readable error message describing what went wrong
          example: Invalid request body
      required:
      - error
    ExpirationPolicy:
      type: object
      description: Expiration policy for automatic sandbox cleanup based on time conditions
      properties:
        action:
          type: string
          description: Action to take when the expiration condition is met
          enum:
          - delete
          example: delete
        type:
          type: string
          description: 'Type of expiration policy: ttl-idle (delete after inactivity),
            ttl-max-age (delete after total lifetime), or date (delete at specific
            time)'
          enum:
          - ttl-idle
          - ttl-max-age
          - date
          example: ttl-idle
        value:
          type: string
          description: Duration value for TTL policies (e.g., '30m', '24h', '7d';
            minimum '60s' for ttl-idle, '5m' for ttl-max-age) or ISO 8601 date for
            date policies
          example: 24h
    FirewallConfig:
      type: object
      description: Firewall configuration specifying which network lockdown rulesets
        to apply. Valid rulesets are "default" (no-op), "proxy" (restrict egress to
        proxy), and "dedicated-ip" (restrict egress to dedicated IP gateway).
      properties:
        rulesets:
          type: array
          description: 'List of firewall rulesets to apply. Valid values: "default"
            (no-op), "proxy" (restrict egress to proxy), "dedicated-ip" (restrict
            egress to dedicated IP gateway).'
          items:
            type: string
          example: '["proxy", "dedicated-ip"]'
    Flavor:
      type: object
      description: A type of hardware available for deployments
      properties:
        name:
          type: string
          description: Flavor name (e.g. t4)
          example: t4
        type:
          type: string
          description: Flavor type (e.g. cpu, gpu)
          enum:
          - cpu
          - gpu
          example: cpu
    Flavors:
      type: array
      description: Types of hardware available for deployments
      items:
        $ref: '#/components/schemas/Flavor'
    Form:
      type: object
      description: Form of the artifact
      properties:
        config:
          type: object
          description: Config of the artifact
          additionalProperties: true
        oauth:
          $ref: '#/components/schemas/OAuth'
        secrets:
          type: object
          description: Secrets of the artifact
          additionalProperties: true
    Function:
      type: object
      description: MCP server deployment that exposes tools for AI agents via the
        Model Context Protocol (MCP). Deployed as a serverless auto-scaling endpoint
        using streamable HTTP transport.
      properties:
        events:
          $ref: '#/components/schemas/CoreEvents'
        metadata:
          $ref: '#/components/schemas/Metadata'
        spec:
          $ref: '#/components/schemas/FunctionSpec'
        status:
          $ref: '#/components/schemas/Status'
      required:
      - metadata
      - spec
    FunctionList:
      type: object
      description: Cursor-paginated list of MCP server functions. Returned starting
        with API version 2026-04-28; older API versions return a bare array.
      properties:
        data:
          type: array
          description: Page of functions.
          items:
            $ref: '#/components/schemas/Function'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    FunctionRuntime:
      type: object
      description: Runtime configuration defining how the MCP server function is deployed
        and scaled
      properties:
        envs:
          type: array
          description: Environment variables injected into the function. Supports
            Kubernetes EnvVar format with valueFrom references.
          items:
            $ref: '#/components/schemas/Env'
        generation:
          type: string
          description: 'Infrastructure generation: mk2 (containers, 2-10s cold starts,
            15+ global regions) or mk3 (microVMs, sub-25ms cold starts)'
          enum:
          - mk2
          - mk3
          example: mk3
        image:
          type: string
          description: Container image built by Blaxel when deploying with 'bl deploy'.
            This field is auto-populated during deployment.
        maxScale:
          type: integer
          description: Maximum number of concurrent function instances for auto-scaling
          example: 10
        memory:
          type: integer
          description: Memory allocation in megabytes. Also determines CPU allocation
            (CPU cores = memory in MB / 2048, e.g., 4096MB = 2 CPUs).
          example: 2048
        minScale:
          type: integer
          description: Minimum instances to keep warm. Set to 1+ to eliminate cold
            starts, 0 for scale-to-zero.
          example: 0
        ports:
          $ref: '#/components/schemas/Ports'
        transport:
          type: string
          description: Transport compatibility for the MCP, can be "websocket" or
            "http-stream"
          enum:
          - websocket
          - http-stream
          example: http-stream
    FunctionSpec:
      type: object
      description: Configuration for an MCP server function including runtime settings,
        transport protocol, and connected integrations
      properties:
        enabled:
          type: boolean
          description: When false, the function is disabled and will not serve requests
          example: true
          default: true
        integrationConnections:
          $ref: '#/components/schemas/IntegrationConnectionsList'
        policies:
          $ref: '#/components/schemas/PoliciesList'
        public:
          type: boolean
          description: When true, the function is publicly accessible without authentication.
            Only available for mk3 generation.
          example: false
          default: false
        region:
          type: string
          description: Region where the function should be deployed (e.g. us-pdx-1,
            eu-lon-1). If not specified, the function is deployed based on policy
            locations.
          example: us-pdx-1
        revision:
          $ref: '#/components/schemas/RevisionConfiguration'
        runtime:
          $ref: '#/components/schemas/FunctionRuntime'
        triggers:
          $ref: '#/components/schemas/Triggers'
    GithubRunnerConfig:
      type: object
      description: Configuration for running GitHub Actions workflow jobs on Blaxel
        infrastructure. When repositories are configured, the job acts as a self-hosted
        GitHub Actions runner. Workflow jobs use runs-on with the Blaxel job name
        to target a specific runner.
      properties:
        repositories:
          type: array
          description: Repositories in owner/repo format that this runner is associated
            with. The runner will pick up workflow jobs from any of these repositories.
            If non-empty, the runner is considered enabled.
          items:
            type: string
          example: '["my-org/repo-a", "my-org/repo-b"]'
    GroupWorkspaceMapping:
      type: object
      description: Mapping between an IdP group and a workspace role for directory
        sync
      properties:
        groupName:
          type: string
          description: Name of the IdP group (e.g. "Engineering", "Platform")
          example: Engineering
        role:
          type: string
          description: Role to assign in this workspace (admin, member or viewer)
          enum:
          - admin
          - member
          - viewer
          example: admin
    Image:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/ImageMetadata'
        spec:
          $ref: '#/components/schemas/ImageSpec'
      required:
      - metadata
      - spec
    ImageMetadata:
      type: object
      properties:
        createdAt:
          type: string
          description: The date and time when the image was created.
          readOnly: true
        displayName:
          type: string
          description: The display name of the image (registry/workspace/repository).
        events:
          $ref: '#/components/schemas/CoreEvents'
        lastDeployedAt:
          type: string
          description: The date and time when the image was last deployed (most recent
            across all tags).
          readOnly: true
        name:
          type: string
          description: The name of the image (repository name).
        resourceType:
          type: string
          description: The resource type of the image.
        sourceWorkspace:
          type: string
          description: If this image is shared from another workspace, this field
            contains the name of the source workspace. Empty for non-shared images.
          readOnly: true
        status:
          $ref: '#/components/schemas/Status'
        updatedAt:
          type: string
          description: The date and time when the image was last updated.
          readOnly: true
        workspace:
          type: string
          description: The workspace of the image.
          readOnly: true
    ImageShareTarget:
      type: object
      properties:
        accountId:
          type: string
          description: ID of the account that owns the target workspace.
        accountOwnerEmail:
          type: string
          description: Email of the account owner for the target workspace (when available).
        pendingShareId:
          type: string
          description: ID of the pending share record when status is "pending".
        status:
          type: string
          description: '"active" when the share is applied in the target workspace,
            "pending" when it is awaiting accept on a cross-account share.'
        workspace:
          type: string
          description: The workspace the image is shared with.
        workspaceDisplayName:
          type: string
          description: Display name of the target workspace.
      required:
      - workspace
      - accountId
      - status
    ImageSpec:
      type: object
      properties:
        size:
          type: integer
          description: The size of the image in bytes.
          readOnly: true
        tags:
          type: array
          description: List of tags available for this image.
          items:
            $ref: '#/components/schemas/ImageTag'
    ImageSummary:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/ImageMetadata'
        spec:
          $ref: '#/components/schemas/ImageSummarySpec'
      required:
      - metadata
      - spec
    ImageSummarySpec:
      type: object
      properties:
        size:
          type: integer
          readOnly: true
        tagCount:
          type: integer
          readOnly: true
    ImageTag:
      type: object
      properties:
        createdAt:
          type: string
          description: The date and time when the tag was created.
          readOnly: true
        name:
          type: string
          description: The name of the tag.
        size:
          type: integer
          description: The size of the image in bytes.
          readOnly: true
        updatedAt:
          type: string
          description: The date and time when the tag was last updated.
          readOnly: true
    Integration:
      type: object
      description: Integration
      properties:
        additionalInfos:
          type: object
          description: Integration additional infos
          additionalProperties:
            type: string
        endpoints:
          $ref: '#/components/schemas/IntegrationEndpoints'
        headers:
          $ref: '#/components/schemas/IntegrationHeaders'
        name:
          type: string
          description: Integration name
        organizations:
          type: array
          description: Integration organizations
          items:
            $ref: '#/components/schemas/IntegrationOrganization'
        params:
          $ref: '#/components/schemas/IntegrationQueryParams'
        repositories:
          type: array
          description: Integration repositories
          items:
            $ref: '#/components/schemas/IntegrationRepository'
    IntegrationConnection:
      type: object
      description: Configured connection to an external service (LLM provider, API,
        SaaS, database) storing credentials and settings for use by workspace resources.
      properties:
        metadata:
          $ref: '#/components/schemas/Metadata'
        spec:
          $ref: '#/components/schemas/IntegrationConnectionSpec'
      required:
      - metadata
      - spec
    IntegrationConnectionSpec:
      type: object
      description: Specification defining the integration type, configuration parameters,
        and encrypted credentials
      properties:
        config:
          type: object
          description: Non-sensitive configuration parameters for the integration
            (e.g., organization ID, region)
          additionalProperties:
            type: string
        integration:
          type: string
          description: Integration provider type (e.g., openai, anthropic, github,
            slack)
          example: openai
        sandbox:
          type: boolean
          description: Whether this connection uses sandbox/test credentials instead
            of production
          example: false
        secret:
          type: object
          description: Encrypted credentials and API keys for authenticating with
            the external service
          additionalProperties:
            type: string
    IntegrationConnectionsList:
      type: array
      items:
        type: string
        description: Deployment integration connection name
    IntegrationEndpoint:
      type: object
      description: Integration endpoint
      properties:
        body:
          type: string
          description: Integration endpoint body
        ignoreModels:
          type: array
          description: Integration endpoint ignore models
          items:
            type: object
            additionalProperties: true
        method:
          type: string
          description: Integration endpoint method
        models:
          type: array
          description: Integration endpoint models
          items:
            type: object
            additionalProperties: true
        streamKey:
          type: string
          description: Integration endpoint stream key
        streamToken:
          $ref: '#/components/schemas/IntegrationEndpointToken'
        token:
          $ref: '#/components/schemas/IntegrationEndpointToken'
    IntegrationEndpointToken:
      type: object
      description: Integration endpoint token
      properties:
        received:
          type: string
          description: Integration endpoint token received
        sent:
          type: string
          description: Integration endpoint token sent
        total:
          type: string
          description: Integration endpoint token total
    IntegrationEndpoints:
      type: object
      description: Integration endpoints
      additionalProperties:
        $ref: '#/components/schemas/IntegrationEndpoint'
    IntegrationHeaders:
      type: object
      description: Integration headers
      additionalProperties:
        type: string
    IntegrationOrganization:
      type: object
      description: Integration organization
      properties:
        avatar_url:
          type: string
          description: Provider organization avatar URL
        displayName:
          type: string
          description: Provider organization display name
        id:
          type: string
          description: Provider organization ID
        name:
          type: string
          description: Provider organization name
    IntegrationQueryParams:
      type: object
      description: Integration query params
      additionalProperties:
        type: string
    IntegrationRepository:
      type: object
      description: Integration repository
      properties:
        id:
          type: string
          description: Repository ID
        isBl:
          type: boolean
          description: Whether the repository has Blaxel imports
        name:
          type: string
          description: Repository name
        organization:
          type: string
          description: Repository owner
        url:
          type: string
          description: Repository URL
    Job:
      type: object
      description: Batch processing job definition for running parallel AI tasks.
        Jobs can execute multiple tasks concurrently with configurable parallelism,
        retries, and timeouts.
      properties:
        events:
          $ref: '#/components/schemas/CoreEvents'
        metadata:
          $ref: '#/components/schemas/Metadata'
        spec:
          $ref: '#/components/schemas/JobSpec'
        status:
          $ref: '#/components/schemas/Status'
      required:
      - metadata
      - spec
    JobExecution:
      type: object
      description: Job execution
      properties:
        metadata:
          $ref: '#/components/schemas/JobExecutionMetadata'
        spec:
          $ref: '#/components/schemas/JobExecutionSpec'
        stats:
          $ref: '#/components/schemas/JobExecutionStats'
        status:
          $ref: '#/components/schemas/JobExecutionStatus'
        tasks:
          type: array
          description: List of execution tasks
          items:
            $ref: '#/components/schemas/JobExecutionTask'
      required:
      - metadata
      - spec
    JobExecutionList:
      type: object
      description: Cursor-paginated list of job executions. Returned starting with
        API version 2026-04-28; older API versions keep the legacy offset-based contract
        and return a bare array.
      properties:
        data:
          type: array
          description: Page of job executions.
          items:
            $ref: '#/components/schemas/JobExecution'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    JobExecutionMetadata:
      type: object
      description: Job execution metadata
      properties:
        cluster:
          type: string
          description: Cluster ID
        completedAt:
          type: string
          description: Completion timestamp
        createdAt:
          type: string
          description: Creation timestamp
        deletedAt:
          type: string
          description: Deletion timestamp
        expiredAt:
          type: string
          description: Expiration timestamp
        id:
          type: string
          description: Execution ID
          example: exec-abc123
        job:
          type: string
          description: Job name
          example: data-processing-job
        startedAt:
          type: string
          description: Start timestamp
        updatedAt:
          type: string
          description: Last update timestamp
        workspace:
          type: string
          description: Workspace ID
          example: my-workspace
      readOnly: true
    JobExecutionSpec:
      type: object
      description: Job execution specification
      properties:
        envOverride:
          type: object
          description: Environment variable overrides (if provided for this execution,
            values are masked with ***)
          example: '{"MY_VAR": "***", "BATCH_SIZE": "***"}'
        memoryOverride:
          type: integer
          description: Memory override in megabytes (if provided for this execution)
          example: 2048
        parallelism:
          type: integer
          description: Number of parallel tasks
          example: 5
        taskCount:
          type: integer
          description: Number of tasks of this execution
          example: 12
        tasks:
          type: array
          description: List of execution tasks
          items:
            $ref: '#/components/schemas/JobExecutionTask'
        tasksRef:
          type: string
          description: Where this execution's task list is stored (server-managed)
          readOnly: true
        timeout:
          type: integer
          description: Job timeout in seconds (captured at execution creation time)
          example: 3600
    JobExecutionStats:
      type: object
      description: Job execution statistics
      properties:
        cancelled:
          type: integer
          description: Number of cancelled tasks
          example: 0
        failure:
          type: integer
          description: Number of failed tasks
          example: 1
        retried:
          type: integer
          description: Number of retried tasks
          example: 2
        running:
          type: integer
          description: Number of running tasks
          example: 1
        success:
          type: integer
          description: Number of successful tasks
          example: 8
        total:
          type: integer
          description: Total number of tasks
          example: 10
      readOnly: true
    JobExecutionStatus:
      type: string
      description: Job execution status
      enum:
      - queued
      - pending
      - running
      - cancelling
      - cancelled
      - failed
      - succeeded
      - timeout
    JobExecutionTask:
      type: object
      description: Job execution task
      properties:
        conditions:
          type: array
          description: Task conditions
          items:
            $ref: '#/components/schemas/JobExecutionTaskCondition'
        metadata:
          $ref: '#/components/schemas/JobExecutionTaskMetadata'
        spec:
          $ref: '#/components/schemas/JobExecutionTaskSpec'
        status:
          $ref: '#/components/schemas/JobExecutionTaskStatus'
    JobExecutionTaskCondition:
      type: object
      description: Job execution task condition
      properties:
        executionReason:
          type: string
          description: Execution reason
        message:
          type: string
          description: Condition message
        reason:
          type: string
          description: Condition reason
        severity:
          type: string
          description: Condition severity
        state:
          type: string
          description: Condition state
        type:
          type: string
          description: Condition type
    JobExecutionTaskList:
      type: object
      description: Cursor-paginated list of an execution's tasks. Tasks are derived
        from event history; pagination slices the in-memory list and the cursor is
        a base64-JSON offset bound to (workspace, job, execution).
      properties:
        data:
          type: array
          description: Page of execution tasks.
          items:
            $ref: '#/components/schemas/JobExecutionTask'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    JobExecutionTaskMetadata:
      type: object
      description: Job execution task metadata
      properties:
        completedAt:
          type: string
          description: Completion timestamp
          readOnly: true
        createdAt:
          type: string
          description: Creation timestamp
          readOnly: true
        name:
          type: string
          description: Task name
          example: task-0
        scheduledAt:
          type: string
          description: Scheduled timestamp
          readOnly: true
        startedAt:
          type: string
          description: Start timestamp
          readOnly: true
        updatedAt:
          type: string
          description: Last update timestamp
          readOnly: true
    JobExecutionTaskSpec:
      type: object
      description: Job execution task specification
      properties:
        maxRetries:
          type: integer
          description: Maximum number of retries
          example: 3
        timeout:
          type: string
          description: Task timeout duration
          example: 30m
    JobExecutionTaskStatus:
      type: string
      description: Job execution task status
      enum:
      - unspecified
      - pending
      - reconciling
      - failed
      - succeeded
      - running
      - cancelled
    JobList:
      type: object
      description: Cursor-paginated list of batch jobs. Returned starting with API
        version 2026-04-28; older API versions return a bare array.
      properties:
        data:
          type: array
          description: Page of jobs.
          items:
            $ref: '#/components/schemas/Job'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    JobRuntime:
      type: object
      description: Runtime configuration defining how batch job tasks are executed
        with parallelism and retry settings
      properties:
        diskPercent:
          type: integer
          description: Percentage of VM RAM allocated for disk storage (tmpfs overlay).
            Valid range 10-95, default 50. Only applies to mk3.1 (microVM) generation.
          example: 80
        envs:
          type: array
          description: Environment variables injected into job tasks. Supports Kubernetes
            EnvVar format with valueFrom references.
          items:
            $ref: '#/components/schemas/Env'
        generation:
          type: string
          description: Infrastructure generation. Jobs always run on mk3 (microVMs);
            any value sent on input is ignored.
          enum:
          - mk2
          - mk3
          example: mk3
        image:
          type: string
          description: Container image built by Blaxel when deploying with 'bl deploy'.
            This field is auto-populated during deployment.
        maxRetries:
          type: integer
          description: Number of automatic retry attempts for failed tasks before
            marking as failed
          example: 3
        memory:
          type: integer
          description: Memory allocation in megabytes. Also determines CPU allocation
            (CPU cores = memory in MB / 2048, e.g., 4096MB = 2 CPUs).
          example: 2048
        ports:
          $ref: '#/components/schemas/Ports'
        timeout:
          type: integer
          description: Maximum execution time in seconds before a task is terminated
          example: 3600
    JobSpec:
      type: object
      description: Configuration for a batch job including execution parameters, parallelism
        settings, and deployment region
      properties:
        enabled:
          type: boolean
          description: When false, the job is disabled and new executions cannot be
            triggered
          example: true
          default: true
        githubRunner:
          $ref: '#/components/schemas/GithubRunnerConfig'
        policies:
          $ref: '#/components/schemas/PoliciesList'
        region:
          type: string
          description: Region where the job should be created (e.g. us-was-1, eu-lon-1)
          example: us-was-1
        revision:
          $ref: '#/components/schemas/RevisionConfiguration'
        runtime:
          $ref: '#/components/schemas/JobRuntime'
        triggers:
          $ref: '#/components/schemas/Triggers'
        volumes:
          $ref: '#/components/schemas/JobVolumes'
    JobVolume:
      type: object
      description: Ephemeral volume for a job. Temporary disk-backed storage that
        is created when the job starts and destroyed when it completes.
      properties:
        mountPath:
          type: string
          description: Absolute filesystem path where the volume will be mounted inside
            the container
          example: /mnt/data
        name:
          type: string
          description: Identifier for the volume, used to reference it internally
          example: scratch
        readOnly:
          type: boolean
          description: If true, the volume is mounted read-only
          example: false
        sizeMb:
          type: integer
          description: Storage capacity in megabytes
          example: 102400
        type:
          type: string
          description: Type of volume. Currently only "ephemeral" is supported.
          enum:
          - ephemeral
          example: ephemeral
      required:
      - name
      - mountPath
      - type
      - sizeMb
    JobVolumes:
      type: array
      items:
        $ref: '#/components/schemas/JobVolume'
    LiteVolume:
      type: object
      description: LiteVolume is the listing-shape projection of a Volume. Drops events
        to keep page payloads small.
      properties:
        metadata:
          $ref: '#/components/schemas/LiteVolumeMetadata'
        spec:
          $ref: '#/components/schemas/LiteVolumeSpec'
        state:
          $ref: '#/components/schemas/VolumeState'
        status:
          type: string
          description: Computed status of the volume.
        terminatedAt:
          type: string
          description: Termination timestamp for soft-deleted volumes.
    LiteVolumeMetadata:
      type: object
      description: Compact metadata for a Volume, returned in listing responses.
      properties:
        createdAt:
          type: string
        displayName:
          type: string
        externalId:
          type: string
          description: Caller-owned identifier for external lookups.
        name:
          type: string
        updatedAt:
          type: string
    LiteVolumeSpec:
      type: object
      description: Compact spec for a Volume, returned in listing responses.
      properties:
        region:
          type: string
          description: Region the volume is provisioned in.
        size:
          type: integer
          description: Volume size in gigabytes.
    LocationResponse:
      type: object
      description: Location availability for policies
      properties:
        continent:
          type: string
          description: Continent of the location
          example: NA
        country:
          type: string
          description: Country of the location
          example: US
        flavors:
          type: array
          description: Hardware flavors available in the location
          items:
            $ref: '#/components/schemas/Flavor'
        location:
          type: string
          description: Name of the location
          example: Portland
        region:
          type: string
          description: Region of the location
          example: us-pdx-1
        status:
          type: string
          description: Status of the location
          example: healthy
      x-stainless-ignore: true
    MCPDefinition:
      type: object
      description: Definition of an MCP from the MCP Hub
      allOf:
      - $ref: '#/components/schemas/TimeFields'
      - properties:
          categories:
            type: array
            description: Categories of the artifact
            items:
              type: object
              additionalProperties: true
          coming_soon:
            type: boolean
            description: If the artifact is coming soon
          description:
            type: string
            description: Description of the artifact
          displayName:
            type: string
            description: Display name of the artifact
          enterprise:
            type: boolean
            description: If the artifact is enterprise
          entrypoint:
            $ref: '#/components/schemas/Entrypoint'
          form:
            $ref: '#/components/schemas/Form'
          hidden:
            type: boolean
            description: If the artifact is hidden
          hiddenSecrets:
            type: array
            description: Hidden secrets of the artifact
            items:
              type: string
          icon:
            type: string
            description: Icon of the artifact
          image:
            type: string
            description: Image of the artifact
          integration:
            type: string
            description: Integration of the artifact
          longDescription:
            type: string
            description: Long description of the artifact
          name:
            type: string
            description: Name of the artifact
          transport:
            type: string
            description: Transport compatibility for the MCP, can be "websocket" or
              "http-stream"
          url:
            type: string
            description: URL of the artifact
    Metadata:
      type: object
      description: Common metadata fields shared by all Blaxel resources including
        name, labels, timestamps, and ownership information
      allOf:
      - $ref: '#/components/schemas/TimeFields'
      - $ref: '#/components/schemas/OwnerFields'
      - properties:
          displayName:
            type: string
            description: Human-readable name for display in the UI. Can contain spaces
              and special characters, max 63 characters.
            example: My Resource
          externalId:
            type: string
            description: Caller-owned identifier for external lookups. Max 64 chars,
              alphanumeric + dash.
            example: my-session-123
          labels:
            $ref: '#/components/schemas/MetadataLabels'
          name:
            type: string
            description: Unique identifier for the resource within the workspace.
              Must be lowercase alphanumeric with hyphens, max 49 characters. Immutable
              after creation.
            example: my-resource
          plan:
            type: string
            description: Billing plan tier applied to this resource (inherited from
              workspace account)
            readOnly: true
          url:
            type: string
            description: Auto-generated endpoint URL for accessing this resource (for
              agents, functions, models, sandboxes)
            readOnly: true
          workspace:
            type: string
            description: Name of the workspace this resource belongs to (read-only,
              set automatically)
            readOnly: true
        required:
        - name
    MetadataLabels:
      type: object
      description: Key-value pairs for organizing and filtering resources. Labels
        can be used to categorize resources by environment, project, team, or any
        custom taxonomy.
      additionalProperties:
        type: string
    Model:
      type: object
      description: Gateway endpoint to external LLM provider APIs (OpenAI, Anthropic,
        etc.) with unified access control, credentials management, and usage tracking.
      properties:
        events:
          $ref: '#/components/schemas/CoreEvents'
        metadata:
          $ref: '#/components/schemas/Metadata'
        spec:
          $ref: '#/components/schemas/ModelSpec'
        status:
          $ref: '#/components/schemas/Status'
      required:
      - metadata
      - spec
    ModelList:
      type: object
      description: Cursor-paginated list of model gateway endpoints. Returned starting
        with API version 2026-04-28; older API versions return a bare array.
      properties:
        data:
          type: array
          description: Page of models.
          items:
            $ref: '#/components/schemas/Model'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ModelRuntime:
      type: object
      description: Configuration identifying which external LLM provider and model
        this gateway endpoint proxies to
      properties:
        endpointName:
          type: string
          description: Provider-specific endpoint name (e.g., HuggingFace Inference
            Endpoints name)
        generation:
          type: string
          description: Infrastructure generation. Empty (default) uses the classic
            deployment path. mk3 deploys through the model-gateway on microVM clusters.
          enum:
          - mk3
          - mk2
        model:
          type: string
          description: Model identifier at the provider (e.g., gpt-4.1, claude-sonnet-4-20250514,
            mistral-large-latest)
          example: gpt-4.1
        organization:
          type: string
          description: Organization or account identifier at the provider (required
            for some providers like OpenAI)
          example: org-abc123
        type:
          type: string
          description: LLM provider type determining the API protocol and authentication
            method
          enum:
          - hf_private_endpoint
          - hf_public_endpoint
          - huggingface
          - public_model
          - mcp
          - openai
          - anthropic
          - gemini
          - mistral
          - deepseek
          - cohere
          - cerebras
          - xai
          - vertexai
          - azure-openai-service
          - azure-ai-inference
          - azure-marketplace
          - groq
          example: openai
    ModelSpec:
      type: object
      description: Configuration for a model gateway endpoint including provider type,
        credentials, and access policies
      properties:
        enabled:
          type: boolean
          description: When false, the model endpoint is disabled and will not accept
            inference requests
          example: true
          default: true
        flavors:
          $ref: '#/components/schemas/Flavors'
        integrationConnections:
          $ref: '#/components/schemas/IntegrationConnectionsList'
        policies:
          $ref: '#/components/schemas/PoliciesList'
        runtime:
          $ref: '#/components/schemas/ModelRuntime'
        sandbox:
          type: boolean
          description: When true, uses sandbox/test credentials from the integration
            connection
          example: false
    NetworkFirewall:
      description: Firewall configuration restricting which external domains the sandbox
        can access
      properties:
        allowedDomains:
          description: List of allowed external domains. Supports wildcards (e.g.
            *.s3.amazonaws.com).
          example: '["api.stripe.com", "api.openai.com", "*.s3.amazonaws.com"]'
          items:
            type: string
          type: array
      type: object
    OAuth:
      type: object
      description: OAuth of the artifact
      properties:
        scope:
          type: array
          description: Scope of the OAuth
          items:
            type: object
            additionalProperties: true
        type:
          type: string
          description: Type of the OAuth
    OwnerFields:
      type: object
      description: Owner fields for Persistence
      properties:
        createdBy:
          type: string
          description: The user or service account who created the resource
          readOnly: true
        updatedBy:
          type: string
          description: The user or service account who updated the resource
          readOnly: true
    PaginationMeta:
      type: object
      description: Pagination metadata returned alongside a page of listing results.
        Always present on listing endpoints starting with API version 2026-04-28.
      properties:
        hasMore:
          type: boolean
          description: True when more pages are available beyond the current one.
        nextCursor:
          type: string
          description: Opaque cursor to pass back as the `cursor` query param for
            the next page. Empty when there are no more pages.
        total:
          type: integer
          description: Total number of items in the workspace, ignoring the current
            page's filters. Lets the UI render "page X of Y" without walking the cursor
            chain. Computed from the hash-only metadata.workspace GSI count, so search
            (`q`) does not narrow it.
        totalIsPartial:
          type: boolean
          description: True when `total` is a lower bound rather than a complete count.
            Counting a very large workspace is bounded so the listing stays fast,
            and this flag says the real number is higher. Clients must not derive
            a page count from `total` when this is set — keep paging with `nextCursor`
            until `hasMore` is false.
    PendingImageShare:
      type: object
      description: Pending cross-account image share awaiting approval from the destination
        workspace
      allOf:
      - $ref: '#/components/schemas/TimeFields'
      - $ref: '#/components/schemas/OwnerFields'
      - properties:
          expiresAt:
            type: string
            description: The date and time when the pending share expires
          id:
            type: string
            description: Unique identifier for the pending image share
          imageName:
            type: string
            description: Image name (repository)
          resourceType:
            type: string
            description: Resource type (agent, function, sandbox, job)
          sharedBy:
            type: string
            description: User sub who initiated the share
          sourceAccountId:
            type: string
            description: Source account ID
          sourceWorkspace:
            type: string
            description: Source workspace name
          targetAccountId:
            type: string
            description: Target account ID
          targetWorkspace:
            type: string
            description: Target workspace name
    PendingImageShareRender:
      type: object
      description: Rendered pending image share with source/target workspace metadata
      properties:
        createdAt:
          type: string
          description: Creation date
        expiresAt:
          type: string
          description: Expiration date
        hasConflict:
          type: boolean
          description: Whether the target workspace already has an image with the
            same name (potential conflict)
        id:
          type: string
          description: Unique identifier for the pending image share
        imageName:
          type: string
          description: Image name (repository)
        resourceType:
          type: string
          description: Resource type (agent, function, sandbox, job)
        sharedBy:
          type: string
          description: User sub who initiated the share
        sharedByEmail:
          type: string
          description: Email of the user who initiated the share
        sourceAccountId:
          type: string
          description: Source account ID
        sourceWorkspace:
          type: string
          description: Source workspace name
        sourceWorkspaceDisplayName:
          type: string
          description: Source workspace display name
        targetAccountId:
          type: string
          description: Target account ID
        targetWorkspace:
          type: string
          description: Target workspace name
        targetWorkspaceDisplayName:
          type: string
          description: Target workspace display name
    PendingInvitation:
      type: object
      description: Pending invitation in workspace
      allOf:
      - $ref: '#/components/schemas/TimeFields'
      - $ref: '#/components/schemas/OwnerFields'
      - properties:
          email:
            type: string
            description: User email
          expiresAt:
            type: string
            description: The date and time when the invitation expires
          invitedBy:
            type: string
            description: User sub
          role:
            type: string
            description: ACL role
          workspace:
            type: string
            description: Workspace name
    PendingInvitationAccept:
      type: object
      description: Pending invitation accept
      properties:
        email:
          type: string
          description: User email
        workspace:
          $ref: '#/components/schemas/Workspace'
    PendingInvitationRender:
      type: object
      description: Pending invitation in workspace
      properties:
        account:
          $ref: '#/components/schemas/PendingInvitationRenderAccount'
        email:
          type: string
          description: User email
        expiresAt:
          type: string
          description: The date and time when the invitation expires
        invitationId:
          type: string
          description: Opaque invitation identifier
        invitedAt:
          type: string
          description: Invitation date
        invitedBy:
          $ref: '#/components/schemas/PendingInvitationRenderInvitedBy'
        role:
          type: string
          description: ACL role
        type:
          type: string
          description: 'Invitation type: "workspace" or "account_admin"'
        workspace:
          $ref: '#/components/schemas/PendingInvitationRenderWorkspace'
        workspaceDetails:
          $ref: '#/components/schemas/PendingInvitationWorkspaceDetails'
    PendingInvitationRenderAccount:
      type: object
      description: Account info in pending invitation render (for account_admin type)
      properties:
        displayName:
          type: string
          description: Account display name or owner email
        id:
          type: string
          description: Account ID
    PendingInvitationRenderInvitedBy:
      type: object
      description: Invited by
      properties:
        email:
          type: string
          description: User email
        family_name:
          type: string
          description: User family name
        given_name:
          type: string
          description: User given name
        sub:
          type: string
          description: User sub
    PendingInvitationRenderWorkspace:
      type: object
      description: Workspace
      properties:
        displayName:
          type: string
          description: Workspace display name
        name:
          type: string
          description: Workspace name
    PendingInvitationWorkspaceDetails:
      type: object
      description: Workspace details
      properties:
        emails:
          type: array
          description: List of user emails in the workspace
          items:
            type: object
            additionalProperties: true
        user_number:
          type: number
          description: Number of users in the workspace
    PoliciesList:
      type: array
      items:
        type: string
        description: Policy name
    Policy:
      type: object
      description: Rule that controls how a deployment is made and served (e.g. location
        restrictions)
      properties:
        metadata:
          $ref: '#/components/schemas/Metadata'
        spec:
          $ref: '#/components/schemas/PolicySpec'
        usage:
          $ref: '#/components/schemas/PolicyUsageCounts'
      required:
      - metadata
      - spec
    PolicyList:
      type: object
      description: Cursor-paginated list of policies. Returned starting with API version
        2026-04-28; older API versions return a bare array.
      properties:
        data:
          type: array
          description: Page of policies.
          items:
            $ref: '#/components/schemas/Policy'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PolicyLocation:
      type: object
      description: Policy location
      properties:
        name:
          type: string
          description: Policy location name
          example: EU
        type:
          type: string
          description: Policy location type
          enum:
          - location
          - country
          - continent
          example: continent
    PolicyLocations:
      type: array
      description: PolicyLocations is a local type that wraps a slice of Location
      items:
        $ref: '#/components/schemas/PolicyLocation'
    PolicyMaxTokens:
      type: object
      description: PolicyMaxTokens is a local type that wraps a slice of PolicyMaxTokens
      properties:
        granularity:
          type: string
          description: Granularity
          example: minute
        input:
          type: integer
          description: Input
          example: 10000
        output:
          type: integer
          description: Output
          example: 5000
        ratioInputOverOutput:
          type: integer
          description: RatioInputOverOutput
          example: 2
        step:
          type: integer
          description: Step
          example: 1
        total:
          type: integer
          description: Total
          example: 15000
    PolicyResourceType:
      type: string
      description: PolicyResourceType is a type of resource, e.g. model, function,
        etc.
      enum:
      - model
      - function
      - agent
      - sandbox
      - application
    PolicyResourceTypes:
      type: array
      description: PolicyResourceTypes is a local type that wraps a slice of PolicyResourceType
      items:
        $ref: '#/components/schemas/PolicyResourceType'
    PolicySpec:
      type: object
      description: Policy specification
      properties:
        flavors:
          $ref: '#/components/schemas/Flavors'
        locations:
          $ref: '#/components/schemas/PolicyLocations'
        maxTokens:
          $ref: '#/components/schemas/PolicyMaxTokens'
        resourceTypes:
          $ref: '#/components/schemas/PolicyResourceTypes'
        sandbox:
          type: boolean
          description: Sandbox mode
          example: false
        type:
          type: string
          description: Policy type, can be location or flavor
          enum:
          - location
          - flavor
          - maxToken
          example: location
    PolicyUsageCounts:
      type: object
      description: Per-resource counts of how many resources reference a policy. Computed
        by the policies listing endpoint to avoid client-side fan-out across the agents/models/functions/sandboxes/jobs
        listings.
      properties:
        agents:
          type: integer
        functions:
          type: integer
        jobs:
          type: integer
        models:
          type: integer
        sandboxes:
          type: integer
    PolicyUsages:
      type: object
      description: Resources currently referencing a policy. Returned by GET /policies/{name}/usages
        so the policies UI can render attachments without fetching the agents/models/functions
        listings full.
      properties:
        agents:
          type: array
          description: Names of agents whose spec.policies contains this policy.
          items:
            type: object
            additionalProperties: true
        functions:
          type: array
          description: Names of functions whose spec.policies contains this policy.
          items:
            type: object
            additionalProperties: true
        jobs:
          type: array
          description: Names of jobs whose spec.policies contains this policy.
          items:
            type: object
            additionalProperties: true
        models:
          type: array
          description: Names of models whose spec.policies contains this policy.
          items:
            type: object
            additionalProperties: true
        sandboxes:
          type: array
          description: Names of sandboxes whose spec.policies contains this policy.
          items:
            type: object
            additionalProperties: true
    Port:
      type: object
      description: A port for a resource
      properties:
        name:
          type: string
          description: The name of the port
          example: http
        protocol:
          type: string
          description: The protocol of the port
          enum:
          - HTTP
          - TCP
          - UDP
          - TLS
          example: HTTP
        target:
          type: integer
          description: The target port of the port
          example: 8080
      required:
      - target
    Ports:
      type: array
      description: Set of ports for a resource
      items:
        $ref: '#/components/schemas/Port'
    Preview:
      type: object
      description: Preview of a Resource
      properties:
        events:
          $ref: '#/components/schemas/CoreEvents'
        metadata:
          $ref: '#/components/schemas/PreviewMetadata'
        spec:
          $ref: '#/components/schemas/PreviewSpec'
        status:
          $ref: '#/components/schemas/Status'
      required:
      - metadata
      - spec
    PreviewMetadata:
      type: object
      description: PreviewMetadata
      allOf:
      - $ref: '#/components/schemas/TimeFields'
      - $ref: '#/components/schemas/OwnerFields'
      - properties:
          displayName:
            type: string
            description: Model display name
          name:
            type: string
            description: Preview name
          resourceName:
            type: string
            description: Resource name
          resourceType:
            type: string
            description: Resource type
          workspace:
            type: string
            description: Workspace name
        required:
        - name
    PreviewSpec:
      type: object
      description: Preview of a Resource
      properties:
        customDomain:
          type: string
          description: Custom domain bound to this preview
        expires:
          type: string
          description: The expiration date for the preview in ISO 8601 format - 2024-12-31T23:59:59Z
        port:
          type: integer
          description: Port of the preview
        prefixUrl:
          type: string
          description: Prefix URL
        public:
          type: boolean
          description: Whether the preview is public
        region:
          type: string
          description: Region where the preview is deployed, this is readonly
          readOnly: true
        requestHeaders:
          type: object
          description: Those headers will be set in all requests to your preview.
            This is especially useful to set the Authorization header.
          additionalProperties:
            type: string
        responseHeaders:
          type: object
          description: Those headers will be set in all responses of your preview.
            This is especially useful to set the CORS headers.
          additionalProperties:
            type: string
        ttl:
          type: string
          description: Time to live for the preview (e.g., "1h", "24h", "7d"). After
            this duration, the preview will be automatically deleted.
        url:
          type: string
          description: URL of the preview
          readOnly: true
    PreviewToken:
      type: object
      description: Token for a Preview
      properties:
        metadata:
          $ref: '#/components/schemas/PreviewTokenMetadata'
        spec:
          $ref: '#/components/schemas/PreviewTokenSpec'
      required:
      - metadata
      - spec
    PreviewTokenMetadata:
      type: object
      description: PreviewTokenMetadata
      properties:
        name:
          type: string
          description: Token name
        previewName:
          type: string
          description: Preview name
        resourceName:
          type: string
          description: Resource name
        resourceType:
          type: string
          description: Resource type
        workspace:
          type: string
          description: Workspace name
      required:
      - name
    PreviewTokenSpec:
      type: object
      description: Spec for a Preview Token
      properties:
        expired:
          type: boolean
          description: Whether the token is expired
          readOnly: true
        expiresAt:
          type: string
          description: Expiration time of the token
        token:
          type: string
          description: Token
          readOnly: true
    PrivateLocation:
      type: object
      description: Private location available for policies
      properties:
        name:
          type: string
          description: Location name
      x-stainless-ignore: true
    ProxyConfig:
      type: object
      description: Proxy configuration for routing sandbox HTTP traffic through the
        platform proxy with MITM inspection and per-destination header/body injection
      properties:
        allowedDomains:
          type: array
          description: List of allowed external domains (allowlist). When set, only
            these domains are reachable. Supports wildcards (e.g. *.s3.amazonaws.com).
          items:
            type: string
          example: '["api.stripe.com", "api.openai.com", "*.s3.amazonaws.com"]'
        bypass:
          type: array
          description: Domains that bypass the proxy entirely via the NO_PROXY directive.
            Traffic to these destinations goes direct, not through the CONNECT tunnel.
            Supports wildcards. Note that localhost, private ranges (10.0.0.0/8, 172.16.0.0/12,
            192.168.0.0/16), 169.254.169.254, .local and .internal are always bypassed
            by default.
          items:
            type: string
          example: '["*.s3.amazonaws.com"]'
        forbiddenDomains:
          type: array
          description: List of forbidden external domains (denylist). When set, all
            domains except these are reachable. Supports wildcards (e.g. *.malware.com).
            If both allowedDomains and forbiddenDomains are set, allowedDomains takes
            precedence.
          items:
            type: string
          example: '["*.malware.com", "evil.example.org"]'
        routing:
          type: array
          description: Per-destination routing rules with header/body injection and
            secrets. Use destinations ["*"] for global rules that apply to all destinations.
          items:
            $ref: '#/components/schemas/ProxyTarget'
    ProxyTarget:
      type: object
      description: Routing rule that injects headers and body fields into requests
        matching the given destinations. Use destinations ["*"] for a global rule
        that applies to all proxied traffic.
      properties:
        body:
          type: object
          description: Body fields to inject into matching requests. Values may contain
            {{SECRET:name}} references resolved from this rule's secrets.
          additionalProperties:
            type: string
          example: '{"api_key": "{{SECRET:stripe-key}}"}'
        destinations:
          type: array
          description: Destination domains this rule applies to. Use ["*"] for a global
            rule that matches all destinations.
          items:
            type: string
          example: '["api.stripe.com"]'
        headers:
          type: object
          description: Headers to inject into matching requests. Values may contain
            {{SECRET:name}} references resolved from this rule's secrets.
          additionalProperties:
            type: string
          example: '{"Authorization": "Bearer {{SECRET:stripe-key}}"}'
        secrets:
          type: object
          description: 'Named secret values for this routing rule, referenced in headers/body
            via {{SECRET:name}}. Stored encrypted at rest. Write-only: never returned
            in API responses.'
          additionalProperties:
            type: string
          example: '{"stripe-key": "sk-live-abc123..."}'
    PublicIp:
      type: object
      properties:
        description:
          type: string
          description: Description of the region/location
        ipv4Cidrs:
          type: array
          description: List of public ipv4 addresses
          items:
            type: string
        ipv6Cidrs:
          type: array
          description: List of public ipv6 addresses
          items:
            type: string
    PublicIps:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/PublicIp'
    Region:
      type: object
      description: Region
      properties:
        agentDrivePublicUrl:
          type: object
          description: S3-compatible endpoint URL for drive storage in this region.
            Use {s3Endpoint}/{bucketName} to access drive contents.
        allowed:
          type: string
          description: Region display name
        continent:
          type: string
          description: Region display name
        country:
          type: string
          description: Region display name
        drivesAvailable:
          type: boolean
          description: Drives availability status - indicates if an S3 endpoint is
            configured for the region
        egressAvailable:
          type: boolean
          description: Egress availability status - indicates if network plane URL
            is configured for the region
        infoGeneration:
          type: string
          description: Region display name
        location:
          type: string
          description: Region display name
        mk31Available:
          type: boolean
          description: Whether this region supports mk3.1 (blaxel nodes). Required
            for Application and Job deployments.
        name:
          type: string
          description: Region name
        proxyAvailable:
          type: boolean
          description: Proxy availability status - indicates if the proxy plane is
            configured for the region
      x-stainless-ignore: true
    Repository:
      type: object
      description: Repository
      properties:
        type:
          type: string
          description: Repository type
          example: github
        url:
          type: string
          description: Repository URL
          example: https://github.com/my-org/my-agent
    RevisionConfiguration:
      type: object
      description: Revision configuration
      properties:
        active:
          type: string
          description: Active revision id
          example: rev-abc123
        canary:
          type: string
          description: Canary revision id
        canaryPercent:
          type: integer
          description: Canary revision percent
          example: 10
        stickySessionTtl:
          type: integer
          description: Sticky session TTL in seconds (0 = disabled)
          example: 0
        traffic:
          type: integer
          description: Traffic percentage
          example: 100
    RevisionMetadata:
      type: object
      description: Revision metadata
      properties:
        active:
          type: boolean
          description: Is the revision active
        canary:
          type: boolean
          description: Is the revision canary
        createdAt:
          type: string
          description: Revision created at
          readOnly: true
        createdBy:
          type: string
          description: Revision created by
          readOnly: true
        id:
          type: string
          description: Revision ID
          readOnly: true
        previousActive:
          type: boolean
          description: Is the revision previous active
        status:
          type: string
          description: Status of the revision
          readOnly: true
        trafficPercent:
          type: integer
          description: Percent of traffic to the revision
    SSODomain:
      type: object
      description: |-
        SSO domain for SAML-based Single Sign-On
        An SSO domain links an email domain (e.g., acme.com) to a workspace so that
        users with that email domain are redirected to the workspace's
        SSO/SAML identity provider during login.
      properties:
        metadata:
          $ref: '#/components/schemas/SSODomainMetadata'
        spec:
          $ref: '#/components/schemas/SSODomainSpec'
      required:
      - metadata
      - spec
      x-stainless-ignore: true
    SSODomainMetadata:
      type: object
      description: SSO domain metadata
      allOf:
      - $ref: '#/components/schemas/TimeFields'
      - $ref: '#/components/schemas/OwnerFields'
      - properties:
          accountId:
            type: string
            description: Account ID
          displayName:
            type: string
            description: Display name for the SSO domain
            example: Acme Corp
          name:
            type: string
            description: Domain name (e.g., "acme.com")
            example: acme.com
    SSODomainSpec:
      type: object
      description: SSO domain specification
      properties:
        allowedAuthMethods:
          type: array
          description: List of allowed login methods for this domain. When set, users
            with this email domain can only use the specified methods. Possible values
            are google, saml, email. Empty list means no restriction.
          items:
            type: string
        autoJoinWorkspaces:
          type: array
          description: List of workspace names where users with this domain auto-join
            on login
          items:
            type: string
        lastUsedAuthMethod:
          type: string
          description: The authentication method last used by a user with this domain
            (google, saml, email)
          readOnly: true
        lastUsedAuthMethodAt:
          type: string
          description: Timestamp of when the last authentication method was used
          readOnly: true
        lastVerifiedAt:
          type: string
          description: Last verification attempt timestamp
          readOnly: true
        status:
          type: string
          description: Current verification status of the domain (pending, verified,
            failed)
          enum:
          - pending
          - verified
          - failed
          readOnly: true
          example: verified
        txtRecordName:
          type: string
          description: DNS TXT record name that must be created for verification
          readOnly: true
        txtRecordValue:
          type: string
          description: DNS TXT record value that must be set for verification
          readOnly: true
        verificationError:
          type: string
          description: Error message if verification failed
          readOnly: true
      x-stainless-ignore: true
    Sandbox:
      type: object
      description: Lightweight virtual machine for secure AI code execution. Sandboxes
        resume from standby in under 25ms and automatically scale to zero after inactivity,
        preserving memory state including running processes and filesystem.
      properties:
        archive:
          $ref: '#/components/schemas/SandboxArchive'
        errors:
          type: array
          description: Infrastructure failures recorded on the sandbox, oldest first
            (read-only, managed by the system)
          items:
            $ref: '#/components/schemas/SandboxInfrastructureError'
          readOnly: true
        events:
          $ref: '#/components/schemas/CoreEvents'
        expiresIn:
          type: integer
          description: Time in seconds until the sandbox is automatically deleted
            based on TTL and lifecycle policies. Only present for sandboxes with lifecycle
            configured.
          readOnly: true
        lastUsedAt:
          type: string
          description: Last time the sandbox was used (read-only, managed by the system)
          readOnly: true
        metadata:
          $ref: '#/components/schemas/Metadata'
        nodeGeneration:
          type: string
          description: Infrastructure generation this sandbox is deployed on (mk3.0
            or mk3.1).
          readOnly: true
        spec:
          $ref: '#/components/schemas/SandboxSpec'
        state:
          type: string
          description: Current state of the sandbox (read-only, managed by the system)
          enum:
          - RUNNING
          - STANDBY
          readOnly: true
        status:
          $ref: '#/components/schemas/Status'
      required:
      - metadata
      - spec
    SandboxArchive:
      type: object
      description: State of the filesystem archive of a sandbox. An archive holds
        the writable filesystem changes and the process configurations of the sandbox,
        not its memory, so restoring it produces a sandbox with the same disk state
        and freshly started processes.
      properties:
        createdAt:
          type: string
          description: When the archive was created (read-only)
          readOnly: true
        generation:
          type: string
          description: Infrastructure generation the archive was taken from (read-only)
          readOnly: true
          example: mk3.0
        key:
          type: string
          description: Storage key of the archive (read-only)
          readOnly: true
          example: my-workspace/my-sandbox.tar
        restore:
          $ref: '#/components/schemas/SandboxArchiveRestore'
        restoreStartedAt:
          type: string
          description: When the restore of the archive started, while the sandbox
            is being unarchived (read-only)
          readOnly: true
        size:
          type: integer
          description: Size of the archive in bytes (read-only)
          readOnly: true
        startedAt:
          type: string
          description: When the archive was started, while the filesystem of the sandbox
            is still being uploaded (read-only)
          readOnly: true
    SandboxArchiveRestore:
      type: object
      description: Progress of the restore of a sandbox archive. A restore writes
        the archived filesystem over the image the sandbox booted from, which takes
        as long as the archive is big; the sandbox answers and its terminal is reachable
        throughout, but nothing may write to its filesystem until the restore is done.
      properties:
        files:
          type: integer
          description: Number of files restored so far (read-only)
          readOnly: true
        restoredBytes:
          type: integer
          description: Bytes of the archive restored so far (read-only)
          readOnly: true
        state:
          type: string
          description: Phase of the restore (read-only)
          enum:
          - downloading
          - extracting
          - relaunching
          - succeeded
          - failed
          readOnly: true
          example: extracting
        totalBytes:
          type: integer
          description: Total size of the archive being restored in bytes, absent when
            the store did not announce it (read-only)
          readOnly: true
    SandboxCreationOptions:
      type: object
      description: Optional Hub template settings applied by the console without additional
        sandbox creation lookups.
      properties:
        extraArgs:
          maxProperties: 8
          type: object
          description: Kernel selection arguments copied into runtime.extraArgs. At
            most 8 entries.
          additionalProperties:
            type: string
        volumes:
          maxItems: 5
          type: array
          description: Volume attachments included in the creation request. At most
            5 attachments per template.
          items:
            $ref: '#/components/schemas/VolumeAttachment'
    SandboxDefinition:
      type: object
      description: Pre-configured sandbox template available in the Sandbox Hub for
        quick deployment with predefined tools and configurations
      properties:
        categories:
          type: array
          description: Categories of the definition
          items:
            type: object
            additionalProperties: true
        coming_soon:
          type: boolean
          description: If the definition is coming soon
          example: false
        creationOptions:
          $ref: '#/components/schemas/SandboxCreationOptions'
        description:
          type: string
          description: Description of the definition
          example: Python environment with data science libraries pre-installed
        displayName:
          type: string
          description: Display name of the definition
          example: Python Data Science
        enterprise:
          type: boolean
          description: If the definition is enterprise
          example: false
        hidden:
          type: boolean
          description: If the definition is hidden
          example: false
        icon:
          type: string
          description: Icon of the definition
        iconDark:
          type: string
          description: Nonempty dark-mode icon URL in responses. Blank inputs use
            the resolved light-mode icon.
        iconLight:
          type: string
          description: Nonempty light-mode icon URL in responses. Blank inputs use
            icon, iconDark, then the default Hub icon.
        image:
          type: string
          description: Image of the Sandbox definition
          example: blaxel/python-data-science:latest
        longDescription:
          type: string
          description: Long description of the definition
        memory:
          type: integer
          description: Memory of the Sandbox definition in MB
          example: 2048
        name:
          type: string
          description: Name of the artifact
          example: python-data-science
        ports:
          $ref: '#/components/schemas/Ports'
        tags:
          type: string
          description: Tags of the definition
        url:
          type: string
          description: URL of the definition
    SandboxError:
      type: object
      description: Error response returned by the CreateSandbox endpoint with extended
        details about the failure
      properties:
        code:
          type: string
          description: Error code identifying the kind of error (e.g., INVALID_IMAGE,
            QUOTA_EXCEEDED)
          example: INVALID_IMAGE
        details:
          type: object
          description: Additional error details. For INVALID_IMAGE errors, includes
            requested_image and supported_images array.
          additionalProperties: true
        message:
          type: string
          description: Human-readable error message describing what went wrong
          example: Sandbox image blaxel/dev-ts-app:latest is not supported
        sandbox_name:
          type: string
          description: Name of the sandbox that failed to create
          example: mysandbox
        status_code:
          type: integer
          description: HTTP status code
          example: 400
        step:
          type: string
          description: Processing step where the error occurred
          example: validate_and_prepare
        timestamp:
          type: string
          description: ISO 8601 timestamp of when the error occurred
          example: "2025-12-19T22:36:29.336304095Z"
        workspace:
          type: string
          description: Workspace name where the sandbox creation was attempted
          example: main
      required:
      - code
      - message
    SandboxForkRequest:
      type: object
      description: Request body for forking a sandbox into an application. Creates
        a new application or adds a canary revision to an existing one.
      properties:
        customDomain:
          type: string
          description: Custom domain for the application
        envs:
          type: array
          description: Environment variables the fork runs with, on top of the ones
            the source has. A variable the source already carries takes this value
            in the fork, one it does not is added, and every other variable of the
            source is kept.
          items:
            $ref: '#/components/schemas/Env'
        lifecycle:
          $ref: '#/components/schemas/SandboxLifecycle'
        port:
          type: integer
          description: Port to expose from the sandbox
          example: 8080
        prefix:
          type: string
          description: URL prefix for the application
        snapshotId:
          type: string
          description: Snapshot ID to fork from. When set, the fork is created from
            that existing snapshot (and an application revision references it). When
            omitted, a fork to a sandbox copies the source sandbox's live state directly
            and no snapshot is persisted; a fork to an application still takes a snapshot,
            since its revision references one.
        targetName:
          type: string
          description: Name of the target application to create or update
          example: my-app
        targetType:
          type: string
          description: Target resource type to fork into
          example: application
        traffic:
          type: integer
          description: Traffic percentage for canary deployment (0-100). When set
            on an existing target, creates a new revision with this traffic percentage.
          example: 10
      required:
      - targetType
      - targetName
    SandboxForkResponse:
      type: object
      description: Response returned after forking a sandbox. Contains either the
        new sandbox or application depending on the fork type.
      properties:
        name:
          type: string
          description: Name of the created or updated resource
        snapshotId:
          type: string
          description: The snapshot ID the fork was created from. Set only when the
            fork went through a snapshot, meaning an explicit snapshotId was supplied
            or the fork target is an application. Empty when the fork copied the source
            sandbox's live state directly.
        type:
          type: string
          description: Type of resource that was created (sandbox or application)
          enum:
          - sandbox
          - application
    SandboxInfrastructureError:
      type: object
      description: Infrastructure failure the compute plane reported for a sandbox
      properties:
        code:
          type: string
          description: Stable code of the failure pattern
          example: VM_NETWORK_FAILURE
        fatal:
          type: boolean
          description: Whether the failure was terminal, putting the sandbox in FAILED,
            as opposed to being cleared by a restart
        instance:
          type: string
          description: Instance the failure was reported for
        message:
          type: string
          description: Reason reported with the failure
        time:
          type: string
          description: Time at which the failure was recorded
    SandboxLifecycle:
      type: object
      description: Lifecycle configuration controlling automatic sandbox deletion
        based on idle time, max age, or specific dates
      properties:
        expirationPolicies:
          type: array
          description: List of expiration policies. Multiple policies can be combined;
            whichever condition is met first triggers the action.
          items:
            $ref: '#/components/schemas/ExpirationPolicy'
        terminatedRetention:
          type: string
          description: Duration to keep the sandbox record after termination for log
            access (e.g., '1h', '24h', '7d'). Defaults to 5m. Subject to maximum quota
            limits.
          example: 24h
    SandboxList:
      type: object
      description: Cursor-paginated list of sandboxes. Returned starting with API
        version 2026-04-28; older API versions return a bare array.
      properties:
        data:
          type: array
          description: Page of sandboxes. Items use the lite shape (no inline event
            history) to keep the page payload small, matching the unpaginated response.
          items:
            $ref: '#/components/schemas/Sandbox'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    SandboxNetwork:
      type: object
      description: Network configuration for a sandbox including subnet, firewall
        rulesets, domain filtering, egress IP binding, and proxy settings
      properties:
        allowedDomains:
          type: array
          description: 'Deprecated: use proxy.allowedDomains instead. List of allowed
            external domains (allowlist). Kept for backward compatibility.'
          items:
            type: string
          example: '["api.stripe.com", "api.openai.com", "*.s3.amazonaws.com"]'
        egress:
          $ref: '#/components/schemas/EgressConfig'
        firewall:
          $ref: '#/components/schemas/FirewallConfig'
        forbiddenDomains:
          type: array
          description: 'Deprecated: use proxy.forbiddenDomains instead. List of forbidden
            external domains (denylist). Kept for backward compatibility.'
          items:
            type: string
          example: '["*.malware.com", "evil.example.org"]'
        proxy:
          $ref: '#/components/schemas/ProxyConfig'
        subnet:
          type: string
          description: Subnet name for the sandbox. Takes priority over any subnet
            derived from egress config. Defaults to "default" when absent.
          example: default
    SandboxRestoreResponse:
      type: object
      description: Result of restoring a sandbox to one of its snapshots. The sandbox
        keeps its name and URLs; everything it held since the snapshot was taken is
        gone.
      properties:
        name:
          type: string
          description: Name of the restored sandbox
        snapshotId:
          type: string
          description: Snapshot the sandbox was restored from
      required:
      - name
      - snapshotId
    SandboxRuntime:
      type: object
      description: Runtime configuration defining how the sandbox VM is provisioned
        and its resource limits
      properties:
        envs:
          type: array
          description: Environment variables injected into the sandbox. Supports Kubernetes
            EnvVar format with valueFrom references.
          items:
            $ref: '#/components/schemas/Env'
        expires:
          type: string
          description: Absolute expiration timestamp in ISO 8601 format when the sandbox
            will be deleted
          example: "2025-12-31T23:59:59Z"
        extraArgs:
          type: object
          description: 'Extra arguments for kernel selection. Supported keys: ''iptables'',
            ''nfs'' (mk3.0), ''tun'', ''android'' and ''landlock'' (mk3.1). The android
            variant includes tun and iptables and cannot be combined with nfs. The
            landlock variant enables the Landlock LSM, includes tun and iptables,
            and cannot be combined with android or nfs. Android and landlock requests
            are rejected if routing selects mk3.0. ''kernelExtensions'' (mk3.1, android
            only for now) switches on the selected kernel''s loadable modules and
            kernel tracing (eBPF, kprobes, perf); without it they are disabled, even
            for root. Values: ''enabled'' or ''disabled''. Determines which kernel
            variant the workload runs on. Immutable after creation.'
          additionalProperties:
            type: string
        image:
          type: string
          description: Sandbox image to use. Can be a public Blaxel image (e.g., blaxel/base-image:latest)
            or a custom template image built with 'bl deploy'.
          example: blaxel/base-image:latest
        memory:
          type: integer
          description: Memory allocation in megabytes. Also determines CPU allocation
            (CPU cores = memory in MB / 2048, e.g., 4096MB = 2 CPUs).
          example: 4096
        ports:
          $ref: '#/components/schemas/Ports'
        standbyGracePeriodSeconds:
          type: integer
          description: 'Seconds the sandbox gets after a SIGUSR2 to prepare before
            it goes to standby (scale to zero). The workload can say it is done earlier
            by writing to $BLAXEL_STANDBY_READY_FILE. Defaults to 0: no signal, immediate
            standby.'
          example: 10
        terminationGracePeriodSeconds:
          type: integer
          description: Duration in seconds the pod needs to terminate gracefully.
            Defaults to 0 for immediate termination.
          example: 30
        ttl:
          type: string
          description: 'Max-age from creation: the sandbox is deleted this long after
            it is created, regardless of activity (not an idle timeout). Units s,
            m, h, d, w (e.g., ''30m'', ''24h'', ''7d'', ''2w''), minimum ''5m''. For
            idle-based cleanup, use a lifecycle expiration policy of type ttl-idle.'
          example: 24h
    SandboxScheduleEntry:
      type: object
      description: A scheduled task that executes a process inside the sandbox at
        specified times. Stored in the dedicated schedules table (no longer embedded
        in the sandbox spec).
      properties:
        createdAt:
          type: string
          description: Creation timestamp (read-only).
          readOnly: true
        id:
          type: string
          description: Unique identifier for this schedule within its sandbox. Auto-generated
            if not provided.
          example: schedule-0
        input:
          $ref: '#/components/schemas/SandboxScheduleInput'
        maxExecutions:
          type: integer
          description: Maximum number of execution records kept for this schedule.
            Once reached, recording a new execution deletes the oldest. Defaults to
            100.
          example: 100
        sandbox:
          type: string
          description: Name of the sandbox this schedule belongs to.
          readOnly: true
        type:
          type: string
          description: Type of schedule timing. 'cron' for recurring (5-field expression),
            'at' for a specific RFC 3339 datetime, 'sleep' for a duration from now
            (resolved to 'at' on creation).
          enum:
          - cron
          - at
          - sleep
          example: cron
        value:
          type: string
          description: 'Timing value. For ''cron'': a 5-field cron expression (e.g.
            ''0 8 * * 1-5''). For ''at'': an RFC 3339 datetime (e.g. ''2026-07-01T09:00:00Z'').
            For ''sleep'': a duration (e.g. ''2h'', ''30m'', ''7d'').'
          example: 0 8 * * 1-5
    SandboxScheduleEntryList:
      type: object
      description: Cursor-paginated list of a sandbox's schedule definitions.
      properties:
        data:
          type: array
          description: Page of schedule definitions.
          items:
            $ref: '#/components/schemas/SandboxScheduleEntry'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    SandboxScheduleExecution:
      type: object
      description: One recorded execution of a sandbox schedule. status and statusCode
        describe whether the scheduler's process submission was accepted; the scheduler
        does not wait for the process to finish. Stored in the dedicated scheduleexecutions
        table.
      properties:
        createdAt:
          type: string
          description: Creation timestamp (read-only).
          readOnly: true
        error:
          type: string
          description: Reason the execution failed, naming the resource that could
            not be reached. Empty when the command was accepted by the sandbox.
          example: sandbox my-sandbox is not reachable at https://xxx.us-pdx-1.bl.run
            (HTTP 404)
        executedAt:
          type: string
          description: RFC 3339 time at which the command was submitted.
          example: "2026-07-01T09:00:00Z"
        id:
          type: string
          description: Unique id of this execution within the schedule.
          example: "00000000000000000042"
        processName:
          type: string
          description: Name of the process started in the sandbox for this execution,
            used to look up its logs.
          example: training-job
        sandbox:
          type: string
          description: Name of the sandbox this execution belongs to.
          readOnly: true
        scheduleId:
          type: string
          description: Id of the schedule this execution belongs to.
          example: schedule-0
        status:
          type: string
          description: Whether submitting the process request was accepted. This is
            not the process completion status.
          enum:
          - succeeded
          - failed
          readOnly: true
        statusCode:
          type: integer
          description: HTTP status code returned when the scheduled command was submitted
            to the sandbox (0 if the sandbox could not be reached). 2xx/3xx means
            the command was accepted.
          example: 200
        timeout:
          type: integer
          description: Process timeout in seconds for this execution. The UI uses
            it to scope the log view to [executedAt, executedAt+timeout]. 0 when the
            schedule set no timeout.
          example: 600
    SandboxScheduleExecutionList:
      type: object
      description: Cursor-paginated list of a sandbox's schedule execution history
        (across all its schedules).
      properties:
        data:
          type: array
          description: Page of schedule executions.
          items:
            $ref: '#/components/schemas/SandboxScheduleExecution'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    SandboxScheduleExecutionStatusMetrics:
      type: object
      description: Schedule execution counts grouped by submission acceptance status.
      properties:
        failed:
          type: integer
          description: Number of process submissions that were not accepted.
        succeeded:
          type: integer
          description: Number of process submissions accepted by the sandbox.
    SandboxScheduleInput:
      type: object
      description: Process execution configuration for a scheduled sandbox task
      properties:
        command:
          type: string
          description: Shell command to execute inside the sandbox
          example: python train.py --epochs 10
        env:
          type: object
          description: Environment variables to set for the process. May contain secrets,
            so values are encrypted at rest and masked in API responses unless an
            admin requests show_secrets=true.
          additionalProperties:
            type: string
        keepAlive:
          type: boolean
          description: Keep the sandbox alive (disable scale-to-zero) while the process
            runs. Defaults to true.
          example: true
        name:
          type: string
          description: Optional name for the process (used to retrieve status/logs)
          example: training-job
        timeout:
          type: integer
          description: Timeout in seconds for the process. Defaults to 600 (10 minutes).
            Set to 0 for no timeout.
          example: 3600
        workingDir:
          type: string
          description: Working directory for the command
          example: /app
    SandboxScheduleMetrics:
      type: object
      description: Workspace sandbox scheduling metrics for a UTC minute window. since
        is inclusive and until is exclusive.
      properties:
        executions:
          type: integer
          description: Number of schedule execution submissions in the selected window.
        executionsByStatus:
          $ref: '#/components/schemas/SandboxScheduleExecutionStatusMetrics'
        sandboxes:
          type: integer
          description: Number of active sandboxes in the workspace.
        schedules:
          type: integer
          description: Number of schedules in the workspace.
        since:
          type: string
          description: Inclusive beginning of the metrics window, normalized to a
            UTC minute.
        until:
          type: string
          description: Exclusive end of the metrics window, normalized to a UTC minute.
    SandboxSnapshot:
      type: object
      description: 'A point-in-time snapshot of a sandbox. It is a workspace-level
        object: it outlives the sandbox it was captured from, and can be restored
        onto a sandbox or forked into a new sandbox or application on its own.'
      properties:
        createdAt:
          type: string
          description: When the snapshot was created
        createdBy:
          type: string
          description: Who created the snapshot
        id:
          type: string
          description: Identifier of the snapshot, unique in the workspace. Workspace-level
            routes address the snapshot by it.
          readOnly: true
          example: snap_abc123
        name:
          type: string
          description: Display name of the snapshot, unique among the snapshots of
            the sandbox it was captured from. Defaults to the identifier.
          example: my-snapshot
        sandboxName:
          type: string
          description: Name of the source sandbox. Kept for compatibility, read source.name
            instead.
        source:
          $ref: '#/components/schemas/SandboxSnapshotSource'
        spec:
          $ref: '#/components/schemas/SandboxSnapshotSpec'
        status:
          type: string
          description: Status of the snapshot (pending, ready, failed)
          example: ready
        workspace:
          type: string
          description: Workspace owning the snapshot
      required:
      - workspace
      - name
      - id
      - createdAt
      - status
    SandboxSnapshotList:
      type: object
      description: Cursor-paginated list of snapshots. Returned starting with API
        version 2026-04-28; older API versions return a bare array.
      properties:
        data:
          type: array
          description: Page of snapshots.
          items:
            $ref: '#/components/schemas/SandboxSnapshot'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    SandboxSnapshotRequest:
      type: object
      description: Request body for creating a snapshot. The source object is required
        at the root endpoint and implied by the path on the nested one.
      properties:
        name:
          type: string
          description: Display name of the snapshot, unique among the snapshots of
            the sandbox it is captured from; the same name may be reused on another
            sandbox. Defaults to the snapshot identifier when absent.
          example: my-snapshot
        source:
          $ref: '#/components/schemas/SandboxSnapshotSource'
    SandboxSnapshotSource:
      type: object
      description: The object a snapshot was captured from.
      properties:
        deleted:
          type: boolean
          description: Whether the source object has since been deleted. The snapshot
            stays usable, the link is only kept for context.
          readOnly: true
        kind:
          type: string
          description: Kind of the object the snapshot was captured from. Defaults
            to sandbox, the only kind that can be captured today.
          enum:
          - sandbox
          example: sandbox
          default: sandbox
        name:
          type: string
          description: Name of the object the snapshot was captured from
      required:
      - name
    SandboxSnapshotSpec:
      type: object
      description: The configuration a snapshot carries, so a sandbox or an application
        can be created from it once its source object is gone.
      properties:
        generation:
          type: string
          description: Infrastructure generation the snapshot was captured on. A snapshot
            only restores on the generation it came from.
          enum:
          - mk2
          - mk3
        image:
          type: string
          description: Image the source object ran
        memory:
          type: integer
          description: Memory in MB the source object ran with
        ports:
          $ref: '#/components/schemas/Ports'
        region:
          type: string
          description: Region holding the snapshot. Restores and forks land in it.
        volumes:
          $ref: '#/components/schemas/VolumeAttachments'
    SandboxSnapshots:
      type: array
      items:
        $ref: '#/components/schemas/SandboxSnapshot'
    SandboxSpec:
      type: object
      description: Configuration for a sandbox including its image, memory, ports,
        region, and lifecycle policies
      properties:
        enabled:
          type: boolean
          description: When false, the sandbox is disabled and will not accept connections
          example: true
          default: true
        lifecycle:
          $ref: '#/components/schemas/SandboxLifecycle'
        network:
          $ref: '#/components/schemas/SandboxNetwork'
        region:
          type: string
          description: Region where the sandbox should be created (e.g. us-pdx-1,
            eu-lon-1). If not specified, defaults to the region closest to the user.
          example: us-pdx-1
        runtime:
          $ref: '#/components/schemas/SandboxRuntime'
        volumes:
          $ref: '#/components/schemas/VolumeAttachments'
        vpc:
          type: string
          description: VPC name for the sandbox. Defaults to "default" when absent.
          example: default
    Secret:
      type: object
      description: Workspace secret, referenced from proxy routing as {{SECRET:name}}.
        Values are write-only and can never be read back. Every upsert stores a new
        immutable version and the latest one is resolved at runtime.
      properties:
        createdAt:
          type: string
          description: The date and time when the secret was first created
          readOnly: true
        name:
          type: string
          description: Case-sensitive secret name
        updatedAt:
          type: string
          description: The date and time of the latest version
          readOnly: true
        value:
          type: string
          description: Secret value. Write-only, never returned by the API
      required:
      - name
    Status:
      type: string
      description: Deployment status of a resource deployed on Blaxel
      enum:
      - DELETING
      - TERMINATED
      - FAILED
      - DEACTIVATED
      - DEACTIVATING
      - UPLOADING
      - BUILDING
      - DEPLOYING
      - DEPLOYED
      - BUILT
      - ARCHIVING
      - ARCHIVED
      - UNARCHIVING
      readOnly: true
    Template:
      type: object
      description: Blaxel template
      properties:
        defaultBranch:
          type: string
          description: Default branch of the template
          example: main
        description:
          type: string
          description: Description of the template
          example: A starter template for building LangChain agents
        downloadCount:
          type: integer
          description: Number of downloads/clones of the repository
          example: 1200
        forksCount:
          type: integer
          description: Number of forks the repository has
          example: 45
        icon:
          type: string
          description: URL to the template's icon
        iconDark:
          type: string
          description: URL to the template's icon in dark mode
        name:
          type: string
          description: Name of the template
          example: langchain-agent
        sha:
          type: string
          description: SHA of the variable
        starCount:
          type: integer
          description: Number of stars the repository has
          example: 150
        topics:
          type: array
          description: Topic of the template
          items:
            type: string
        url:
          type: string
          description: URL of the template
          example: https://github.com/blaxel-ai/template-langchain-agent
        variables:
          type: array
          description: Variables of the template
          items:
            $ref: '#/components/schemas/TemplateVariable'
    TemplateVariable:
      type: object
      description: Blaxel template variable
      properties:
        description:
          type: string
          description: Description of the variable
          example: OpenAI API key for the agent
        integration:
          type: string
          description: Integration of the variable
          example: openai
        name:
          type: string
          description: Name of the variable
          example: OPENAI_API_KEY
        path:
          type: string
          description: Path of the variable
          example: .env
        secret:
          type: boolean
          description: Whether the variable is secret
          example: true
    TimeFields:
      type: object
      description: Time fields for Persistence
      properties:
        createdAt:
          type: string
          description: The date and time when the resource was created
          readOnly: true
        updatedAt:
          type: string
          description: The date and time when the resource was updated
          readOnly: true
    Trigger:
      type: object
      description: Trigger configuration
      properties:
        configuration:
          $ref: '#/components/schemas/TriggerConfiguration'
        enabled:
          type: boolean
          description: 'Enable or disable the trigger (default: true)'
          example: true
        id:
          type: string
          description: Identifier of the trigger. Optional — the server auto-generates
            a unique id when one is not provided, and disambiguates duplicates within
            a resource.
          example: trigger-1
        type:
          type: string
          description: The type of trigger, can be http or http-async
          enum:
          - http
          - http-async
          - cron
          example: http
    TriggerConfiguration:
      type: object
      description: Trigger configuration
      properties:
        authenticationType:
          type: string
          description: The authentication type of the trigger
          example: blaxel
        callbackSecret:
          type: string
          description: The callback secret for async triggers (auto-generated, encrypted)
          readOnly: true
        callbackUrl:
          type: string
          description: The callback URL for async triggers (optional)
          example: https://myapp.com/webhook
        path:
          type: string
          description: The path of the trigger
          example: /invoke
        retry:
          type: integer
          description: The retry of the trigger
          example: 3
        schedule:
          type: string
          description: The schedule of the trigger, cron expression * * * * *
          example: 0 * * * *
        tasks:
          type: array
          description: The tasks configuration of the cronjob
          items:
            $ref: '#/components/schemas/TriggerConfigurationTask'
        tasksRef:
          type: string
          description: Where this trigger's task list is stored (server-managed)
          readOnly: true
        timeout:
          type: integer
          description: The timeout in seconds for async triggers (max 900s, MK3 only)
          example: 300
    TriggerConfigurationTask:
      type: object
      description: The tasks configuration of the cronjob
    Triggers:
      type: array
      description: Triggers to use your agent
      items:
        $ref: '#/components/schemas/Trigger'
    VPC:
      type: object
      description: Virtual Private Cloud scoped to a workspace for network isolation
        and dedicated egress
      properties:
        events:
          $ref: '#/components/schemas/CoreEvents'
        metadata:
          $ref: '#/components/schemas/Metadata'
        spec:
          $ref: '#/components/schemas/VPCSpec'
        status:
          $ref: '#/components/schemas/Status'
      required:
      - metadata
      - spec
    VPCSpec:
      type: object
      description: VPC specification (controlplane-only, no external resources)
      additionalProperties: true
    Volume:
      type: object
      description: Persistent storage volume that can be attached to sandboxes for
        durable file storage across sessions. Volumes survive sandbox deletion and
        can be reattached to new sandboxes.
      properties:
        events:
          $ref: '#/components/schemas/CoreEvents'
        metadata:
          $ref: '#/components/schemas/Metadata'
        spec:
          $ref: '#/components/schemas/VolumeSpec'
        state:
          $ref: '#/components/schemas/VolumeState'
        status:
          type: string
          description: Volume status computed from events
          readOnly: true
        terminatedAt:
          type: string
          description: Timestamp when the volume was marked for termination
          readOnly: true
      required:
      - metadata
      - spec
    VolumeAttachment:
      type: object
      description: Configuration for attaching a volume to a sandbox at a specific
        filesystem path. Defaults to a persistent volume; set type to "ephemeral"
        for disk-backed scratch space created with the sandbox and destroyed when
        it stops.
      properties:
        mountPath:
          type: string
          description: Absolute filesystem path where the volume will be mounted inside
            the sandbox
          example: /mnt/data
        name:
          type: string
          description: For persistent volumes, the name of the volume resource to
            attach (must exist in the same workspace and region). For ephemeral volumes,
            an identifier used to reference the volume internally.
          example: my-volume
        readOnly:
          type: boolean
          description: If true, the volume is mounted read-only and cannot be modified
            by the sandbox
          example: false
        sizeMb:
          type: integer
          description: Storage capacity in megabytes. Required for ephemeral volumes,
            ignored for persistent volumes.
          example: 102400
        type:
          type: string
          description: Type of volume. Defaults to "persistent" (an existing volume
            resource). Use "ephemeral" for temporary disk-backed storage created with
            the sandbox.
          enum:
          - persistent
          - ephemeral
          example: persistent
    VolumeAttachments:
      type: array
      items:
        $ref: '#/components/schemas/VolumeAttachment'
    VolumeList:
      type: object
      description: Cursor-paginated list of volumes. Returned starting with API version
        2026-04-28; older API versions return a bare array. Items use the lite shape
        (no inline event history).
      properties:
        data:
          type: array
          description: Page of volumes.
          items:
            $ref: '#/components/schemas/LiteVolume'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    VolumeSpec:
      type: object
      description: Immutable volume configuration set at creation time (size and region
        cannot be changed after creation)
      properties:
        region:
          type: string
          description: Deployment region for the volume (e.g., us-pdx-1, eu-lon-1).
            Must match the region of sandboxes it attaches to.
          example: us-pdx-1
        size:
          type: integer
          description: Storage capacity in megabytes. Can be increased after creation
            but not decreased.
          example: 1024
        template:
          type: string
          description: Volume template to initialize from, with optional revision
            (e.g., "mytemplate:1" or "mytemplate:latest")
          example: mytemplate:latest
    VolumeState:
      type: object
      description: Current runtime state of the volume including attachment status
      properties:
        attachedTo:
          type: string
          description: Resource currently using this volume in format "type:name"
            (e.g., "sandbox:my-sandbox"). Empty if not attached.
          example: sandbox:my-sandbox
      readOnly: true
    VolumeTemplate:
      type: object
      description: Volume template for creating pre-configured volumes
      properties:
        metadata:
          $ref: '#/components/schemas/Metadata'
        spec:
          $ref: '#/components/schemas/VolumeTemplateSpec'
        state:
          $ref: '#/components/schemas/VolumeTemplateState'
        versions:
          type: array
          description: List of versions for this template
          items:
            $ref: '#/components/schemas/VolumeTemplateVersion'
      required:
      - metadata
      - spec
    VolumeTemplateSpec:
      type: object
      description: Volume template specification
      properties:
        defaultSize:
          type: integer
          description: Default size of the volume in MB
        description:
          type: string
          description: Description of the volume template
    VolumeTemplateState:
      type: object
      description: Volume template state
      properties:
        lastVersionUploadedAt:
          type: string
          description: Timestamp of last version upload
          readOnly: true
        latestVersion:
          type: string
          description: Current/latest S3 version ID
          readOnly: true
        status:
          type: string
          description: Status of the volume template (created, ready, error)
          enum:
          - created
          - ready
          - error
          readOnly: true
        versionCount:
          type: integer
          description: Total number of versions for this template
          readOnly: true
    VolumeTemplateVersion:
      type: object
      description: Volume template version tracking individual versions of template
        content
      properties:
        bucket:
          type: string
          description: S3 bucket name where this version is stored
          readOnly: true
        contentSize:
          type: integer
          description: Size of the template content in bytes
          readOnly: true
        name:
          type: string
          description: Name of the template version
        region:
          type: string
          description: AWS region where this version is stored
          readOnly: true
        status:
          type: string
          description: Status of the version (CREATED, READY, FAILED)
          enum:
          - CREATED
          - READY
          - FAILED
          readOnly: true
        templateName:
          type: string
          description: Template name this version belongs to
        versionId:
          type: string
          description: S3 version ID for this template version
          readOnly: true
        workspace:
          type: string
          description: Workspace name
          readOnly: true
    Workspace:
      type: object
      description: Tenant container that groups all Blaxel resources (agents, functions,
        models, etc.) with shared team access control and billing.
      allOf:
      - $ref: '#/components/schemas/TimeFields'
      - $ref: '#/components/schemas/OwnerFields'
      - properties:
          accountId:
            type: string
            description: Workspace account id
          basetenTeamId:
            type: string
            description: Baseten team this workspace was provisioned for; absent on
              native workspaces
            readOnly: true
          displayName:
            type: string
            description: Workspace display name
            example: My Workspace
          groupMappings:
            type: array
            description: Group-to-role mappings for directory sync (SCIM) group membership
            items:
              $ref: '#/components/schemas/GroupWorkspaceMapping'
          hipaaInfo:
            $ref: '#/components/schemas/WorkspaceHipaaInfo'
          id:
            type: string
            description: Autogenerated unique workspace id
            readOnly: true
          labels:
            $ref: '#/components/schemas/MetadataLabels'
          name:
            type: string
            description: Workspace name
            example: my-workspace
          region:
            type: string
            description: Workspace write region
            example: us-west-2
          resourceCounts:
            type: object
            description: Per-resource counts (agents, functions, models, sandboxes,
              policies, jobs, volumes, drives, volumetemplates, integrationconnections,
              previews, customdomains, serviceaccounts, images). Only populated when
              GetWorkspace is called with ?countResources=true.
            additionalProperties:
              type: integer
            readOnly: true
          runtime:
            $ref: '#/components/schemas/WorkspaceRuntime'
          status:
            type: string
            description: Workspace status (created, account_binded, account_configured,
              workspace_configured, ready, error)
            enum:
            - created
            - account_binded
            - account_configured
            - workspace_configured
            - ready
            - error
            readOnly: true
            example: ready
          statusReason:
            type: string
            description: Reason for current status (only set for error status)
            readOnly: true
    WorkspaceAvailability:
      type: object
      description: Result of a workspace-name availability check.
      properties:
        available:
          type: boolean
          description: Whether the requested workspace name is available.
        message:
          type: string
          description: Human-readable explanation suitable for display in the UI.
            Empty when available.
        reason:
          type: string
          description: Machine-readable reason explaining why the name is unavailable.
            Empty when available.
          enum:
          - taken
          - forbidden_reserved
          - forbidden_blaxel
          - forbidden_v_prefix
    WorkspaceHipaaInfo:
      type: object
      description: HIPAA compliance state for a workspace. `accountEnabled` mirrors
        the account-level `hipaa_compliance` addon (set server-side from operator
        tooling and Stripe billing events). `unsafe` records a per-workspace opt-out
        toggled from workspace settings; absent when the account does not have the
        addon.
      properties:
        accountEnabled:
          type: boolean
          description: True when the parent account has the HIPAA compliance addon
            active. Set server-side from operator tooling and Stripe billing events;
            cannot be changed from workspace settings.
        unsafe:
          $ref: '#/components/schemas/WorkspaceHipaaUnsafe'
    WorkspaceHipaaUnsafe:
      type: object
      description: Per-workspace HIPAA opt-out record. Toggled from workspace settings;
        the backend stamps `updatedBy` and `updatedAt`.
      properties:
        enabled:
          type: boolean
          description: True marks this workspace as HIPAA-unsafe (NOT compliant),
            overriding the account-level addon. False marks the workspace as HIPAA
            compliant.
        updatedAt:
          type: string
          description: RFC3339 timestamp when the opt-out was last toggled. Stamped
            server-side.
          readOnly: true
        updatedBy:
          type: string
          description: User id (sub) of the actor that last toggled this opt-out.
            Stamped server-side.
          readOnly: true
    WorkspaceRuntime:
      type: object
      description: Runtime configuration for the workspace infrastructure
      properties:
        generation:
          type: string
          description: Infrastructure generation version for the workspace (affects
            available features and deployment behavior)
          example: mk3
        sandbox:
          $ref: '#/components/schemas/WorkspaceSandboxSettings'
    WorkspaceSandboxSettings:
      type: object
      description: Workspace-wide sandbox configuration that applies to all sandbox
        deployments in the workspace.
      properties:
        disableProcessLogging:
          type: boolean
          description: When true, sandbox deployments in this workspace set SANDBOX_DISABLE_PROCESS_LOGGING=true
            to disable per-process stdout/stderr logging. Requires sandbox-api v0.2.28+.
    WorkspaceUser:
      type: object
      description: Workspace user
      properties:
        accepted:
          type: boolean
          description: Whether the user has accepted the workspace invitation
        email:
          type: string
          description: Workspace user email
        email_verified:
          type: boolean
          description: Whether the user's email has been verified
        expired:
          type: boolean
          description: Whether the invitation has expired
        family_name:
          type: string
          description: Workspace user family name
        given_name:
          type: string
          description: Workspace user given name
        mfa_enabled:
          type: boolean
          description: Whether the user has at least one verified MFA factor. Omitted
            when the caller is not entitled to see it (only workspace admins and owners
            see other members' MFA status) and for pending invitations, which have
            no account yet.
        role:
          type: string
          description: Workspace user role
        source:
          type: string
          description: Source of the user provisioning
          enum:
          - directory_sync
          - invitation
          - domain_capture
        sub:
          type: string
          description: Workspace user identifier
  securitySchemes:
    ApiKeyAuth:
      bearerFormat: API Key
      description: Long-lived API key for programmatic access
      scheme: bearer
      type: http
    OAuth2:
      description: OAuth2 authentication with JWT tokens
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          scopes:
            admin: Administrative access
            agents:create: Create agents
            agents:delete: Delete agents
            agents:get: Get agent details
            agents:list: List agents
            agents:update: Update agents
            apiKey:list: List API keys
            apiKey:write: Create and delete API keys
            applications:create: Create applications
            applications:delete: Delete applications
            applications:get: Get application details
            applications:list: List applications
            applications:update: Update applications
            configurations:list: List configurations
            customdomains:create: Create custom domains
            customdomains:delete: Delete custom domains
            customdomains:get: Get custom domain details
            customdomains:list: List custom domains
            customdomains:update: Update custom domains
            functions:create: Create functions
            functions:delete: Delete functions
            functions:get: Get function details
            functions:list: List functions
            functions:update: Update functions
            integrations:create: Create integrations
            integrations:list: List integrations
            invitations:list: List invitations
            jobs:create: Create jobs
            jobs:delete: Delete jobs
            jobs:get: Get job details
            jobs:list: List jobs
            jobs:update: Update jobs
            locations:list: List locations
            mcphub:list: List MCP hub resources
            models:create: Create models
            models:delete: Delete models
            models:get: Get model details
            models:list: List models
            models:update: Update models
            policies:create: Create policies
            policies:delete: Delete policies
            policies:get: Get policy details
            policies:list: List policies
            policies:update: Update policies
            sandboxes:control: Control sandbox operations
            sandboxes:create: Create sandboxes
            sandboxes:delete: Delete sandboxes
            sandboxes:get: Get sandbox details
            sandboxes:list: List sandboxes
            sandboxes:update: Update sandboxes
            sandboxhub:list: List sandbox hub resources
            secrets:create: Create secrets
            secrets:delete: Delete secrets
            secrets:list: List secrets
            templates:get: Get template details
            templates:list: List templates
            volumeTemplates:create: Create volume templates
            volumeTemplates:delete: Delete volume templates
            volumeTemplates:get: Get volume template details
            volumeTemplates:list: List volume templates
            volumeTemplates:upsert: Create or update volume templates
            volumes:create: Create volumes
            volumes:delete: Delete volumes
            volumes:get: Get volume details
            volumes:list: List volumes
            workspaces:accept: Accept workspace invitation
            workspaces:create: Create workspaces
            workspaces:decline: Decline workspace invitation
            workspaces:delete: Delete workspaces
            workspaces:get: Get workspace details
            workspaces:invite: Invite users to workspace
            workspaces:leave: Leave workspace
            workspaces:list: List workspaces
            workspaces:remove: Remove users from workspace
            workspaces:update: Update workspaces
          tokenUrl: /oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access
            agents:create: Create agents
            agents:delete: Delete agents
            agents:get: Get agent details
            agents:list: List agents
            agents:update: Update agents
            apiKey:list: List API keys
            apiKey:write: Create and delete API keys
            applications:create: Create applications
            applications:delete: Delete applications
            applications:get: Get application details
            applications:list: List applications
            applications:update: Update applications
            configurations:list: List configurations
            customdomains:create: Create custom domains
            customdomains:delete: Delete custom domains
            customdomains:get: Get custom domain details
            customdomains:list: List custom domains
            customdomains:update: Update custom domains
            functions:create: Create functions
            functions:delete: Delete functions
            functions:get: Get function details
            functions:list: List functions
            functions:update: Update functions
            integrations:create: Create integrations
            integrations:list: List integrations
            invitations:list: List invitations
            jobs:create: Create jobs
            jobs:delete: Delete jobs
            jobs:get: Get job details
            jobs:list: List jobs
            jobs:update: Update jobs
            locations:list: List locations
            mcphub:list: List MCP hub resources
            models:create: Create models
            models:delete: Delete models
            models:get: Get model details
            models:list: List models
            models:update: Update models
            policies:create: Create policies
            policies:delete: Delete policies
            policies:get: Get policy details
            policies:list: List policies
            policies:update: Update policies
            sandboxes:control: Control sandbox operations
            sandboxes:create: Create sandboxes
            sandboxes:delete: Delete sandboxes
            sandboxes:get: Get sandbox details
            sandboxes:list: List sandboxes
            sandboxes:update: Update sandboxes
            sandboxhub:list: List sandbox hub resources
            secrets:create: Create secrets
            secrets:delete: Delete secrets
            secrets:list: List secrets
            templates:get: Get template details
            templates:list: List templates
            volumeTemplates:create: Create volume templates
            volumeTemplates:delete: Delete volume templates
            volumeTemplates:get: Get volume template details
            volumeTemplates:list: List volume templates
            volumeTemplates:upsert: Create or update volume templates
            volumes:create: Create volumes
            volumes:delete: Delete volumes
            volumes:get: Get volume details
            volumes:list: List volumes
            workspaces:accept: Accept workspace invitation
            workspaces:create: Create workspaces
            workspaces:decline: Decline workspace invitation
            workspaces:delete: Delete workspaces
            workspaces:get: Get workspace details
            workspaces:invite: Invite users to workspace
            workspaces:leave: Leave workspace
            workspaces:list: List workspaces
            workspaces:remove: Remove users from workspace
            workspaces:update: Update workspaces
          tokenUrl: /oauth/token
      type: oauth2
info:
  title: Blaxel Control Plane
  version: 0.0.1
openapi: 3.0.3
paths:
  /agents:
    get:
      description: Returns AI agents deployed in the workspace. Each agent includes
        its deployment status, runtime configuration, and global inference endpoint
        URL. Starting with API version 2026-04-28 the response is wrapped in `{data,
        meta}` and supports cursor pagination via the `cursor` and `limit` query parameters;
        older versions keep returning a bare array with all agents.
      operationId: ListAgents
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      - $ref: '#/components/parameters/PaginationAnchor'
      - $ref: '#/components/parameters/ExternalIdFilter'
      - $ref: '#/components/parameters/ListingStatus'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentList'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to list agents
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - agents:list
      - ApiKeyAuth: []
      summary: List all agents
      tags:
      - agents
    post:
      description: Creates a new AI agent deployment from your code. The agent will
        be built and deployed as a serverless auto-scaling endpoint. Use the Blaxel
        CLI 'bl deploy' for a simpler deployment experience.
      operationId: CreateAgent
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Agent'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid agent configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to create agents
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - Agent with this name already exists
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - agents:create
      - ApiKeyAuth: []
      summary: Create agent
      tags:
      - agents
  /agents/{agentName}:
    delete:
      description: Permanently deletes an agent and all its deployment history. The
        agent's inference endpoint will immediately stop responding. This action cannot
        be undone.
      operationId: DeleteAgent
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to delete this agent
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Agent does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - agents:delete
      - ApiKeyAuth: []
      summary: Delete agent
      tags:
      - agents
    get:
      description: Returns detailed information about an agent including its current
        deployment status, configuration, events history, and inference endpoint URL.
      operationId: GetAgent
      parameters:
      - description: Show secret values (requires workspace admin role)
        in: query
        name: show_secrets
        required: false
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to view this agent
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Agent does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - agents:get
      - ApiKeyAuth: []
      summary: Get agent
      tags:
      - agents
    parameters:
    - description: Unique name identifier of the agent
      in: path
      name: agentName
      required: true
      schema:
        type: string
    put:
      description: Updates an agent's configuration and triggers a new deployment.
        Changes to runtime settings, environment variables, or scaling parameters
        will be applied on the next deployment.
      operationId: UpdateAgent
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Agent'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid agent configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to update this agent
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Agent does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - agents:update
      - ApiKeyAuth: []
      summary: Update agent
      tags:
      - agents
  /agents/{agentName}/revisions:
    get:
      operationId: ListAgentRevisions
      parameters:
      - description: Name of the agent
        in: path
        name: agentName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RevisionMetadata'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - agents:list
      - ApiKeyAuth: []
      summary: List all agent revisions
      tags:
      - agents
  /applications:
    get:
      description: Returns applications deployed in the workspace. Each application
        includes its deployment status, runtime configuration, and endpoint URL. Starting
        with API version 2026-04-28 the response is wrapped in `{data, meta}` and
        supports cursor pagination via the `cursor` and `limit` query parameters;
        older versions keep returning a bare array with all applications.
      operationId: ListApplications
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      - $ref: '#/components/parameters/PaginationAnchor'
      - $ref: '#/components/parameters/ListingStatus'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationList'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to list applications
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - applications:list
      - ApiKeyAuth: []
      summary: List all applications
      tags:
      - applications
    post:
      description: Creates a new application deployment. Applications are long-running
        workloads that default to public access and mk3 generation.
      operationId: CreateApplication
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid application configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to create applications
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - Application with this name already exists
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - applications:create
      - ApiKeyAuth: []
      summary: Create application
      tags:
      - applications
  /applications/{applicationName}:
    delete:
      description: Permanently deletes an application and all its deployment history.
        The application endpoint will immediately stop responding. This action cannot
        be undone.
      operationId: DeleteApplication
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to delete this application
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Application does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - applications:delete
      - ApiKeyAuth: []
      summary: Delete application
      tags:
      - applications
    get:
      description: Returns detailed information about an application including its
        current deployment status, configuration, events history, and endpoint URL.
      operationId: GetApplication
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to view this application
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Application does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - applications:get
      - ApiKeyAuth: []
      summary: Get application
      tags:
      - applications
    parameters:
    - description: Unique name identifier of the application
      in: path
      name: applicationName
      required: true
      schema:
        type: string
    put:
      description: Updates an application's configuration and triggers a new deployment.
        Changes to runtime settings, environment variables, or scaling parameters
        will be applied on the next deployment.
      operationId: UpdateApplication
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid application configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to update this application
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Application does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - applications:update
      - ApiKeyAuth: []
      summary: Update application
      tags:
      - applications
  /applications/{applicationName}/customdomains:
    post:
      description: Creates a new custom domain scoped to a specific application. After
        creation, you must configure DNS records and verify domain ownership before
        it becomes active.
      operationId: CreateApplicationCustomDomain
      parameters:
      - description: Name of the application
        in: path
        name: applicationName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDomain'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomain'
          description: successful operation
      security:
      - OAuth2:
        - customdomains:create
      - ApiKeyAuth: []
      summary: Create application custom domain
      tags:
      - customdomains
      x-stainless-ignore: true
  /applications/{applicationName}/revisions:
    get:
      operationId: ListApplicationRevisions
      parameters:
      - description: Name of the application
        in: path
        name: applicationName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AppRevision'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - applications:list
      - ApiKeyAuth: []
      summary: List all application revisions
      tags:
      - applications
  /changelog:
    get:
      description: Returns the latest public changelog entries for the controlplane
        UI. The origin response is intentionally not cached in memory; CloudFront
        caches this endpoint according to the Cache-Control header.
      operationId: GetChangelog
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangelogResponse'
          description: Latest changelog entries
      security: []
      summary: Get latest changelog entries
      tags:
      - changelog
      x-stainless-ignore: true
  /configuration:
    get:
      description: Returns global platform configuration including available regions,
        countries, continents, and private locations for deployment policies.
      operationId: GetConfiguration
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'
          description: Configuration of the control plane
      security:
      - OAuth2:
        - configurations:list
      - ApiKeyAuth: []
      summary: Get platform configuration
      tags:
      - configurations
      x-stainless-ignore: true
  /customdomains:
    get:
      description: Returns all custom domains configured in the workspace. Custom
        domains allow serving preview deployments under your own domain (e.g., preview.yourdomain.com).
      operationId: ListCustomDomains
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/CustomDomain'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - customdomains:list
      - ApiKeyAuth: []
      summary: List custom domains
      tags:
      - customdomains
      x-stainless-ignore: true
    post:
      description: Creates a new custom domain for preview deployments. After creation,
        you must configure DNS records and verify domain ownership before it becomes
        active.
      operationId: CreateCustomDomain
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDomain'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomain'
          description: successful operation
      security:
      - OAuth2:
        - customdomains:create
      - ApiKeyAuth: []
      summary: Create custom domain
      tags:
      - customdomains
      x-stainless-ignore: true
  /customdomains/{domainName}:
    delete:
      operationId: DeleteCustomDomain
      parameters:
      - description: Name of the custom domain
        in: path
        name: domainName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomain'
          description: successful operation
      security:
      - OAuth2:
        - customdomains:delete
      - ApiKeyAuth: []
      summary: Delete custom domain
      tags:
      - customdomains
      x-stainless-ignore: true
    get:
      operationId: GetCustomDomain
      parameters:
      - description: Name of the custom domain
        in: path
        name: domainName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomain'
          description: successful operation
      security:
      - OAuth2:
        - customdomains:get
      - ApiKeyAuth: []
      summary: Get custom domain
      tags:
      - customdomains
      x-stainless-ignore: true
    put:
      operationId: UpdateCustomDomain
      parameters:
      - description: Name of the custom domain
        in: path
        name: domainName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDomain'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomain'
          description: successful operation
      security:
      - OAuth2:
        - customdomains:update
      - ApiKeyAuth: []
      summary: Update custom domain
      tags:
      - customdomains
      x-stainless-ignore: true
  /customdomains/{domainName}/share:
    get:
      description: Returns the list of workspaces (and/or the account) that a custom
        domain is currently shared with.
      operationId: ListCustomDomainShares
      parameters:
      - description: Name of the custom domain
        in: path
        name: domainName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/CustomDomainShareTarget'
                type: array
          description: successful operation
        "404":
          description: custom domain not found
      security:
      - OAuth2:
        - customdomains:get
      - ApiKeyAuth: []
      summary: List custom domain shares
      tags:
      - customdomains
      x-stainless-ignore: true
    post:
      description: Shares a verified custom domain with another workspace of the same
        account by copying the domain record; the ACM certificate and CloudFront tenant
        stay with the owner and are reused (not re-provisioned). Use targetWorkspace
        "account" to make the domain usable by every workspace of the account. Cross-account
        sharing is not supported.
      operationId: ShareCustomDomain
      parameters:
      - description: Name of the custom domain
        in: path
        name: domainName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                targetWorkspace:
                  description: Name of the workspace to share the domain with, or
                    "account" to share with every workspace of the account.
                  type: string
              required:
              - targetWorkspace
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomain'
          description: successful operation
        "400":
          description: invalid request
        "404":
          description: custom domain not found
        "409":
          description: custom domain conflict in target workspace
      security:
      - OAuth2:
        - customdomains:update
      - ApiKeyAuth: []
      summary: Share a custom domain
      tags:
      - customdomains
      x-stainless-ignore: true
  /customdomains/{domainName}/share/{targetWorkspace}:
    delete:
      description: Revokes sharing of a custom domain with a target workspace (or
        the account when targetWorkspace is "account"). Removes the shared copy /
        clears the account-global marker; the owner's domain is not affected.
      operationId: UnshareCustomDomain
      parameters:
      - description: Name of the custom domain
        in: path
        name: domainName
        required: true
        schema:
          type: string
      - description: Name of the target workspace, or "account" for an account-wide
          share.
        in: path
        name: targetWorkspace
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomain'
          description: successful operation
        "404":
          description: custom domain or share not found
      security:
      - OAuth2:
        - customdomains:update
      - ApiKeyAuth: []
      summary: Unshare a custom domain
      tags:
      - customdomains
      x-stainless-ignore: true
  /customdomains/{domainName}/verify:
    post:
      operationId: VerifyCustomDomain
      parameters:
      - description: Name of the custom domain
        in: path
        name: domainName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDomain'
          description: successful operation
      security:
      - OAuth2:
        - customdomains:update
      - ApiKeyAuth: []
      summary: Verify custom domain
      tags:
      - customdomains
      x-stainless-ignore: true
  /drives:
    get:
      description: Returns all drives in the workspace. Drives provide persistent
        storage that can be attached to agents, functions, and sandboxes. Starting
        with API version 2026-04-28, the response wraps items in `{data, meta}` and
        supports cursor pagination via the `cursor` and `limit` query parameters;
        older versions keep returning a bare array with all drives.
      operationId: ListDrives
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      - $ref: '#/components/parameters/PaginationAnchor'
      - description: Filter drives by external ID. When set, only drives matching
          this caller-owned identifier are returned.
        in: query
        name: externalId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/ListingStatus'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriveList'
          description: successful operation
        "401":
          description: Unauthorized
      security:
      - OAuth2:
        - drives:list
      - ApiKeyAuth: []
      summary: List drives
      tags:
      - drives
    post:
      description: Creates a new drive in the workspace. Drives can be buckets and
        can be mounted at runtime to sandboxes.
      operationId: CreateDrive
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Drive'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Drive'
          description: successful operation
        "401":
          description: Unauthorized
      security:
      - OAuth2:
        - drives:create
      - ApiKeyAuth: []
      summary: Create a drive
      tags:
      - drives
  /drives/{driveName}:
    delete:
      description: Starts the deletion of a drive. The drive is marked DELETING and
        its storage is wiped asynchronously; the drive disappears from listings once
        the cleanup completes.
      operationId: DeleteDrive
      parameters:
      - in: path
        name: driveName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  message:
                    example: Drive deletion started
                    type: string
                  name:
                    example: my-drive
                    type: string
                  status:
                    example: DELETING
                    type: string
                type: object
          description: successful operation
        "401":
          description: Unauthorized
        "404":
          description: Drive not found
      security:
      - OAuth2:
        - drives:delete
      - ApiKeyAuth: []
      summary: Delete a drive
      tags:
      - drives
    get:
      description: Retrieves details of a specific drive including its status and
        events.
      operationId: GetDrive
      parameters:
      - in: path
        name: driveName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Drive'
          description: successful operation
        "401":
          description: Unauthorized
        "404":
          description: Drive not found
      security:
      - OAuth2:
        - drives:get
      - ApiKeyAuth: []
      summary: Get a drive
      tags:
      - drives
    put:
      description: Updates an existing drive. Metadata fields like displayName and
        labels can be changed. Size can be set if not already configured.
      operationId: UpdateDrive
      parameters:
      - in: path
        name: driveName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Drive'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Drive'
          description: successful operation
        "401":
          description: Unauthorized
        "404":
          description: Drive not found
      security:
      - OAuth2:
        - drives:create
      - ApiKeyAuth: []
      summary: Update a drive
      tags:
      - drives
  /drives/{driveName}/access-token:
    post:
      description: Issues a short-lived JWT access token scoped to a specific drive.
        The token can be used as Bearer authentication for direct S3 operations against
        the drive's bucket.
      operationId: CreateDriveAccessToken
      parameters:
      - in: path
        name: driveName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: number
                  token_type:
                    example: Bearer
                    type: string
                type: object
          description: successful operation
        "401":
          description: Unauthorized
        "403":
          description: Drives feature not enabled
        "404":
          description: Drive not found
      security:
      - OAuth2:
        - drives:get
      - ApiKeyAuth: []
      summary: Create drive access token
      tags:
      - drives
  /drives/{driveName}/folders:
    delete:
      description: Deletes a folder and all its contents directly in drive storage.
        This is synchronous and non-atomic. If it times out or fails, some contents
        may have been deleted; retry the same path to finish cleanup. An absent folder
        succeeds. The drive root and internal metadata cannot be deleted.
      operationId: DeleteDriveFolder
      parameters:
      - in: path
        name: driveName
        required: true
        schema:
          type: string
      - description: Relative folder path ending in a slash, for example documents/reports/.
        in: query
        name: path
        required: true
        schema:
          maxLength: 1024
          type: string
      responses:
        "204":
          description: Folder and its contents deleted, or folder already absent
        "400":
          description: Invalid folder path
        "401":
          description: Unauthorized
        "403":
          description: Insufficient permissions, protected path, or drives feature
            disabled
        "404":
          description: Drive not found
        "409":
          description: Drive unavailable or requested path is not a folder
        "502":
          description: Storage unavailable or deletion incomplete; retry to finish
            cleanup
        "504":
          description: Deletion timed out and may be partially complete; retry to
            finish cleanup
      security:
      - OAuth2:
        - drives:delete
      - ApiKeyAuth: []
      summary: Delete a folder and its contents
      tags:
      - drives
  /drives/by-external-id/{externalId}:
    get:
      description: Returns a drive matching the given external ID. If no drive is
        found, returns 404.
      operationId: GetDriveByExternalId
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Drive'
          description: successful operation
        "401":
          description: Unauthorized
        "403":
          description: Forbidden - Insufficient permissions to view drives
        "404":
          description: Drive not found
        "500":
          description: Internal server error
      security:
      - OAuth2:
        - drives:get
      - ApiKeyAuth: []
      summary: Get drive by external ID
      tags:
      - drives
    parameters:
    - description: Caller-owned external identifier for the drive
      in: path
      name: externalId
      required: true
      schema:
        type: string
  /drives/jwks.json:
    get:
      description: Returns the JSON Web Key Set containing the Ed25519 public key
        used to verify drive access tokens. Other S3-compatible storage can use this
        endpoint to validate Bearer tokens.
      operationId: GetDriveJWKS
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  keys:
                    items:
                      type: object
                    type: array
                type: object
          description: successful operation
      security: []
      summary: Get drive token JWKS
      tags:
      - drives
  /egressgateways:
    get:
      operationId: ListAllEgressGateways
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/EgressGateway'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - egressgateways:list
      - ApiKeyAuth: []
      summary: List all egress gateways across all VPCs in the workspace
      tags:
      - vpcs
  /egressgateways/usage:
    get:
      description: Returns the inverse map (gateway → sandbox names) for the workspace.
        Used by the egress-IPs UI to render attachment counts without fetching the
        sandboxes listing full client-side.
      operationId: GetEgressGatewayUsage
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EgressGatewayUsage'
          description: successful operation
      security:
      - OAuth2:
        - egressgateways:list
        - sandboxes:list
      - ApiKeyAuth: []
      summary: Egress gateway sandbox attachments
      tags:
      - vpcs
  /egressips:
    get:
      operationId: ListAllEgressIPs
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/EgressIP'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - egressips:list
      - ApiKeyAuth: []
      summary: List all egress IPs across all VPCs and gateways in the workspace
      tags:
      - vpcs
  /features:
    get:
      description: Returns only the feature flags that are currently enabled for the
        specified workspace. Disabled features are not included to prevent information
        leakage.
      operationId: getWorkspaceFeatures
      responses:
        "200":
          content:
            application/json:
              example:
                features:
                  advanced_metrics: true
                  gpu_deployments: true
                  new_ui: true
              schema:
                properties:
                  features:
                    additionalProperties:
                      type: boolean
                    description: Map of feature keys to enabled state (always true).
                      Disabled features are omitted.
                    type: object
                type: object
          description: Map of enabled features (only enabled flags are included)
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - You do not have access to this workspace
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Workspace does not exist
      security:
      - OAuth2:
        - featureFlags:list
      - ApiKeyAuth: []
      summary: Get enabled features for workspace
      tags:
      - workspaces
      x-stainless-ignore: true
  /features/{featureKey}:
    get:
      description: Evaluates a specific feature flag for the workspace with full details
        including variant and payload. Useful for testing and debugging feature flag
        targeting.
      operationId: testFeatureFlag
      parameters:
      - description: Name of the feature flag
        in: path
        name: featureKey
        required: true
        schema:
          type: string
      - description: Account ID to check feature flags for. When provided, evaluates
          the feature flag at the account level instead of the workspace level.
        in: query
        name: account
        required: false
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              example:
                enabled: true
                evaluatedAt: "2026-02-09T10:30:00Z"
                featureKey: gpu_deployments
                payload:
                  allowed_types:
                  - A100
                  - H100
                  max_gpus: 4
                variant: variant_a
              schema:
                properties:
                  enabled:
                    type: boolean
                  evaluatedAt:
                    format: date-time
                    type: string
                  featureKey:
                    type: string
                  payload:
                    type: object
                  variant:
                    type: string
                type: object
          description: Feature flag evaluation result with details
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - You do not have access to this feature flag
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Feature flag not found
      security:
      - OAuth2:
        - featureFlags:get
      - ApiKeyAuth: []
      summary: Retrieve feature flag evaluation for workspace
      tags:
      - featureFlags
      x-stainless-ignore: true
  /functions:
    get:
      description: Returns MCP server functions deployed in the workspace. Each function
        includes its deployment status, transport protocol (websocket or http-stream),
        and endpoint URL. Starting with API version 2026-04-28 the response is wrapped
        in `{data, meta}` and supports cursor pagination via the `cursor` and `limit`
        query parameters; older versions keep returning a bare array with all functions.
      operationId: ListFunctions
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      - $ref: '#/components/parameters/PaginationAnchor'
      - $ref: '#/components/parameters/ExternalIdFilter'
      - $ref: '#/components/parameters/ListingStatus'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionList'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to list functions
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - functions:list
      - ApiKeyAuth: []
      summary: List all MCP servers
      tags:
      - functions
    post:
      description: Creates a new MCP server function deployment. The function will
        expose tools via the Model Context Protocol that can be used by AI agents.
        Supports streamable HTTP transport.
      operationId: CreateFunction
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Function'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid function configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to create functions
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - Function with this name already exists
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - functions:create
      - ApiKeyAuth: []
      summary: Create MCP server
      tags:
      - functions
  /functions/{functionName}:
    delete:
      description: Permanently deletes an MCP server function and all its deployment
        history. Any agents using this function's tools will no longer be able to
        invoke them.
      operationId: DeleteFunction
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to delete this function
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Function does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - functions:delete
      - ApiKeyAuth: []
      summary: Delete MCP server
      tags:
      - functions
    get:
      description: Returns detailed information about an MCP server function including
        its deployment status, available tools, transport configuration, and endpoint
        URL.
      operationId: GetFunction
      parameters:
      - description: Show secret values (requires workspace admin role)
        in: query
        name: show_secrets
        required: false
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to view this function
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Function does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - functions:get
      - ApiKeyAuth: []
      summary: Get MCP server
      tags:
      - functions
    parameters:
    - description: Unique name identifier of the MCP server function
      in: path
      name: functionName
      required: true
      schema:
        type: string
    put:
      description: Updates an MCP server function's configuration and triggers a new
        deployment. Changes to runtime settings, integrations, or transport protocol
        will be applied on the next deployment.
      operationId: UpdateFunction
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Function'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Function'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid function configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to update this function
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Function does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - functions:update
      - ApiKeyAuth: []
      summary: Update MCP server
      tags:
      - functions
  /functions/{functionName}/revisions:
    get:
      description: Returns revisions for a function by name.
      operationId: ListFunctionRevisions
      parameters:
      - description: Name of the function
        in: path
        name: functionName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RevisionMetadata'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - functions:get
      - ApiKeyAuth: []
      summary: List function revisions
      tags:
      - functions
  /images:
    delete:
      description: Cleans up unused container images in the workspace registry. Only
        removes images that are not currently referenced by any active agent, function,
        sandbox, or job deployment.
      operationId: CleanupImages
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    description: Number of images deleted
                    type: integer
                  message:
                    description: Result message
                    type: string
                type: object
          description: successful operation
      security:
      - OAuth2:
        - images:delete
      - ApiKeyAuth: []
      summary: Cleanup unused container images
      tags:
      - images
    get:
      description: Returns paginated image summaries starting with API version 2026-09-22.
        Older versions return a bare array including all tags.
      operationId: ListImages
      parameters:
      - in: query
        name: cursor
        schema:
          type: string
      - in: query
        name: limit
        schema:
          default: 50
          maximum: 100
          type: integer
      - in: query
        name: sort
        schema:
          type: string
      - description: Case-sensitive name prefix. Selects name order.
        in: query
        name: q
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/ImageSummary'
                    type: array
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                required:
                - data
                - meta
                type: object
          description: successful operation
      security:
      - OAuth2:
        - images:list
      - ApiKeyAuth: []
      summary: List container images
      tags:
      - images
    post:
      description: Builds or imports a container image without creating a deployment.
        Provide a registry image reference to download and convert an existing image,
        or omit image to receive a presigned URL for uploading source code. Registry
        imports can specify memoryMb and volumeMb for the import worker. These settings
        do not change the resources of workloads using the image.
      operationId: CreateImage
      requestBody:
        content:
          application/json:
            schema:
              properties:
                dockerConfig:
                  description: Docker configuration JSON containing credentials for
                    the source registry.
                  type: string
                generation:
                  description: Runtime generation (e.g., mk3). Defaults to mk3 if
                    not specified.
                  type: string
                image:
                  description: A pre-built Docker image reference (e.g., docker.io/myorg/myimage:latest).
                    References with a registry hostname start an asynchronous import
                    that downloads and converts the image for the resource runtime.
                  type: string
                memoryMb:
                  description: Memory for the registry import worker in MiB. Only
                    supported when image is a registry reference. When omitted, the
                    platform default is used.
                  example: 16384
                  maximum: 32768
                  minimum: 1
                  type: integer
                name:
                  description: Name of the image to build
                  type: string
                resourceType:
                  description: Resource type (agent, function, sandbox, job)
                  type: string
                tag:
                  description: Tag for the imported image. Only supported when image
                    is a registry reference. When omitted, a tag is derived from the
                    build inputs. Tags are immutable, so a tag that already exists
                    is rejected. latest, pending and failed are reserved.
                  example: v1.2.0
                  maxLength: 32
                  pattern: ^[A-Za-z0-9_][A-Za-z0-9_.-]{0,31}$
                  type: string
                volumeMb:
                  description: Temporary scratch disk for the registry import worker
                    in MiB. Only supported when image is a registry reference. When
                    omitted, the platform default is used. Set to 0 to use memory-backed
                    scratch. Positive values are not supported for HIPAA workspaces.
                  example: 32768
                  maximum: 131072
                  minimum: 0
                  type: integer
              required:
              - resourceType
              - name
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  image:
                    description: The registered image reference (only present when
                      image was provided in request)
                    type: string
                  message:
                    description: Status message
                    type: string
                  name:
                    description: Name of the image
                    type: string
                  resourceType:
                    description: Resource type
                    type: string
                type: object
          description: successful operation
          headers:
            X-Blaxel-Upload-Url:
              description: Presigned URL for uploading source code
              schema:
                type: string
        "400":
          description: invalid request
        "409":
          description: the requested tag already exists
      security:
      - OAuth2:
        - images:create
      - ApiKeyAuth: []
      summary: Build a container image
      tags:
      - images
  /images/{resourceType}/{imageName}:
    delete:
      description: Deletes a container image and all its tags from the workspace registry.
        Will fail if the image is currently in use by an active deployment.
      operationId: DeleteImage
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
          description: successful operation
        "400":
          description: image used
        "404":
          description: image not found
      security:
      - OAuth2:
        - images:delete
      - ApiKeyAuth: []
      summary: Delete container image
      tags:
      - images
    get:
      description: Returns a bounded image summary starting with API version 2026-09-22.
        Older versions return the image with all tags.
      operationId: GetImage
      parameters:
      - description: Owner workspace for an account-shared image.
        in: query
        name: sourceWorkspace
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageSummary'
          description: successful operation
      security:
      - OAuth2:
        - images:get
      - ApiKeyAuth: []
      summary: Get container image
      tags:
      - images
    parameters:
    - description: Resource type (agents, functions, sandboxes, jobs)
      in: path
      name: resourceType
      required: true
      schema:
        type: string
    - description: Name of the container image repository
      in: path
      name: imageName
      required: true
      schema:
        type: string
  /images/{resourceType}/{imageName}/share:
    get:
      description: Returns the list of workspaces that a container image is currently
        shared with.
      operationId: ListImageShares
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ImageShareTarget'
                type: array
          description: successful operation
        "404":
          description: image not found
      security:
      - OAuth2:
        - images:get
      - ApiKeyAuth: []
      summary: List image shares
      tags:
      - images
    parameters:
    - description: Resource type (agents, functions, sandboxes, jobs)
      in: path
      name: resourceType
      required: true
      schema:
        type: string
    - description: Name of the container image repository
      in: path
      name: imageName
      required: true
      schema:
        type: string
    post:
      description: Shares a container image with another workspace by copying the
        metadata record. The underlying storage (S3) data is not duplicated. For same-account
        targets the share is applied immediately. For cross-account targets, a pending
        image share is created and must be explicitly accepted by an admin of the
        target workspace; the correct target account ID must be supplied as an anti-spam
        measure.
      operationId: ShareImage
      requestBody:
        content:
          application/json:
            schema:
              properties:
                targetAccountId:
                  description: Account ID of the target workspace. Required when the
                    target workspace belongs to a different account than the source
                    workspace (anti-spam).
                  type: string
                targetWorkspace:
                  description: Name of the workspace to share the image with
                  type: string
              required:
              - targetWorkspace
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
          description: successful operation (same-account share, applied immediately)
        "202":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingImageShare'
          description: pending approval from target workspace admin
        "400":
          description: invalid request
        "404":
          description: image not found
        "409":
          description: image conflict in target workspace
      security:
      - OAuth2:
        - images:share
      - ApiKeyAuth: []
      summary: Share a container image
      tags:
      - images
  /images/{resourceType}/{imageName}/share/{targetWorkspace}:
    delete:
      description: Revokes sharing of a container image with a target workspace. Removes
        the metadata copy from the target workspace. The source image is not affected.
      operationId: UnshareImage
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
          description: successful operation
        "404":
          description: image or share not found
      security:
      - OAuth2:
        - images:share
      - ApiKeyAuth: []
      summary: Unshare a container image
      tags:
      - images
    parameters:
    - description: Resource type (agents, functions, sandboxes, jobs)
      in: path
      name: resourceType
      required: true
      schema:
        type: string
    - description: Name of the container image repository
      in: path
      name: imageName
      required: true
      schema:
        type: string
    - description: Name of the target workspace to revoke sharing from
      in: path
      name: targetWorkspace
      required: true
      schema:
        type: string
  /images/{resourceType}/{imageName}/tags:
    get:
      description: Returns a bounded page of image tags. Search by prefix or exact
        name. Tags are ordered by name only. Send Blaxel-Version 2026-09-22 with image
        catalog requests.
      operationId: ListImageTags
      parameters:
      - in: query
        name: cursor
        schema:
          type: string
      - in: query
        name: limit
        schema:
          default: 50
          maximum: 100
          type: integer
      - description: Order by tag name. Creation-time sorting is not supported.
        in: query
        name: sort
        schema:
          default: name:asc
          enum:
          - name:asc
          - name:desc
          type: string
      - description: Case-sensitive name prefix. Selects name order.
        in: query
        name: q
        schema:
          type: string
      - description: Exact tag name, mutually exclusive with q.
        in: query
        name: name
        schema:
          type: string
      - description: Owner workspace for an account-shared image.
        in: query
        name: sourceWorkspace
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/ImageTag'
                    type: array
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                required:
                - data
                - meta
                type: object
          description: A page of tags
      security:
      - OAuth2:
        - images:get
      - ApiKeyAuth: []
      summary: List image tags
      tags:
      - images
    parameters:
    - in: path
      name: resourceType
      required: true
      schema:
        type: string
    - in: path
      name: imageName
      required: true
      schema:
        type: string
  /images/{resourceType}/{imageName}/tags/{tagName}:
    delete:
      description: Deletes a specific tag from a container image. The underlying image
        layers are kept if other tags reference them. Will fail if the tag is currently
        in use.
      operationId: DeleteImageTag
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
          description: successful operation
        "204":
          description: Tag deleted (API version 2026-09-22 and later).
        "400":
          description: tag is in use
        "404":
          description: image or tag not found
      security:
      - OAuth2:
        - images:delete
      - ApiKeyAuth: []
      summary: Delete container image tag
      tags:
      - images
    parameters:
    - description: Resource type (agents, functions, sandboxes, jobs)
      in: path
      name: resourceType
      required: true
      schema:
        type: string
    - description: Name of the container image repository
      in: path
      name: imageName
      required: true
      schema:
        type: string
    - description: Tag name to delete (e.g., latest, v1.0.0)
      in: path
      name: tagName
      required: true
      schema:
        type: string
  /integrations/{integrationName}:
    get:
      description: Returns metadata about an integration provider including available
        endpoints, authentication methods, and supported models or features.
      operationId: GetIntegration
      parameters:
      - description: Name of the integration
        in: path
        name: integrationName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
          description: successful operation
      security:
      - OAuth2:
        - integrations:list
      - ApiKeyAuth: []
      summary: Get integration provider info
      tags:
      - integrations
  /integrations/connections:
    get:
      description: Returns all configured integration connections in the workspace.
        Each connection stores credentials and settings for an external service (LLM
        provider, API, database).
      operationId: ListIntegrationConnections
      parameters:
      - $ref: '#/components/parameters/ExternalIdFilter'
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/IntegrationConnection'
                type: array
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to list integration connections
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - integrations:list
      - ApiKeyAuth: []
      summary: List integration connections
      tags:
      - integrations
    post:
      description: Creates a new integration connection with credentials for an external
        service. The connection can then be used by models, functions, and other resources
        to authenticate with the service.
      operationId: CreateIntegrationConnection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationConnection'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationConnection'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid integration configuration or unsupported
            integration type
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to create integration
            connections
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - Integration connection with this name already exists
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - integrations:create
      - ApiKeyAuth: []
      summary: Create integration connection
      tags:
      - integrations
  /integrations/connections/{connectionName}:
    delete:
      description: Permanently deletes an integration connection. Any resources using
        this connection will lose access to the external service.
      operationId: DeleteIntegrationConnection
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationConnection'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to delete this connection
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Integration connection does not exist
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - Integration connection is in use by models or functions
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - integrations:delete
      - ApiKeyAuth: []
      summary: Delete integration connection
      tags:
      - integrations
    get:
      description: Returns detailed information about an integration connection including
        its provider type, configuration (secrets are masked), and usage status.
      operationId: GetIntegrationConnection
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationConnection'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to view this connection
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Integration connection does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - integrations:get
      - ApiKeyAuth: []
      summary: Get integration connection
      tags:
      - integrations
    parameters:
    - description: Unique name identifier of the integration connection
      in: path
      name: connectionName
      required: true
      schema:
        type: string
    put:
      description: Updates an integration connection's configuration or credentials.
        Changes take effect immediately for all resources using this connection.
      operationId: UpdateIntegrationConnection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationConnection'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationConnection'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid integration configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to update this connection
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Integration connection does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - integrations:update
      - ApiKeyAuth: []
      summary: Update integration connection
      tags:
      - integrations
  /integrations/connections/{connectionName}/endpointConfigurations:
    get:
      description: Returns a list of all endpoint configurations for a model.
      operationId: GetIntegrationConnectionModelEndpointConfigurations
      parameters:
      - description: Name of the connection
        in: path
        name: connectionName
        required: true
        schema:
          type: string
      responses:
        "200":
          description: successful operation
      security:
      - OAuth2:
        - integrations:list
      - ApiKeyAuth: []
      summary: Get integration connection model endpoint configurations
      tags:
      - integrations
      x-stainless-ignore: true
  /integrations/connections/{connectionName}/models:
    get:
      description: Returns a list of all models for an integration connection.
      operationId: ListIntegrationConnectionModels
      parameters:
      - description: Name of the connection
        in: path
        name: connectionName
        required: true
        schema:
          type: string
      responses:
        "200":
          description: successful operation
      security:
      - OAuth2:
        - integrations:list
      - ApiKeyAuth: []
      summary: List integration connection models
      tags:
      - integrations
      x-stainless-ignore: true
  /integrations/connections/{connectionName}/models/{modelId}:
    get:
      description: Returns a model for an integration connection by ID.
      operationId: GetIntegrationConnectionModel
      parameters:
      - description: Name of the connection
        in: path
        name: connectionName
        required: true
        schema:
          type: string
      - description: Model ID
        in: path
        name: modelId
        required: true
        schema:
          type: string
      responses:
        "200":
          description: successful operation
      security:
      - OAuth2:
        - integrations:get
      - ApiKeyAuth: []
      summary: Get integration connection model
      tags:
      - integrations
      x-stainless-ignore: true
  /jobs:
    get:
      description: Returns batch job definitions in the workspace. Each job can be
        triggered to run multiple parallel tasks with configurable concurrency and
        retry settings. Starting with API version 2026-04-28 the response is wrapped
        in `{data, meta}` and supports cursor pagination via the `cursor` and `limit`
        query parameters; older versions keep returning a bare array with all jobs.
      operationId: ListJobs
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      - $ref: '#/components/parameters/PaginationAnchor'
      - $ref: '#/components/parameters/ExternalIdFilter'
      - $ref: '#/components/parameters/ListingStatus'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobList'
          description: successful operation
      security:
      - OAuth2:
        - jobs:list
      - ApiKeyAuth: []
      summary: List batch jobs
      tags:
      - jobs
    post:
      description: Creates a new batch job definition for parallel AI task processing.
        Jobs can be triggered via API or scheduled, and support configurable parallelism,
        timeouts, and retry logic.
      operationId: CreateJob
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Job'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
          description: successful operation
      security:
      - OAuth2:
        - jobs:create
      - ApiKeyAuth: []
      summary: Create batch job
      tags:
      - jobs
  /jobs/{jobId}:
    delete:
      description: Permanently deletes a batch job definition and cancels any running
        executions. Historical execution data will be retained for a limited time.
      operationId: DeleteJob
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
          description: successful operation
      security:
      - OAuth2:
        - jobs:delete
      - ApiKeyAuth: []
      summary: Delete batch job
      tags:
      - jobs
    get:
      description: Returns detailed information about a batch job including its runtime
        configuration, execution history, and deployment status.
      operationId: GetJob
      parameters:
      - description: Show secret values (requires workspace admin role)
        in: query
        name: show_secrets
        required: false
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
          description: successful operation
      security:
      - OAuth2:
        - jobs:get
      - ApiKeyAuth: []
      summary: Get batch job
      tags:
      - jobs
    parameters:
    - description: Unique name identifier of the batch job
      in: path
      name: jobId
      required: true
      schema:
        type: string
    put:
      description: Updates a batch job's configuration. Changes affect new executions;
        running executions continue with their original configuration.
      operationId: UpdateJob
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Job'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
          description: successful operation
      security:
      - OAuth2:
        - jobs:update
      - ApiKeyAuth: []
      summary: Update batch job
      tags:
      - jobs
  /jobs/{jobId}/executions:
    get:
      description: Returns executions for a batch job. Starting with API version 2026-04-28
        the response is wrapped in `{data, meta}` and supports cursor pagination via
        the `cursor` and `limit` query parameters; older versions keep the legacy
        offset/limit contract and return a bare array.
      operationId: ListJobExecutions
      parameters:
      - description: Name of the job
        in: path
        name: jobId
        required: true
        schema:
          type: string
      - description: Number of items per page
        in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - description: Page offset (legacy, ignored when Blaxel-Version >= 2026-04-28)
        in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          type: integer
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobExecutionList'
          description: successful operation
        "400":
          description: bad request
        "500":
          description: internal server error
      security:
      - OAuth2:
        - jobs:list
      - ApiKeyAuth: []
      summary: List job executions
      tags:
      - jobs
    post:
      description: Triggers a new execution of the batch job. Each execution runs
        multiple tasks in parallel according to the job's configured concurrency.
        Tasks can be parameterized via the request body.
      operationId: CreateJobExecution
      parameters:
      - description: Name of the job
        in: path
        name: jobId
        required: true
        schema:
          type: string
        x-stainless-param: pathJobId
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobExecutionRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateJobExecutionOutput'
          description: successful operation
        "400":
          description: bad request
        "500":
          description: internal server error
      security:
      - OAuth2:
        - jobs:create
      - ApiKeyAuth: []
      summary: Create job execution
      tags:
      - jobs
  /jobs/{jobId}/executions/{executionId}:
    delete:
      description: Cancels a running job execution. Tasks already in progress will
        complete, but no new tasks will be started. The execution status changes to
        'cancelling' then 'cancelled'.
      operationId: DeleteJobExecution
      parameters:
      - description: Name of the job
        in: path
        name: jobId
        required: true
        schema:
          type: string
      - description: Id of the execution
        in: path
        name: executionId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobExecution'
          description: successful operation
        "400":
          description: bad request
        "404":
          description: execution not found
        "500":
          description: internal server error
      security:
      - OAuth2:
        - jobs:delete
      - ApiKeyAuth: []
      summary: Cancel job execution
      tags:
      - jobs
    get:
      description: Returns detailed information about a specific job execution including
        status, task statistics (success/failure/running counts), and timing information.
      operationId: GetJobExecution
      parameters:
      - description: Name of the job
        in: path
        name: jobId
        required: true
        schema:
          type: string
      - description: Id of the execution
        in: path
        name: executionId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobExecution'
          description: successful operation
        "400":
          description: bad request
        "404":
          description: execution not found
        "500":
          description: internal server error
      security:
      - OAuth2:
        - jobs:get
      - ApiKeyAuth: []
      summary: Get job execution
      tags:
      - jobs
  /jobs/{jobId}/executions/{executionId}/tasks:
    get:
      description: Returns one cursor-paginated page of an execution's tasks. Tasks
        are derived from event history each request; only the in-memory slicing is
        paginated, the events scan still fetches the whole event log behind the scenes.
        Available starting with API version 2026-04-28.
      operationId: ListJobExecutionTasks
      parameters:
      - description: Name of the job
        in: path
        name: jobId
        required: true
        schema:
          type: string
      - description: Execution id
        in: path
        name: executionId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobExecutionTaskList'
          description: successful operation
        "400":
          description: bad request
        "404":
          description: job or execution not found
        "500":
          description: internal server error
      security:
      - OAuth2:
        - jobs:get
      - ApiKeyAuth: []
      summary: List execution tasks
      tags:
      - jobs
  /jobs/{jobId}/revisions:
    get:
      description: Returns revisions for a job by name.
      operationId: ListJobRevisions
      parameters:
      - description: Name of the job
        in: path
        name: jobId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RevisionMetadata'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - jobs:list
      - ApiKeyAuth: []
      summary: List job revisions
      tags:
      - jobs
  /locations:
    get:
      description: Returns all deployment regions with their current availability
        status and supported hardware flavors. Use this to discover where resources
        can be deployed.
      operationId: ListLocations
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/LocationResponse'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - locations:list
      - ApiKeyAuth: []
      summary: List deployment regions
      tags:
      - locations
      x-stainless-ignore: true
  /mcp/hub:
    get:
      description: Returns all pre-built MCP server definitions available in the Blaxel
        Hub. These can be deployed directly to your workspace with pre-configured
        tools and integrations.
      operationId: ListMCPHubDefinitions
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/MCPDefinition'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - mcphub:list
      - ApiKeyAuth: []
      summary: List MCP Hub servers
      tags:
      - mcphub
      x-stainless-ignore: true
  /models:
    get:
      description: Returns model gateway endpoints configured in the workspace. Each
        model represents a proxy to an external LLM provider (OpenAI, Anthropic, etc.)
        with unified access control. Starting with API version 2026-04-28 the response
        is wrapped in `{data, meta}` and supports cursor pagination via the `cursor`
        and `limit` query parameters; older versions keep returning a bare array with
        all models.
      operationId: ListModels
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      - $ref: '#/components/parameters/PaginationAnchor'
      - $ref: '#/components/parameters/ExternalIdFilter'
      - $ref: '#/components/parameters/ListingStatus'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to list models
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - models:list
      - ApiKeyAuth: []
      summary: List model endpoints
      tags:
      - models
    post:
      description: Creates a new model gateway endpoint that proxies requests to an
        external LLM provider. Requires an integration connection with valid API credentials
        for the target provider.
      operationId: CreateModel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Model'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid model configuration or integration connection
            not found
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to create models
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - Model with this name already exists
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - models:create
      - ApiKeyAuth: []
      summary: Create model endpoint
      tags:
      - models
  /models/{modelName}:
    delete:
      description: Permanently deletes a model gateway endpoint. Any agents or applications
        using this endpoint will need to be updated to use a different model.
      operationId: DeleteModel
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to delete this model
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Model does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - models:delete
      - ApiKeyAuth: []
      summary: Delete model endpoint
      tags:
      - models
    get:
      description: Returns detailed information about a model gateway endpoint including
        its provider configuration, integration connection, and usage status.
      operationId: GetModel
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to view this model
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Model does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - models:get
      - ApiKeyAuth: []
      summary: Get model endpoint
      tags:
      - models
    parameters:
    - description: Unique name identifier of the model endpoint
      in: path
      name: modelName
      required: true
      schema:
        type: string
    put:
      description: Updates a model gateway endpoint's configuration. Changes to provider
        settings or integration connection take effect immediately.
      operationId: UpdateModel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Model'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid model configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to update this model
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Model does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - models:update
      - ApiKeyAuth: []
      summary: Update model endpoint
      tags:
      - models
  /models/{modelName}/revisions:
    get:
      description: Returns revisions for a model by name.
      operationId: ListModelRevisions
      parameters:
      - description: Name of the model
        in: path
        name: modelName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RevisionMetadata'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - models:list
      - ApiKeyAuth: []
      summary: List model revisions
      tags:
      - models
  /pending-image-shares:
    get:
      description: Lists pending cross-account image shares targeting the caller's
        workspace (incoming) or originating from it (outgoing). Expired shares are
        cleaned up opportunistically.
      operationId: ListPendingImageShares
      parameters:
      - description: 'Direction of pending shares: "incoming" (default) or "outgoing"'
        in: query
        name: direction
        required: false
        schema:
          enum:
          - incoming
          - outgoing
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PendingImageShareRender'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - images:share
      - ApiKeyAuth: []
      summary: List pending image shares
      tags:
      - images
  /pending-image-shares/{pendingShareId}/accept:
    parameters:
    - description: ID of the pending image share
      in: path
      name: pendingShareId
      required: true
      schema:
        type: string
    post:
      description: Accepts a pending cross-account image share and copies the image
        metadata to the target workspace. Caller must be an admin of the target workspace.
      operationId: AcceptImageShare
      parameters:
      - description: When true, overwrite conflicting tags in the target workspace
          instead of returning 409.
        in: query
        name: force
        required: false
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
          description: successful operation
        "403":
          description: forbidden
        "404":
          description: pending image share not found
        "409":
          description: image conflict in target workspace
        "410":
          description: pending image share expired
      security:
      - OAuth2:
        - images:share
      - ApiKeyAuth: []
      summary: Accept a pending image share
      tags:
      - images
  /pending-image-shares/{pendingShareId}/decline:
    parameters:
    - description: ID of the pending image share
      in: path
      name: pendingShareId
      required: true
      schema:
        type: string
    post:
      description: Declines a pending cross-account image share. Caller must be an
        admin of the target workspace.
      operationId: DeclineImageShare
      responses:
        "204":
          description: successfully declined
        "403":
          description: forbidden
        "404":
          description: pending image share not found
      security:
      - OAuth2:
        - images:share
      - ApiKeyAuth: []
      summary: Decline a pending image share
      tags:
      - images
  /policies:
    get:
      description: Returns governance policies in the workspace. Policies control
        deployment locations, hardware flavors, and token limits for agents, functions,
        and models. Starting with API version 2026-04-28 the response is wrapped in
        `{data, meta}` and supports cursor pagination via the `cursor` and `limit`
        query parameters; older versions keep returning a bare array with all policies.
      operationId: ListPolicies
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      - $ref: '#/components/parameters/PaginationAnchor'
      - $ref: '#/components/parameters/ExternalIdFilter'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyList'
          description: successful operation
      security:
      - OAuth2:
        - policies:list
      - ApiKeyAuth: []
      summary: List governance policies
      tags:
      - policies
    post:
      description: Creates a new governance policy to control where and how resources
        are deployed. Policies can restrict deployment to specific regions, countries,
        or continents for compliance.
      operationId: CreatePolicy
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Policy'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
          description: successful operation
      security:
      - OAuth2:
        - policies:create
      - ApiKeyAuth: []
      summary: Create governance policy
      tags:
      - policies
  /policies/{policyName}:
    delete:
      description: Permanently deletes a governance policy. Resources using this policy
        will need to be updated to use a different policy.
      operationId: DeletePolicy
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
          description: successful operation
      security:
      - OAuth2:
        - policies:delete
      - ApiKeyAuth: []
      summary: Delete governance policy
      tags:
      - policies
    get:
      description: Returns detailed information about a governance policy including
        its type (location, flavor, or maxToken), restrictions, and which resource
        types it applies to.
      operationId: GetPolicy
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
          description: successful operation
      security:
      - OAuth2:
        - policies:get
      - ApiKeyAuth: []
      summary: Get governance policy
      tags:
      - policies
    parameters:
    - description: Unique name identifier of the policy
      in: path
      name: policyName
      required: true
      schema:
        type: string
    put:
      description: Updates a governance policy's restrictions. Changes take effect
        on the next deployment of resources using this policy.
      operationId: UpdatePolicy
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Policy'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
          description: successful operation
      security:
      - OAuth2:
        - policies:update
      - ApiKeyAuth: []
      summary: Update governance policy
      tags:
      - policies
  /policies/{policyName}/usages:
    get:
      description: Returns the names of every resource (agent, function, model, sandbox,
        job) currently referencing the given policy. Replaces the client-side fan-out
        the policies UI used to do over the listings.
      operationId: GetPolicyUsages
      parameters:
      - description: Unique name identifier of the policy
        in: path
        name: policyName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyUsages'
          description: successful operation
      security:
      - OAuth2:
        - policies:get
        - agents:list
        - functions:list
        - models:list
        - sandboxes:list
        - jobs:list
      - ApiKeyAuth: []
      summary: List resources using a policy
      tags:
      - policies
  /publicIps:
    get:
      description: Returns a list of all public ips used in Blaxel..
      operationId: ListPublicIps
      parameters:
      - description: Filter by region name (only returns mk3 region data)
        in: query
        name: region
        required: false
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicIps'
          description: successful operation
      security:
      - OAuth2:
        - admin
      - ApiKeyAuth: []
      summary: List public ips
      tags:
      - publicIps:list
  /sandbox/hub:
    get:
      description: Returns all pre-built sandbox templates available in the Blaxel
        Hub. These include popular development environments with pre-installed tools
        and frameworks.
      operationId: ListSandboxHubDefinitions
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SandboxDefinition'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - sandboxhub:list
      - ApiKeyAuth: []
      summary: List Sandbox Hub templates
      tags:
      - sandboxhub
  /sandboxes:
    get:
      description: Returns sandboxes in the workspace. Each sandbox includes its configuration,
        status, and endpoint URL. Terminated sandboxes are hidden by default; pass
        `showTerminated=true` to include them. Starting with API version 2026-04-28
        the response is wrapped in `{data, meta}` and supports cursor pagination via
        the `cursor` and `limit` query parameters; older versions keep returning a
        bare array of all sandboxes.
      operationId: ListSandboxes
      parameters:
      - description: If true, include terminated sandboxes in the response. Defaults
          to false.
        in: query
        name: showTerminated
        required: false
        schema:
          default: false
          type: boolean
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      - $ref: '#/components/parameters/PaginationAnchor'
      - description: Comma-separated list of statuses to filter on (e.g. `DEPLOYED,FAILED`).
          When set it takes precedence over `showTerminated`. Unknown values are rejected
          with a 400. Bound into the cursor fingerprint.
        example: DEPLOYED,FAILED
        in: query
        name: status
        required: false
        schema:
          type: string
      - description: Filter sandboxes by external ID. When set, only sandboxes matching
          this caller-owned identifier are returned.
        in: query
        name: externalId
        required: false
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxList'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to list sandboxes
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:list
      - ApiKeyAuth: []
      summary: List sandboxes
      tags:
      - compute
    post:
      description: Creates a new sandbox VM for secure AI code execution. Sandboxes
        automatically scale to zero when idle and resume instantly, preserving memory
        state including running processes and filesystem.
      operationId: CreateSandbox
      parameters:
      - description: If true, return the existing sandbox instead of a 409 when one
          with this name is alive. A name held by a FAILED or TERMINATED sandbox is
          reused, and a deletion or a concurrent creation still in flight is waited
          for (with backoff) so the response is the sandbox, not a conflict to retry.
        in: query
        name: createIfNotExist
        required: false
        schema:
          default: false
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sandbox'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxError'
          description: Bad request - Invalid sandbox configuration (e.g., invalid
            region, image not found)
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxError'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxError'
          description: Forbidden - Insufficient permissions to create sandboxes
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxError'
          description: Conflict - Sandbox with this name already exists
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxError'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:create
      - ApiKeyAuth: []
      summary: Create sandbox
      tags:
      - compute
      x-amazon-apigateway-integration:
        ref: '#/components/x-amazon-apigateway-integrations/albapi-noauth'
      x-blaxel-authorizer-disabled: true
  /sandboxes/{sandboxName}:
    delete:
      description: Permanently deletes a sandbox and all its data. If no volumes are
        attached, this guarantees zero data retention (ZDR). This action cannot be
        undone.
      operationId: DeleteSandbox
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to delete this sandbox
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Sandbox does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:delete
      - ApiKeyAuth: []
      summary: Delete sandbox
      tags:
      - compute
    get:
      description: Returns detailed information about a sandbox including its configuration,
        attached volumes, lifecycle policies, and API endpoint URL.
      operationId: GetSandbox
      parameters:
      - description: Show secret values (requires workspace admin role)
        in: query
        name: show_secrets
        required: false
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to view this sandbox
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Sandbox does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: Get sandbox
      tags:
      - compute
    parameters:
    - description: Unique name identifier of the sandbox
      in: path
      name: sandboxName
      required: true
      schema:
        type: string
    put:
      description: Updates a sandbox's configuration. Note that certain changes (like
        image or memory) may reset the sandbox state. Use lifecycle policies to control
        automatic cleanup.
      operationId: UpdateSandbox
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sandbox'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid sandbox configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to update this sandbox
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Sandbox does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:update
      - ApiKeyAuth: []
      summary: Update sandbox
      tags:
      - compute
  /sandboxes/{sandboxName}/archive:
    post:
      description: Archives a sandbox. The changes its filesystem accumulated over
        its image are exported to the archive store, then the sandbox is shut down
        while its definition is kept, so it can be recreated later with the same disk.
        Memory and running processes are not preserved, processes are started again
        from their configuration when the sandbox is unarchived.
      operationId: ArchiveSandbox
      parameters:
      - description: Name of the sandbox to archive
        in: path
        name: sandboxName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
          description: Sandbox archived successfully
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to archive this sandbox
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Sandbox does not exist
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - The sandbox is already archived or is not running
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:update
      - ApiKeyAuth: []
      summary: Archive sandbox
      tags:
      - compute
  /sandboxes/{sandboxName}/fork:
    post:
      description: Forks a sandbox into a new sandbox or application. When forking
        to a sandbox, the target must not already exist (409 if it does). When forking
        to an application, a new revision is added if the app already exists, or a
        new application is created. With no snapshotId, a fork to a sandbox copies
        the source sandbox's live state directly and no snapshot is persisted, while
        a fork to an application takes a snapshot its revision then references. This
        is a WIP endpoint — the full implementation depends on the execution plane.
      operationId: ForkSandbox
      parameters:
      - description: Name of the sandbox to fork
        in: path
        name: sandboxName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxForkRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxForkResponse'
          description: Fork created successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid fork parameters
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Source sandbox does not exist
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - Target sandbox already exists (only for type sandbox)
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:create
      - ApiKeyAuth: []
      summary: Fork sandbox
      tags:
      - compute
  /sandboxes/{sandboxName}/previews:
    get:
      description: Returns a list of Sandbox Previews in the workspace.
      operationId: ListSandboxPreviews
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Preview'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: List Sandbox Previews
      tags:
      - compute
    parameters:
    - description: Name of the Sandbox
      in: path
      name: sandboxName
      required: true
      schema:
        type: string
    post:
      description: Create a preview
      operationId: CreateSandboxPreview
      parameters:
      - description: Force creation by replacing conflicting previews that use the
          same custom domain prefix URL
        in: query
        name: force
        required: false
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Preview'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Preview'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:create
      - ApiKeyAuth: []
      summary: Create Sandbox Preview
      tags:
      - compute
  /sandboxes/{sandboxName}/previews/{previewName}:
    delete:
      description: Deletes a Sandbox Preview by name.
      operationId: DeleteSandboxPreview
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Preview'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:delete
      - ApiKeyAuth: []
      summary: Delete Sandbox Preview
      tags:
      - compute
    get:
      description: Returns a Sandbox Preview by name.
      operationId: GetSandboxPreview
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Preview'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: Get Sandbox Preview
      tags:
      - compute
    parameters:
    - description: Name of the Sandbox
      in: path
      name: sandboxName
      required: true
      schema:
        type: string
    - description: Name of the Preview
      in: path
      name: previewName
      required: true
      schema:
        type: string
    put:
      description: Updates a Sandbox Preview by name.
      operationId: UpdateSandboxPreview
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Preview'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Preview'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:update
      - ApiKeyAuth: []
      summary: Update Sandbox Preview
      tags:
      - compute
  /sandboxes/{sandboxName}/previews/{previewName}/tokens:
    get:
      description: Gets tokens for a Sandbox Preview.
      operationId: ListSandboxPreviewTokens
      parameters:
      - description: Name of the Sandbox
        in: path
        name: sandboxName
        required: true
        schema:
          type: string
      - description: Name of the Preview
        in: path
        name: previewName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PreviewToken'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: Get tokens for Sandbox Preview
      tags:
      - compute
    post:
      description: Creates a token for a Sandbox Preview.
      operationId: CreateSandboxPreviewToken
      parameters:
      - description: Name of the Sandbox
        in: path
        name: sandboxName
        required: true
        schema:
          type: string
      - description: Name of the Preview
        in: path
        name: previewName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewToken'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewToken'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:update
      - ApiKeyAuth: []
      summary: Create token for Sandbox Preview
      tags:
      - compute
  /sandboxes/{sandboxName}/previews/{previewName}/tokens/{tokenName}:
    delete:
      description: Deletes a token for a Sandbox Preview by name.
      operationId: DeleteSandboxPreviewToken
      parameters:
      - description: Name of the Sandbox
        in: path
        name: sandboxName
        required: true
        schema:
          type: string
      - description: Name of the Preview
        in: path
        name: previewName
        required: true
        schema:
          type: string
      - description: Name of the Token
        in: path
        name: tokenName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Success message
                    type: string
                type: object
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:delete
      - ApiKeyAuth: []
      summary: Delete token for Sandbox Preview
      tags:
      - compute
  /sandboxes/{sandboxName}/schedule-executions:
    get:
      description: Returns the execution history of a Sandbox's schedules (across
        all schedules of the sandbox), newest first. Cursor-paginated via the `cursor`
        and `limit` query parameters. Each item records the HTTP status of submitting
        the scheduled command and the process name for log lookup.
      operationId: ListSandboxScheduleExecutions
      parameters:
      - description: Number of items per page
        in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - $ref: '#/components/parameters/PaginationCursor'
      - description: Sort by creation time. Defaults to newest first.
        in: query
        name: sort
        required: false
        schema:
          enum:
          - createdAt:desc
          - createdAt:asc
          type: string
      - $ref: '#/components/parameters/PaginationQuery'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxScheduleExecutionList'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: List Sandbox Schedule Executions
      tags:
      - compute
    parameters:
    - description: Name of the Sandbox
      in: path
      name: sandboxName
      required: true
      schema:
        type: string
  /sandboxes/{sandboxName}/schedules:
    get:
      description: Returns the schedules configured on a Sandbox. Starting with API
        version 2026-04-28 the response is wrapped in `{data, meta}` and supports
        cursor pagination via the `cursor` and `limit` query parameters; older versions
        return a bare array.
      operationId: ListSandboxSchedules
      parameters:
      - description: Number of items per page
        in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - $ref: '#/components/parameters/PaginationCursor'
      - description: Sort by creation time. Defaults to newest first.
        in: query
        name: sort
        required: false
        schema:
          enum:
          - createdAt:desc
          - createdAt:asc
          type: string
      - $ref: '#/components/parameters/PaginationQuery'
      - description: Filter schedules by timing type. Only cron and at are stored
          (sleep resolves to at on creation); any other value is ignored.
        in: query
        name: type
        required: false
        schema:
          enum:
          - cron
          - at
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxScheduleEntryList'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: List Sandbox Schedules
      tags:
      - compute
    parameters:
    - description: Name of the Sandbox
      in: path
      name: sandboxName
      required: true
      schema:
        type: string
    post:
      description: Adds a schedule to a Sandbox.
      operationId: CreateSandboxSchedule
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxScheduleEntry'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxScheduleEntry'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:create
      - ApiKeyAuth: []
      summary: Create Sandbox Schedule
      tags:
      - compute
  /sandboxes/{sandboxName}/schedules/{scheduleId}:
    delete:
      description: Deletes a Sandbox Schedule by id.
      operationId: DeleteSandboxSchedule
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxScheduleEntry'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:delete
      - ApiKeyAuth: []
      summary: Delete Sandbox Schedule
      tags:
      - compute
    get:
      description: Returns a Sandbox Schedule by id.
      operationId: GetSandboxSchedule
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxScheduleEntry'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: Get Sandbox Schedule
      tags:
      - compute
    parameters:
    - description: Name of the Sandbox
      in: path
      name: sandboxName
      required: true
      schema:
        type: string
    - description: Id of the Schedule
      in: path
      name: scheduleId
      required: true
      schema:
        type: string
    put:
      description: Updates a Sandbox Schedule by id.
      operationId: UpdateSandboxSchedule
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxScheduleEntry'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxScheduleEntry'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:update
      - ApiKeyAuth: []
      summary: Update Sandbox Schedule
      tags:
      - compute
  /sandboxes/{sandboxName}/snapshots:
    get:
      description: Returns a list of snapshots for the specified sandbox.
      operationId: ListSandboxSnapshots
      parameters:
      - description: Name of the sandbox
        in: path
        name: sandboxName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxSnapshots'
          description: successful operation
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Sandbox does not exist
      security:
      - OAuth2:
        - sandboxes:list
      - ApiKeyAuth: []
      summary: List sandbox snapshots
      tags:
      - compute
    post:
      description: Creates a point-in-time snapshot of a sandbox. Snapshots capture
        the sandbox state and can be used for forking into new sandboxes or applications.
        This is a WIP endpoint — the full implementation depends on the execution
        plane.
      operationId: CreateSandboxSnapshot
      parameters:
      - description: Name of the sandbox to snapshot
        in: path
        name: sandboxName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxSnapshotRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxSnapshot'
          description: Snapshot created successfully
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Sandbox does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:update
      - ApiKeyAuth: []
      summary: Create sandbox snapshot
      tags:
      - compute
  /sandboxes/{sandboxName}/snapshots/{snapshotId}:
    delete:
      description: Deletes a snapshot of a sandbox, addressed by its name among that
        sandbox's snapshots (or by its ID).
      operationId: DeleteSandboxSnapshot
      parameters:
      - description: Name of the sandbox
        in: path
        name: sandboxName
        required: true
        schema:
          type: string
      - description: Name of the snapshot among the sandbox's snapshots. A snapshot
          ID is also accepted and resolves within the whole workspace, so it reaches
          a snapshot whose source sandbox is another one or was deleted.
        in: path
        name: snapshotId
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Snapshot deleted successfully
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Snapshot does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:delete
      - ApiKeyAuth: []
      summary: Delete sandbox snapshot
      tags:
      - compute
  /sandboxes/{sandboxName}/snapshots/{snapshotId}/restore:
    post:
      description: Restores a sandbox to one of its own snapshots. The running sandbox
        is torn down and rebuilt from the snapshot under the same name and URLs, so
        everything it held since the snapshot was taken is lost unless it was itself
        snapshotted.
      operationId: RestoreSandboxSnapshot
      parameters:
      - description: Name of the sandbox to restore
        in: path
        name: sandboxName
        required: true
        schema:
          type: string
      - description: Name of the snapshot among the sandbox's snapshots. A snapshot
          ID is also accepted and resolves within the whole workspace, so it reaches
          a snapshot whose source sandbox is another one or was deleted.
        in: path
        name: snapshotId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxRestoreResponse'
          description: Sandbox restored successfully
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Sandbox or snapshot does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:update
      - ApiKeyAuth: []
      summary: Restore sandbox from snapshot
      tags:
      - compute
  /sandboxes/{sandboxName}/unarchive:
    post:
      description: Recreates an archived sandbox from its archive. The recreated sandbox
        runs the current generation whatever generation it was archived from, restores
        the archived filesystem before anything starts, and starts the saved processes
        again with new process identifiers.
      operationId: UnarchiveSandbox
      parameters:
      - description: Name of the sandbox to unarchive
        in: path
        name: sandboxName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
          description: Sandbox recreated successfully
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to unarchive this sandbox
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Sandbox does not exist
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - The sandbox is not archived
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:update
      - ApiKeyAuth: []
      summary: Unarchive sandbox
      tags:
      - compute
  /sandboxes/by-external-id/{externalId}:
    get:
      description: Returns the most recent non-terminated sandbox matching the given
        external ID. If no active sandbox is found, returns 404.
      operationId: GetSandboxByExternalId
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to view sandboxes
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - No active sandbox with this external ID
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: Get sandbox by external ID
      tags:
      - compute
    parameters:
    - description: Caller-owned external identifier for the sandbox
      in: path
      name: externalId
      required: true
      schema:
        type: string
  /schedule-executions:
    get:
      description: Returns schedule execution submissions across the workspace, newest
        first by default. Status describes submission acceptance, not process completion.
        since and until are inclusive RFC 3339 bounds on creation time.
      operationId: ListScheduleExecutions
      parameters:
      - description: Number of items per page
        in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - $ref: '#/components/parameters/PaginationCursor'
      - description: Sort by creation time. Defaults to newest first.
        in: query
        name: sort
        required: false
        schema:
          enum:
          - createdAt:desc
          - createdAt:asc
          type: string
      - $ref: '#/components/parameters/PaginationQuery'
      - description: Filter by process submission acceptance status. Historical rows
          without status do not match this filter.
        in: query
        name: status
        required: false
        schema:
          enum:
          - succeeded
          - failed
          type: string
      - description: Filter by sandbox name.
        in: query
        name: sandbox
        required: false
        schema:
          type: string
      - description: Filter by schedule id.
        in: query
        name: schedule
        required: false
        schema:
          type: string
      - description: Inclusive beginning of the createdAt window, as RFC 3339.
        in: query
        name: since
        required: false
        schema:
          format: date-time
          type: string
      - description: Inclusive end of the createdAt window, as RFC 3339.
        in: query
        name: until
        required: false
        schema:
          format: date-time
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxScheduleExecutionList'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: List Workspace Schedule Executions
      tags:
      - compute
  /schedules:
    get:
      description: Returns schedule definitions across the workspace, newest first
        by default.
      operationId: ListSchedules
      parameters:
      - description: Number of items per page
        in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - $ref: '#/components/parameters/PaginationCursor'
      - description: Sort by creation time. Defaults to newest first.
        in: query
        name: sort
        required: false
        schema:
          enum:
          - createdAt:desc
          - createdAt:asc
          type: string
      - $ref: '#/components/parameters/PaginationQuery'
      - description: Filter by sandbox name.
        in: query
        name: sandbox
        required: false
        schema:
          type: string
      - description: Filter schedules by stored timing type. sleep resolves to at
          before persistence.
        in: query
        name: type
        required: false
        schema:
          enum:
          - cron
          - at
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxScheduleEntryList'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: List Workspace Schedules
      tags:
      - compute
  /schedules/metrics:
    get:
      description: Returns active sandbox and scheduling metrics for a UTC minute
        window. since is inclusive and until is exclusive. The default window is the
        last 24 hours and the maximum is 7 days. Execution status describes submission
        acceptance, not process completion. Execution totals begin accumulating when
        metrics collection is enabled and can lag recent firings briefly.
      operationId: GetSandboxScheduleMetrics
      parameters:
      - description: Inclusive beginning of the metrics window, as RFC 3339. Normalized
          down to a UTC minute, must be within the last 7 days, and defaults to 24
          hours before until.
        in: query
        name: since
        required: false
        schema:
          format: date-time
          type: string
      - description: Exclusive end of the metrics window, as RFC 3339. Normalized
          down to a UTC minute and defaults to the current minute.
        in: query
        name: until
        required: false
        schema:
          format: date-time
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxScheduleMetrics'
          description: successful operation
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: Get Sandbox Scheduling Metrics
      tags:
      - compute
  /secrets:
    delete:
      description: Deletes a secret by name (query parameter) from the workspace.
      operationId: DeleteSecretByQuery
      parameters:
      - description: Name of the secret
        in: query
        name: name
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
          description: successful operation
      security:
      - OAuth2:
        - secrets:delete
      - ApiKeyAuth: []
      summary: Delete secret by query
      tags:
      - secrets
      x-stainless-ignore: true
    get:
      description: Lists the secrets of the workspace. Values are write-only and never
        returned.
      operationId: ListSecrets
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Secret'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - secrets:list
      - ApiKeyAuth: []
      summary: List secrets
      tags:
      - secrets
    post:
      description: Creates or updates a secret by name. Each call stores a new immutable
        version; the latest version is the one resolved by the proxy.
      operationId: UpsertSecret
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Secret'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
          description: successful operation
      security:
      - OAuth2:
        - secrets:create
      - ApiKeyAuth: []
      summary: Upsert secret
      tags:
      - secrets
  /secrets/{secretName}:
    delete:
      description: Deletes a secret and all its versions from the workspace.
      operationId: DeleteSecret
      parameters:
      - description: Name of the secret
        in: path
        name: secretName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
          description: successful operation
      security:
      - OAuth2:
        - secrets:delete
      - ApiKeyAuth: []
      summary: Delete secret
      tags:
      - secrets
  /service_accounts:
    get:
      description: Returns all service accounts in the workspace. Service accounts
        are machine identities for external systems to authenticate with Blaxel via
        OAuth or API keys.
      operationId: GetWorkspaceServiceAccounts
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  properties:
                    client_id:
                      description: Service account client ID
                      type: string
                    created_at:
                      description: Creation timestamp
                      type: string
                    description:
                      description: Service account description
                      type: string
                    name:
                      description: Service account name
                      type: string
                    role:
                      description: Role of the service account in the workspace
                      type: string
                    updated_at:
                      description: Last update timestamp
                      type: string
                  type: object
                type: array
          description: successful operation
      security:
      - OAuth2:
        - workspaces:get
      - ApiKeyAuth: []
      summary: List service accounts
      tags:
      - service_accounts
      x-stainless-ignore: true
    post:
      description: Creates a new service account for machine-to-machine authentication.
        Returns client ID and secret (secret is only shown once at creation). Use
        these credentials for OAuth client_credentials flow.
      operationId: CreateWorkspaceServiceAccount
      requestBody:
        content:
          application/json:
            schema:
              properties:
                description:
                  description: Service account description
                  type: string
                name:
                  description: Service account name
                  type: string
                role:
                  description: Role of the service account in the workspace. Defaults
                    to admin on creation; unchanged on update when omitted.
                  enum:
                  - viewer
                  - member
                  - admin
                  type: string
              required:
              - name
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  client_id:
                    description: Service account client ID
                    type: string
                  client_secret:
                    description: Service account client secret (only returned on creation)
                    type: string
                  created_at:
                    description: Creation timestamp
                    type: string
                  description:
                    description: Service account description
                    type: string
                  name:
                    description: Service account name
                    type: string
                  role:
                    description: Role of the service account in the workspace
                    type: string
                  updated_at:
                    description: Last update timestamp
                    type: string
                type: object
          description: successful operation
      security:
      - OAuth2:
        - workspaces:update
      - ApiKeyAuth: []
      summary: Create service account
      tags:
      - service_accounts
      x-stainless-ignore: true
  /service_accounts/{clientId}:
    delete:
      description: Permanently deletes a service account and invalidates all its credentials.
        Any systems using this service account will lose access immediately.
      operationId: DeleteWorkspaceServiceAccount
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  client_id:
                    description: Service account client ID
                    type: string
                  created_at:
                    description: Creation timestamp
                    type: string
                  description:
                    description: Service account description
                    type: string
                  name:
                    description: Service account name
                    type: string
                  updated_at:
                    description: Last update timestamp
                    type: string
                type: object
          description: successful operation
      security:
      - OAuth2:
        - workspaces:update
      - ApiKeyAuth: []
      summary: Delete service account
      tags:
      - service_accounts
      x-stainless-ignore: true
    put:
      description: Updates a service account's name or description. Credentials (client
        ID/secret) cannot be changed.
      operationId: UpdateWorkspaceServiceAccount
      parameters:
      - description: Client ID
        in: path
        name: clientId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                description:
                  description: Service account description
                  type: string
                name:
                  description: Service account name
                  type: string
                role:
                  description: Role of the service account in the workspace. Defaults
                    to admin on creation; unchanged on update when omitted.
                  enum:
                  - viewer
                  - member
                  - admin
                  type: string
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  client_id:
                    description: Service account client ID
                    type: string
                  created_at:
                    description: Creation timestamp
                    type: string
                  description:
                    description: Service account description
                    type: string
                  name:
                    description: Service account name
                    type: string
                  role:
                    description: Role of the service account in the workspace
                    type: string
                  updated_at:
                    description: Last update timestamp
                    type: string
                type: object
          description: successful operation
      security:
      - OAuth2:
        - workspaces:update
      - ApiKeyAuth: []
      summary: Update service account
      tags:
      - service_accounts
      x-stainless-ignore: true
  /service_accounts/{clientId}/api_keys:
    get:
      description: Returns all long-lived API keys created for a service account.
        API keys provide an alternative to OAuth for simpler authentication scenarios.
      operationId: ListApiKeysForServiceAccount
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ApiKey'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - apiKey:list
      - ApiKeyAuth: []
      summary: List service account API keys
      tags:
      - service_accounts
      x-stainless-ignore: true
    parameters:
    - description: Service account client ID
      in: path
      name: clientId
      required: true
      schema:
        type: string
    post:
      description: Creates a new long-lived API key for a service account. The full
        key value is only returned once at creation. API keys can have optional expiration
        dates.
      operationId: CreateApiKeyForServiceAccount
      requestBody:
        content:
          application/json:
            schema:
              properties:
                expires_in:
                  description: Expiration period for the API key. Supports formats
                    like '30d' (30 days), '24h' (24 hours), '1w' (1 week). If not
                    set, the API key never expires.
                  type: string
                name:
                  description: Name for the API key
                  type: string
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
          description: successful operation
      security:
      - OAuth2:
        - apiKey:write
      - ApiKeyAuth: []
      summary: Create service account API key
      tags:
      - service_accounts
      x-stainless-ignore: true
  /service_accounts/{clientId}/api_keys/{apiKeyId}:
    delete:
      description: Revokes an API key for a service account. The key becomes invalid
        immediately and any requests using it will fail authentication.
      operationId: DeleteApiKeyForServiceAccount
      responses:
        "200":
          description: successful operation
      security:
      - OAuth2:
        - apiKey:write
      - ApiKeyAuth: []
      summary: Revoke service account API key
      tags:
      - service_accounts
      x-stainless-ignore: true
    parameters:
    - description: Service account client ID
      in: path
      name: clientId
      required: true
      schema:
        type: string
    - description: API key identifier to revoke
      in: path
      name: apiKeyId
      required: true
      schema:
        type: string
  /snapshots:
    get:
      description: Returns the snapshots of the workspace, newest first by default,
        including the ones whose source object has been deleted. Starting with API
        version 2026-04-28 the response is wrapped in `{data, meta}` and supports
        cursor pagination via the `cursor` and `limit` query parameters; older versions
        keep returning a bare array.
      operationId: ListSnapshots
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      - $ref: '#/components/parameters/PaginationAnchor'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxSnapshotList'
          description: successful operation
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:list
      - ApiKeyAuth: []
      summary: List snapshots
      tags:
      - compute
    post:
      description: Captures a snapshot from a source object. The snapshot belongs
        to the workspace rather than to its source, so it survives the deletion of
        the object it was captured from, and carries what creating a sandbox or an
        application from it needs.
      operationId: CreateSnapshot
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxSnapshotRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxSnapshot'
          description: Snapshot created successfully
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Source object does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:update
      - ApiKeyAuth: []
      summary: Create snapshot
      tags:
      - compute
  /snapshots/{snapshotName}:
    delete:
      description: Deletes a snapshot. There is a single snapshot object, so this
        removes it for the whole workspace, whether or not the object it was captured
        from still exists.
      operationId: DeleteSnapshot
      parameters:
      - description: ID of the snapshot
        in: path
        name: snapshotName
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Snapshot deleted successfully
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Snapshot does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:delete
      - ApiKeyAuth: []
      summary: Delete snapshot
      tags:
      - compute
    get:
      description: Returns a snapshot of the workspace by ID.
      operationId: GetSnapshot
      parameters:
      - description: ID of the snapshot
        in: path
        name: snapshotName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxSnapshot'
          description: successful operation
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Snapshot does not exist
      security:
      - OAuth2:
        - sandboxes:get
      - ApiKeyAuth: []
      summary: Get snapshot
      tags:
      - compute
  /snapshots/{snapshotName}/fork:
    post:
      description: Creates a new sandbox or application from a snapshot. The snapshot
        is enough on its own, so this works after the object it was captured from
        has been deleted.
      operationId: ForkSnapshot
      parameters:
      - description: ID of the snapshot to create the resource from
        in: path
        name: snapshotName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxForkRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxForkResponse'
          description: Resource created successfully
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Snapshot does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - sandboxes:create
      - ApiKeyAuth: []
      summary: Fork snapshot
      tags:
      - compute
  /templates:
    get:
      description: Returns all deployment templates available for creating agents,
        functions, and other resources with pre-configured settings and code.
      operationId: ListTemplates
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Template'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - templates:list
      - ApiKeyAuth: []
      summary: List deployment templates
      tags:
      - templates
  /templates/{templateName}:
    get:
      description: Returns detailed information about a deployment template including
        its configuration, source code reference, and available parameters.
      operationId: GetTemplate
      parameters:
      - description: Name of the template
        in: path
        name: templateName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
          description: successful operation
      security:
      - OAuth2:
        - templates:get
      - ApiKeyAuth: []
      summary: Get template
      tags:
      - templates
  /users:
    get:
      description: Returns all team members in the workspace including their roles
        (admin, member or viewer) and invitation status.
      operationId: ListWorkspaceUsers
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/WorkspaceUser'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - workspaces:list
      - ApiKeyAuth: []
      summary: List workspace team members
      tags:
      - workspaces
      x-stainless-ignore: true
    post:
      description: Invites a new team member to the workspace by email. The invitee
        will receive an email to accept the invitation before gaining access to workspace
        resources.
      operationId: InviteWorkspaceUser
      requestBody:
        content:
          application/json:
            schema:
              properties:
                email:
                  format: email
                  type: string
              type: object
        description: Email of the user to invite
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingInvitation'
          description: successful operation
        "400":
          description: invalid email format
        "404":
          description: workspace not found
      security:
      - OAuth2:
        - workspaces:invite
      - ApiKeyAuth: []
      summary: Invite user to workspace
      tags:
      - workspaces
      x-stainless-ignore: true
  /users/{subOrEmail}:
    delete:
      description: Removes a user from the workspace (or revokes an invitation if
        the user has not accepted the invitation yet).
      operationId: RemoveWorkspaceUser
      parameters:
      - description: Sub or email of the user
        in: path
        name: subOrEmail
        required: true
        schema:
          type: string
      responses:
        "200":
          description: User successfully removed or invitation revoked
        "404":
          description: Workspace or user not found
      security:
      - OAuth2:
        - workspaces:remove
      - ApiKeyAuth: []
      summary: Remove user from workspace or revoke invitation
      tags:
      - workspaces
      x-stainless-ignore: true
    put:
      description: Updates the role of a user in the workspace.
      operationId: UpdateWorkspaceUserRole
      parameters:
      - description: Sub or email of the user
        in: path
        name: subOrEmail
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                role:
                  description: The new role to assign to the user
                  type: string
              required:
              - role
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceUser'
          description: User role updated successfully
        "400":
          description: Invalid role provided
        "404":
          description: Workspace or user not found
      security:
      - OAuth2:
        - workspaces:update
      - ApiKeyAuth: []
      summary: Update user role in workspace
      tags:
      - workspaces
      x-stainless-ignore: true
  /volume_templates:
    get:
      description: Returns all volume templates in the workspace. Volume templates
        contain pre-configured filesystem snapshots that can be used to initialize
        new volumes.
      operationId: ListVolumeTemplates
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/VolumeTemplate'
                type: array
          description: successful operation
      security:
      - OAuth2:
        - volumeTemplates:list
      - ApiKeyAuth: []
      summary: List volume templates
      tags:
      - volumeTemplates
    post:
      description: Creates a new volume template for initializing volumes with pre-configured
        filesystem contents. Optionally returns a presigned URL for uploading the
        template archive.
      operationId: CreateVolumeTemplate
      parameters:
      - description: If true, returns a presigned URL for uploading the template content
        in: query
        name: upload
        schema:
          type: boolean
      - description: Version name for the template version being created
        in: query
        name: version
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VolumeTemplate'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeTemplate'
          description: successful operation
          headers:
            X-Blaxel-Upload-Url:
              description: Presigned URL for uploading template content (if upload=true)
              schema:
                type: string
      security:
      - OAuth2:
        - volumeTemplates:create
      - ApiKeyAuth: []
      summary: Create volume template
      tags:
      - volumeTemplates
  /volume_templates/{volumeTemplateName}:
    delete:
      description: Deletes a volume template by name.
      operationId: DeleteVolumeTemplate
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeTemplate'
          description: successful operation
      security:
      - OAuth2:
        - volumeTemplates:delete
      - ApiKeyAuth: []
      summary: Delete volume template
      tags:
      - volumeTemplates
    get:
      description: Returns a volume template by name.
      operationId: GetVolumeTemplate
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeTemplate'
          description: successful operation
      security:
      - OAuth2:
        - volumeTemplates:get
      - ApiKeyAuth: []
      summary: Get volume template
      tags:
      - volumeTemplates
    parameters:
    - description: Name of the volume template
      in: path
      name: volumeTemplateName
      required: true
      schema:
        type: string
    put:
      description: Creates or updates a volume template.
      operationId: UpdateVolumeTemplate
      parameters:
      - description: If true, returns a presigned URL for uploading the template content
        in: query
        name: upload
        schema:
          type: boolean
      - description: Version name for the template version being created
        in: query
        name: version
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VolumeTemplate'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeTemplate'
          description: successful operation
          headers:
            X-Blaxel-Upload-Url:
              description: Presigned URL for uploading template content (only when
                upload=true)
              schema:
                type: string
      security:
      - OAuth2:
        - volumeTemplates:upsert
      - ApiKeyAuth: []
      summary: Create or update volume template
      tags:
      - volumeTemplates
  /volume_templates/{volumeTemplateName}/versions/{versionName}:
    delete:
      description: Deletes a specific version of a volume template.
      operationId: DeleteVolumeTemplateVersion
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                  template:
                    $ref: '#/components/schemas/VolumeTemplate'
                type: object
          description: Version deleted successfully
        "400":
          description: Cannot delete the only version
        "404":
          description: Version not found
      security:
      - OAuth2:
        - volumeTemplates:delete
      - ApiKeyAuth: []
      summary: Delete volume template version
      tags:
      - volumeTemplates
    parameters:
    - description: Name of the volume template
      in: path
      name: volumeTemplateName
      required: true
      schema:
        type: string
    - description: Name of the version to delete
      in: path
      name: versionName
      required: true
      schema:
        type: string
  /volumes:
    get:
      description: Returns persistent storage volumes in the workspace. Volumes can
        be attached to sandboxes for durable file storage that persists across sessions
        and sandbox deletions. Starting with API version 2026-04-28 the response is
        wrapped in `{data, meta}` and supports cursor pagination via the `cursor`
        and `limit` query parameters; older versions keep returning a bare array of
        volumes.
      operationId: ListVolumes
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/PaginationSort'
      - $ref: '#/components/parameters/PaginationQuery'
      - $ref: '#/components/parameters/PaginationAnchor'
      - description: Filter volumes by external ID. When set, only volumes matching
          this caller-owned identifier are returned.
        in: query
        name: externalId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/ListingStatus'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeList'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to list volumes
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - volumes:list
      - ApiKeyAuth: []
      summary: List persistent volumes
      tags:
      - volumes
    post:
      description: Creates a new persistent storage volume that can be attached to
        sandboxes. Volumes must be created in a specific region and can only attach
        to sandboxes in the same region.
      operationId: CreateVolume
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Volume'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid volume configuration (e.g., invalid region)
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to create volumes
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - Volume with this name already exists
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - volumes:create
      - ApiKeyAuth: []
      summary: Create persistent volume
      tags:
      - volumes
  /volumes/{volumeName}:
    delete:
      description: Permanently deletes a volume and all its data. The volume must
        not be attached to any sandbox. This action cannot be undone.
      operationId: DeleteVolume
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to delete this volume
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Volume does not exist
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - Volume is currently attached to a sandbox
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - volumes:delete
      - ApiKeyAuth: []
      summary: Delete persistent volume
      tags:
      - volumes
    get:
      description: Returns detailed information about a volume including its size,
        region, attachment status, and any events history.
      operationId: GetVolume
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to view this volume
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Volume does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - volumes:get
      - ApiKeyAuth: []
      summary: Get persistent volume
      tags:
      - volumes
    parameters:
    - description: Name of the volume
      in: path
      name: volumeName
      required: true
      schema:
        type: string
    put:
      description: Updates a volume.
      operationId: UpdateVolume
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Volume'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
          description: successful operation
      security:
      - OAuth2:
        - volumes:update
      - ApiKeyAuth: []
      summary: Update volume
      tags:
      - volumes
  /volumes/by-external-id/{externalId}:
    get:
      description: Returns an active volume matching the given external ID. If no
        active volume is found, returns 404.
      operationId: GetVolumeByExternalId
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to view volumes
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - No active volume with this external ID
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - volumes:get
      - ApiKeyAuth: []
      summary: Get volume by external ID
      tags:
      - volumes
    parameters:
    - description: Caller-owned external identifier for the volume
      in: path
      name: externalId
      required: true
      schema:
        type: string
  /vpcs:
    get:
      operationId: ListVPCs
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/VPC'
                type: array
          description: successful operation
      summary: List all VPCs in the workspace
      tags:
      - vpcs
    post:
      operationId: CreateVPC
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VPC'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VPC'
          description: successful operation
      summary: Create a VPC for the workspace
      tags:
      - vpcs
  /vpcs/{vpcName}:
    delete:
      operationId: DeleteVPC
      parameters:
      - in: path
        name: vpcName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VPC'
          description: successful operation
      summary: Delete a VPC
      tags:
      - vpcs
    get:
      operationId: GetVPC
      parameters:
      - in: path
        name: vpcName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VPC'
          description: successful operation
      summary: Get a VPC by name
      tags:
      - vpcs
  /vpcs/{vpcName}/egressgateways:
    get:
      operationId: ListEgressGateways
      parameters:
      - in: path
        name: vpcName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/EgressGateway'
                type: array
          description: successful operation
      summary: List egress gateways in a VPC
      tags:
      - vpcs
    post:
      operationId: CreateEgressGateway
      parameters:
      - in: path
        name: vpcName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EgressGateway'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EgressGateway'
          description: successful operation
      summary: Create an egress gateway in a VPC
      tags:
      - vpcs
  /vpcs/{vpcName}/egressgateways/{gatewayName}:
    delete:
      operationId: DeleteEgressGateway
      parameters:
      - in: path
        name: vpcName
        required: true
        schema:
          type: string
      - in: path
        name: gatewayName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EgressGateway'
          description: successful operation
      summary: Delete an egress gateway
      tags:
      - vpcs
    get:
      operationId: GetEgressGateway
      parameters:
      - in: path
        name: vpcName
        required: true
        schema:
          type: string
      - in: path
        name: gatewayName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EgressGateway'
          description: successful operation
      summary: Get an egress gateway by name
      tags:
      - vpcs
  /vpcs/{vpcName}/egressgateways/{gatewayName}/ips:
    get:
      operationId: ListEgressIPs
      parameters:
      - in: path
        name: vpcName
        required: true
        schema:
          type: string
      - in: path
        name: gatewayName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/EgressIP'
                type: array
          description: successful operation
      summary: List egress IPs in a gateway
      tags:
      - vpcs
    post:
      operationId: CreateEgressIP
      parameters:
      - in: path
        name: vpcName
        required: true
        schema:
          type: string
      - in: path
        name: gatewayName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EgressIP'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EgressIP'
          description: successful operation
      summary: Allocate a new egress IP from the gateway
      tags:
      - vpcs
  /vpcs/{vpcName}/egressgateways/{gatewayName}/ips/{ipName}:
    delete:
      operationId: DeleteEgressIP
      parameters:
      - in: path
        name: vpcName
        required: true
        schema:
          type: string
      - in: path
        name: gatewayName
        required: true
        schema:
          type: string
      - in: path
        name: ipName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EgressIP'
          description: successful operation
      summary: Delete an egress IP
      tags:
      - vpcs
    get:
      operationId: GetEgressIP
      parameters:
      - in: path
        name: vpcName
        required: true
        schema:
          type: string
      - in: path
        name: gatewayName
        required: true
        schema:
          type: string
      - in: path
        name: ipName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EgressIP'
          description: successful operation
      summary: Get an egress IP by name
      tags:
      - vpcs
  /workspaces:
    get:
      description: Returns all workspaces the authenticated user has access to. Each
        workspace is a separate tenant with its own resources, team members, and billing.
      operationId: ListWorkspaces
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Workspace'
                type: array
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - workspaces:list
      - ApiKeyAuth: []
      summary: List accessible workspaces
      tags:
      - workspaces
    post:
      description: Creates a new workspace tenant. The authenticated user becomes
        the workspace admin. Requires a linked billing account.
      operationId: CreateWorkspace
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Workspace'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid workspace configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions or no billing account
            linked
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict - Workspace with this name already exists
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - workspaces:create
      - ApiKeyAuth: []
      summary: Create workspace tenant
      tags:
      - workspaces
      x-stainless-ignore: true
  /workspaces/{workspaceName}:
    delete:
      description: Permanently deletes a workspace and ALL its resources (agents,
        functions, sandboxes, volumes, etc.). This action cannot be undone. Only workspace
        admins can delete a workspace.
      operationId: DeleteWorkspace
      parameters:
      - description: Name of the workspace
        in: path
        name: workspaceName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Only workspace admins can delete workspaces
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Workspace does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - workspaces:delete
      - ApiKeyAuth: []
      summary: Delete workspace tenant
      tags:
      - workspaces
      x-stainless-ignore: true
    get:
      description: Returns detailed information about a workspace including its display
        name, account ID, status, and runtime configuration.
      operationId: GetWorkspace
      parameters:
      - description: Name of the workspace
        in: path
        name: workspaceName
        required: true
        schema:
          type: string
      - description: When true, the response includes a resourceCounts map with the
          number of agents, functions, models, sandboxes, policies, jobs, volumes,
          volumetemplates, integrationconnections, previews, customdomains, serviceaccounts
          and images currently in this workspace. Off by default — each count is one
          extra indexed query.
        in: query
        name: countResources
        required: false
        schema:
          default: false
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
          description: successful operation
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - You do not have access to this workspace
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Workspace does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - workspaces:get
      - ApiKeyAuth: []
      summary: Get workspace details
      tags:
      - workspaces
    put:
      description: Updates a workspace's settings such as display name and labels.
        The workspace name cannot be changed after creation.
      operationId: UpdateWorkspace
      parameters:
      - description: name of the workspace
        in: path
        name: workspaceName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Workspace'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
          description: successful operation
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request - Invalid workspace configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized - Invalid or missing authentication credentials
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions to update this workspace
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not found - Workspace does not exist
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
      - OAuth2:
        - workspaces:update
      - ApiKeyAuth: []
      summary: Update workspace
      tags:
      - workspaces
      x-stainless-ignore: true
  /workspaces/{workspaceName}/leave:
    delete:
      description: Leaves a workspace.
      operationId: LeaveWorkspace
      parameters:
      - description: Name of the workspace
        in: path
        name: workspaceName
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
          description: Workspace successfully left
        "404":
          description: Workspace not found
      security:
      - OAuth2:
        - workspaces:leave
      - ApiKeyAuth: []
      summary: Leave workspace
      tags:
      - workspaces
      x-stainless-ignore: true
  /workspaces/availability:
    post:
      description: Check if a workspace is available.
      operationId: CheckWorkspaceAvailability
      parameters:
      - description: When true, return a structured WorkspaceAvailability object with
          a machine-readable reason and human-readable message instead of a bare boolean.
          Defaults to false for backwards compatibility.
        in: query
        name: withReason
        required: false
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
              required:
              - name
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                oneOf:
                - type: boolean
                - $ref: '#/components/schemas/WorkspaceAvailability'
          description: successful operation
      summary: Check workspace availability
      tags:
      - workspaces
      x-stainless-ignore: true
security:
- OAuth2:
  - admin
- ApiKeyAuth: []
servers:
- description: Blaxel Control Plane
  url: https://api.blaxel.ai/v0
- description: Blaxel Inference
  url: https://run.blaxel.ai