> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel an image build

> Cancels a build that is queued or building and returns it. The build stops, and anything waiting on it fails with `image build was cancelled`. Cancelling a build that is already cancelled returns it unchanged. A build that has already finished cannot be cancelled. The request takes no body.



## OpenAPI

````yaml /sailbox-openapi.json post /sailbox-image-builds/{build_id}/cancel
openapi: 3.1.0
info:
  title: Sail Sailbox API
  version: '2026-10-04'
  description: >-
    Create and operate Sailboxes over HTTP. Sailboxes are fast-booting virtual
    machines that you can pause, resume, and checkpoint.


    Run commands, stream files, manage lifecycle and networking, and inspect
    usage. Turning on SSH and building an image still require an SDK or the CLI.
    See the [HTTP API guide](/sailboxes-http-api).
servers:
  - url: https://sailbox-api.sailresearch.com/v1
security:
  - BearerAuth: []
tags:
  - name: Apps
    description: Groups that own Sailboxes. One app per workload.
  - name: Lifecycle
    description: >-
      A Sailbox's whole life: create it, watch it, stop and start it, terminate
      it.
  - name: Checkpoints
    description: Save a Sailbox to start from later, and copy a running one.
  - name: Image builds
    description: >-
      Watch and cancel the image builds your organization starts with an SDK or
      the CLI.
  - name: Exec
    description: Run commands and control their standard input and terminals.
  - name: Files
    description: Stream regular files into and out of a Sailbox.
  - name: Networking
    description: >-
      Publish ports, serve them on hostnames you own, and identify a Sailbox to
      other Sailboxes.
  - name: Secrets
    description: >-
      Organization values that egress policy rules can add to matching requests.
      Sail never returns a stored value.
  - name: Egress policies
    description: >-
      What a Sailbox may connect to, and what happens to the HTTPS requests it
      sends.
  - name: Volumes
    description: >-
      Shared storage that outlives any one Sailbox. Alpha: these endpoints can
      still change.
  - name: SSH access
    description: Certificates for connecting to a Sailbox with `ssh`.
  - name: Usage
    description: Resource usage and spend.
  - name: Identity
    description: Who your API key belongs to.
