Hyperbrowser Images API

openapi: 3.2.0
info:
  title: Hyperbrowser Images API
  version: 1.0.0
servers:
- url: https://api.hyperbrowser.ai
  description: Production server
tags:
- name: Images
paths:
  /api/images:
    get:
      summary: Get list of sandbox images
      tags:
      - Images
      security:
      - ApiKeyAuth: []
      parameters:
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        required: false
        description: Page size (max 100)
        schema:
          type: integer
          default: 20
      - name: source
        in: query
        required: false
        description: Filter by image source. Repeat to include multiple sources.
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - public
            - team
      - name: search
        in: query
        required: false
        description: Search by image name
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of images
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxImageListResponse'
      operationId: getApiImages
      x-operation-id-source: derived
  /api/images/{key}:
    delete:
      summary: Delete sandbox image
      tags:
      - Images
      security:
      - ApiKeyAuth: []
      parameters:
      - name: key
        in: path
        required: true
        description: Team image name or ID. Names resolve to the newest launch-target revision (release_channel unset), including not-yet-uploaded rows. Public images cannot be deleted. In-flight builds, snapshots, and sandbox mappings that still reference the image return 409.
        schema:
          type: string
      responses:
        '200':
          description: Image deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxImageDeleteResponse'
      operationId: deleteApiImagesByKey
      x-operation-id-source: derived
  /api/images/builds:
    post:
      summary: Create an image build
      tags:
      - Images
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImageBuildParams'
      responses:
        '200':
          description: Image build created with a presigned upload target
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateImageBuildResponse'
      operationId: postApiImagesBuilds
      x-operation-id-source: derived
    get:
      summary: Get list of image builds
      tags:
      - Images
      security:
      - ApiKeyAuth: []
      parameters:
      - name: status
        in: query
        required: false
        description: Filter by build status
        schema:
          type: string
          enum:
          - awaiting_upload
          - upload_verified
          - dispatching
          - building
          - verifying
          - completed
          - failed
          - canceled
      - name: limit
        in: query
        required: false
        description: Maximum number of builds to return
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: List of image builds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageBuildListResponse'
      operationId: getApiImagesBuilds
      x-operation-id-source: derived
  /api/images/builds/{buildId}:
    get:
      summary: Get image build by ID
      tags:
      - Images
      security:
      - ApiKeyAuth: []
      parameters:
      - name: buildId
        in: path
        required: true
        description: Image build ID
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Image build details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageBuildResponse'
      operationId: getApiImagesBuildsByBuildId
      x-operation-id-source: derived
  /api/images/builds/{buildId}/complete:
    post:
      summary: Complete an image build upload
      tags:
      - Images
      security:
      - ApiKeyAuth: []
      parameters:
      - name: buildId
        in: path
        required: true
        description: Image build ID
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteImageBuildParams'
      responses:
        '200':
          description: Upload confirmed; build queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageBuildResponse'
      operationId: postApiImagesBuildsByBuildIdComplete
      x-operation-id-source: derived
  /api/images/builds/{buildId}/cancel:
    post:
      summary: Cancel an image build
      tags:
      - Images
      security:
      - ApiKeyAuth: []
      parameters:
      - name: buildId
        in: path
        required: true
        description: Image build ID
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Image build canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageBuildResponse'
      operationId: postApiImagesBuildsByBuildIdCancel
      x-operation-id-source: derived
components:
  schemas:
    CreateImageBuildParams:
      type: object
      properties:
        imageName:
          type: string
          maxLength: 64
          pattern: ^[A-Za-z0-9_-]+$
          description: Name for the resulting image. Letters, numbers, dashes, and underscores only.
        inputSha256:
          type: string
          minLength: 64
          maxLength: 64
          pattern: ^[A-Fa-f0-9]{64}$
          description: SHA-256 of the image archive to upload.
        inputSizeBytes:
          type: integer
          minimum: 1
        inputFormat:
          type: string
          enum:
          - rootfs_export_tar_gz
          default: rootfs_export_tar_gz
          description: Archive format of the input.
        sourcePlatform:
          type: string
          enum:
          - linux/amd64
          default: linux/amd64
          description: Platform of the source image.
        imageConfigUser:
          type: string
          description: Default user from the image config.
        imageInit:
          type: object
          description: Startup defaults to attach to the image.
          properties:
            env:
              type: object
              maxProperties: 128
              description: Environment variables. Keys must match `^[A-Za-z_][A-Za-z0-9_]*$`.
              additionalProperties:
                type: string
                maxLength: 8192
            command:
              type: string
              minLength: 1
              maxLength: 8192
              description: Startup command.
            args:
              type: array
              maxItems: 256
              items:
                type: string
                minLength: 1
                maxLength: 8192
              description: Startup argument vector.
          additionalProperties: false
      required:
      - imageName
      - inputSha256
      - inputSizeBytes
    ImageBuildResponse:
      type: object
      properties:
        build:
          $ref: '#/components/schemas/ImageBuild'
      required:
      - build
    CreateImageBuildResponse:
      type: object
      properties:
        build:
          $ref: '#/components/schemas/ImageBuild'
        upload:
          type: object
          description: Presigned upload target for the image archive.
          properties:
            url:
              type: string
            method:
              type: string
              enum:
              - PUT
            headers:
              type: object
              additionalProperties:
                type: string
            objectKey:
              type: string
            expiresInSeconds:
              type: integer
            maxUploadBytes:
              type: integer
          required:
          - url
          - method
          - headers
          - objectKey
          - expiresInSeconds
          - maxUploadBytes
      required:
      - build
      - upload
    SandboxImageDeleteResponse:
      type: object
      properties:
        deleted:
          type: boolean
        id:
          type: string
          description: Deleted image revision ID.
        imageName:
          type: string
          description: Deleted image name.
        uploaded:
          type: boolean
          description: Whether the deleted revision was uploaded. Delete-by-name can target a not-yet-uploaded revision that list endpoints hide.
      required:
      - deleted
      - id
      - imageName
      - uploaded
    ImageBuild:
      type: object
      properties:
        id:
          type: string
          format: uuid
        imageName:
          type: string
        imageId:
          type:
          - string
          - 'null'
          format: uuid
        status:
          type: string
          enum:
          - awaiting_upload
          - upload_verified
          - dispatching
          - building
          - verifying
          - completed
          - failed
          - canceled
          description: Current image-build lifecycle state.
        inputSha256:
          type:
          - string
          - 'null'
        inputSizeBytes:
          type:
          - integer
          - 'null'
        errorCode:
          type:
          - string
          - 'null'
        errorMessage:
          type:
          - string
          - 'null'
        completedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - imageName
      - status
      - completedAt
      - createdAt
      - updatedAt
    CompleteImageBuildParams:
      type: object
      properties:
        inputSha256:
          type: string
          minLength: 64
          maxLength: 64
          pattern: ^[A-Fa-f0-9]{64}$
        inputSizeBytes:
          type: integer
          minimum: 1
        inputFormat:
          type: string
          enum:
          - rootfs_export_tar_gz
          default: rootfs_export_tar_gz
      required:
      - inputSha256
      - inputSizeBytes
    ImageBuildListResponse:
      type: object
      properties:
        builds:
          type: array
          items:
            $ref: '#/components/schemas/ImageBuild'
      required:
      - builds
    SandboxImageListResponse:
      type: object
      properties:
        images:
          type: array
          items:
            $ref: '#/components/schemas/SandboxImage'
        totalCount:
          type: integer
        page:
          type: integer
        perPage:
          type: integer
      required:
      - images
      - totalCount
      - page
      - perPage
    SandboxImage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        imageName:
          type: string
        namespace:
          type: string
        source:
          type: string
          enum:
          - public
          - team
        imageInit:
          type:
          - object
          - 'null'
          description: Startup configuration derived from the image (entrypoint, env, user).
        uploaded:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - imageName
      - namespace
      - source
      - uploaded
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    X402SessionManagement:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The managementToken from the X402 session purchase response. Valid for 24 hours and scoped to that session; no API key or further payment is required.
x-provenance:
  method: harvested
  publisher: Hyperbrowser
  source: https://www.hyperbrowser.ai/docs/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)