paths:
  /sailbox-image-builds/{build_id}/cancel:
    post:
      tags:
        - Image builds
      summary: Cancel an image build
      description: >-
        Cancels a build that is queued or building and returns it. The build
        stops, and anything waiting on it fails with `image build was
        cancelled`. Cancelling a build that is already cancelled returns it
        unchanged. A build that has already finished cannot be cancelled. The
        request takes no body.
      operationId: cancelImageBuild
      parameters:
        - name: build_id
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: The build is cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageBuild'
              example:
                build_id: 5e2c9a47-1d8b-4f36-a09e-7c4b2d6f8a13
                image_id: >-
                  sha256:7b1e4a0d93c25f68a1d4f7b0c3e29a5d81f6b4c07e2a9d3f5b8c1e6a04d7f293
                status: cancelled
                architecture: arm64
                created_at: '2026-05-04T17:02:11Z'
                started_at: null
                finished_at: '2026-05-04T17:03:40Z'
                error_message: image build was cancelled
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '400':
          description: >-
            The request was rejected. See the error message for the offending
            field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: memory_limit_mib must be between 16384 and 262144
                  type: invalid_request_error
                  param: null
                  code: null
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '401':
          description: The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: Invalid API key
                  type: authentication_error
                  param: null
                  code: invalid_api_key
        '402':
          description: >-
            The organization is out of credits. The error carries a
            `billing_url` pointing at the page where you add them. Retry once
            you have.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: >-
                    Your API key has been disabled due to insufficient credits.
                    Visit https://app.sailresearch.com/billing to add credits.
                  type: billing_error
                  param: null
                  code: credits_exhausted
                  billing_url: https://app.sailresearch.com/billing
        '403':
          description: The API key is not allowed to perform this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: sailboxes require an organization-scoped API key
                  type: permission_error
                  param: null
                  code: null
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '404':
          description: No image build with that id exists in your organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: image build not found
                  type: not_found_error
                  param: null
                  code: null
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '409':
          description: >-
            The build has already finished, or the `Idempotency-Key` was reused
            for a different request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: image build has already finished
                  type: conflict_error
                  param: null
                  code: null
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '429':
          description: >-
            Too many requests in flight, or the organization is at a limit. A
            `Retry-After` header means the request never started, so retry it
            unchanged after that delay. Without one, the request ran and hit the
            limit `message` names. Some of those clear on their own, such as a
            shortage of public ports; others need you to free something up
            first. Send the request again once the cause is gone.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: >-
                    Too many concurrent requests. Please retry after some of
                    your organization's in-flight requests complete.
                  type: rate_limit_error
                  param: null
                  code: rate_limited
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: failed to fetch sailbox
                  type: server_error
                  param: null
                  code: null
        '503':
          description: >-
            Sail is momentarily unavailable. Retry after the delay in the
            `Retry-After` header when one is present, and with backoff
            otherwise.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: Authentication service unavailable
                  type: server_error
                  param: null
                  code: null
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: >-
        Makes the request retry-safe. Sail remembers the answer it sent under a
        key, including a 400 or a 409, and replays it with `Idempotent-Replayed:
        true` for a retry that repeats the key, the method, the path, and the
        body. Bodies are compared byte for byte. Reusing a key for a different
        request returns 409, so send a corrected request under a new key. A key
        that is blank or only spaces is ignored, and the request runs without
        idempotency.


        Any string of up to 255 bytes works, and characters outside ASCII count
        for more than one. A UUID is a good default. Keys are remembered for at
        least 24 hours and scoped to the API key that sent them.


        A server error, or a failure to record the answer, can leave a key
        unsettled, and creating a Sailbox is where that matters. See [Retrying
        safely](/sailboxes-http-api#retrying-safely).
  schemas:
    ImageBuild:
      type: object
      properties:
        build_id:
          type: string
          description: Id of the build.
        image_id:
          type: string
          description: Id of the image the build produces.
        status:
          type: string
          description: >-
            A build is `queued` while it waits to start, then `building`, and it
            ends as `ready`, `failed`, or `cancelled`. Sail can add statuses
            later, so handle a value you do not recognize.
        architecture:
          type: string
          description: CPU architecture the image is built for.
        created_at:
          type: string
          format: date-time
          description: When the build was requested.
        started_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the build last started running. Null while the build is queued,
            and for a build that never ran.
        finished_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the build became ready, failed, or was cancelled. Null until
            then.
        error_message:
          type:
            - string
            - 'null'
          description: Why the build failed or was cancelled. Null for any other status.
      required:
        - build_id
        - image_id
        - status
        - architecture
        - created_at
        - started_at
        - finished_at
        - error_message
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    ErrorObject:
      type: object
      required:
        - message
        - type
        - param
        - code
      properties:
        message:
          type: string
          description: Human-readable description of what went wrong.
        type:
          type: string
          description: >-
            Error category: `invalid_request_error`, `authentication_error`,
            `permission_error`, `billing_error`, `not_found_error`,
            `conflict_error`, `rate_limit_error`, `quota_exceeded_error`,
            `not_implemented_error`, or `server_error`.
        param:
          oneOf:
            - type: string
            - type: 'null'
          description: >-
            The request field the error refers to, when the error is about one
            field.
        code:
          oneOf:
            - type: string
            - type: integer
            - type: 'null'
          description: >-
            Stable short code for the error, when one applies. Errors relayed
            from the Sailbox runtime carry its status token, for example
            `already_exists` or `failed_precondition` on a 409, which the HTTP
            status alone does not distinguish.
        billing_url:
          type: string
          format: uri
          description: Page where you add credits. Sent with a 402.
      additionalProperties: true
  headers:
    IdempotentReplayed:
      description: >-
        `true` when this response is the stored answer to an earlier request
        that sent the same `Idempotency-Key`. Absent when the request ran for
        the first time.
      schema:
        type: string
        enum:
          - 'true'
    RetryAfter:
      description: >-
        How many seconds to wait before retrying. On a 429 it also means the
        request never started, so the retry can reuse the same
        `Idempotency-Key`.
      schema:
        type: integer
        minimum: 0
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````