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

# Update Images

> Update one or many logical images: visibility, name/tag, and owner.

Applies up to 100 independent patches; each item names its source image
exactly and may change `visibility`, rename `name`/`tag`, move a personal
image into one of the caller's teams, or promote a personal/team image to
an org-less platform image (platform admins only; platform images are
always PUBLIC).

Renames and owner moves update the whole logical group (container + VM
artifacts and their linked builds) atomically without moving the backing
artifacts: the old reference stops resolving and the new reference
resolves to the same content. An owner move settles storage billing to
the source wallet at the cutover instant and bills the destination
afterwards. Destinations are never overwritten (`destination_exists`).

`dryRun` performs resolution, authorization, collision detection, and
quota projection without writing; a valid request with item-specific
failures still returns 200 with per-item errors.



## OpenAPI

````yaml https://api.primeintellect.ai/openapi.json patch /api/v1/images
openapi: 3.1.0
info:
  title: PI API
  version: 0.1.0
servers:
  - url: https://api.primeintellect.ai
security: []
paths:
  /api/v1/images:
    patch:
      tags:
        - Images
      summary: Update Images
      description: >-
        Update one or many logical images: visibility, name/tag, and owner.


        Applies up to 100 independent patches; each item names its source image

        exactly and may change `visibility`, rename `name`/`tag`, move a
        personal

        image into one of the caller's teams, or promote a personal/team image
        to

        an org-less platform image (platform admins only; platform images are

        always PUBLIC).


        Renames and owner moves update the whole logical group (container + VM

        artifacts and their linked builds) atomically without moving the backing

        artifacts: the old reference stops resolving and the new reference

        resolves to the same content. An owner move settles storage billing to

        the source wallet at the cutover instant and bills the destination

        afterwards. Destinations are never overwritten (`destination_exists`).


        `dryRun` performs resolution, authorization, collision detection, and

        quota projection without writing; a valid request with item-specific

        failures still returns 200 with per-item errors.
      operationId: update_images_api_v1_images_patch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateImagesRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateImagesResponse'
        '401':
          description: Authorization failed
        '422':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - HTTPBearer: []
components:
  schemas:
    UpdateImagesRequest:
      properties:
        mode:
          type: string
          enum:
            - explicit
          const: explicit
          title: Mode
          default: explicit
        dryRun:
          type: boolean
          title: Dryrun
          default: false
        updates:
          items:
            $ref: '#/components/schemas/ImageUpdateItem'
          type: array
          maxItems: 100
          minItems: 1
          title: Updates
          description: Logical-image patches (max 100 per request)
      type: object
      required:
        - updates
      title: UpdateImagesRequest
      description: |-
        Explicit list of independent logical-image patches.

        Every update names its source exactly (structured coordinates or a
        reference); there is no server-side search selection for mutations.
    UpdateImagesResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: True only when every item succeeded
        dryRun:
          type: boolean
          title: Dryrun
        results:
          items:
            $ref: '#/components/schemas/ImageUpdateResult'
          type: array
          title: Results
      type: object
      required:
        - success
        - dryRun
      title: UpdateImagesResponse
      description: Response for both explicit and search update modes.
    ErrorResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
          title: Errors
      type: object
      required:
        - errors
      title: ErrorResponse
    ImageUpdateItem:
      properties:
        source:
          $ref: '#/components/schemas/ImageUpdateSource'
        set:
          $ref: '#/components/schemas/ImageUpdatePatch'
      type: object
      required:
        - source
        - set
      title: ImageUpdateItem
      description: One independent logical-image patch.
    ImageUpdateResult:
      properties:
        source:
          $ref: '#/components/schemas/ImageUpdateSource'
        success:
          type: boolean
          title: Success
        before:
          anyOf:
            - $ref: '#/components/schemas/ImageCoordinateState'
            - type: 'null'
        after:
          anyOf:
            - $ref: '#/components/schemas/ImageCoordinateState'
            - type: 'null'
        error:
          anyOf:
            - $ref: '#/components/schemas/ImageMutationError'
            - type: 'null'
      type: object
      required:
        - source
        - success
      title: ImageUpdateResult
      description: Per-item outcome, in deterministic request order.
    ErrorDetail:
      properties:
        param:
          type: string
          title: Param
        details:
          type: string
          title: Details
      type: object
      required:
        - param
        - details
      title: ErrorDetail
    ImageUpdateSource:
      properties:
        owner:
          anyOf:
            - oneOf:
                - $ref: '#/components/schemas/PersonalImageOwner'
                - $ref: '#/components/schemas/TeamImageOwner'
                - $ref: '#/components/schemas/PlatformImageOwner'
              discriminator:
                propertyName: type
                mapping:
                  personal:
                    $ref: '#/components/schemas/PersonalImageOwner'
                  platform:
                    $ref: '#/components/schemas/PlatformImageOwner'
                  team:
                    $ref: '#/components/schemas/TeamImageOwner'
            - type: 'null'
          title: Owner
        name:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Name
        tag:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Tag
        reference:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Reference
      type: object
      title: ImageUpdateSource
      description: >-
        Source selector for one logical-image update.


        Either the structured coordinate form (``owner`` + ``name`` + ``tag``)
        or

        the ``reference`` form (owner-slug / legacy owner-prefixed / plain

        personal ``name:tag`` reference, resolved with the same rules as the

        delete endpoint). The two forms are mutually exclusive.
    ImageUpdatePatch:
      properties:
        name:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Name
        tag:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Tag
        owner:
          anyOf:
            - oneOf:
                - $ref: '#/components/schemas/PersonalImageOwner'
                - $ref: '#/components/schemas/TeamImageOwner'
                - $ref: '#/components/schemas/PlatformImageOwner'
              discriminator:
                propertyName: type
                mapping:
                  personal:
                    $ref: '#/components/schemas/PersonalImageOwner'
                  platform:
                    $ref: '#/components/schemas/PlatformImageOwner'
                  team:
                    $ref: '#/components/schemas/TeamImageOwner'
            - type: 'null'
          title: Owner
        visibility:
          anyOf:
            - $ref: '#/components/schemas/ImageVisibilityEnum'
            - type: 'null'
      type: object
      title: ImageUpdatePatch
      description: |-
        Partial patch applied to one logical image; omitted fields keep
        their current value. At least one field must be provided.
    ImageCoordinateState:
      properties:
        owner:
          oneOf:
            - $ref: '#/components/schemas/PersonalImageOwner'
            - $ref: '#/components/schemas/TeamImageOwner'
            - $ref: '#/components/schemas/PlatformImageOwner'
          title: Owner
          discriminator:
            propertyName: type
            mapping:
              personal:
                $ref: '#/components/schemas/PersonalImageOwner'
              platform:
                $ref: '#/components/schemas/PlatformImageOwner'
              team:
                $ref: '#/components/schemas/TeamImageOwner'
        name:
          type: string
          title: Name
        tag:
          type: string
          title: Tag
        visibility:
          $ref: '#/components/schemas/ImageVisibilityEnum'
      type: object
      required:
        - owner
        - name
        - tag
        - visibility
      title: ImageCoordinateState
      description: Canonical logical-image coordinate plus effective visibility.
    ImageMutationError:
      properties:
        code:
          $ref: '#/components/schemas/ImageMutationErrorCode'
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - message
      title: ImageMutationError
      description: Stable machine-readable failure for one update item.
    PersonalImageOwner:
      properties:
        type:
          type: string
          enum:
            - personal
          const: personal
          title: Type
          default: personal
      type: object
      title: PersonalImageOwner
      description: The authenticated caller's personal scope.
    TeamImageOwner:
      properties:
        type:
          type: string
          enum:
            - team
          const: team
          title: Type
          default: team
        teamId:
          type: string
          minLength: 1
          title: Teamid
      type: object
      required:
        - teamId
      title: TeamImageOwner
      description: A team scope; the caller's relationship to it is checked per item.
    PlatformImageOwner:
      properties:
        type:
          type: string
          enum:
            - platform
          const: platform
          title: Type
          default: platform
      type: object
      title: PlatformImageOwner
      description: Org-less platform scope (admin-managed, always PUBLIC).
    ImageVisibilityEnum:
      type: string
      enum:
        - PRIVATE
        - PUBLIC
      title: ImageVisibilityEnum
    ImageMutationErrorCode:
      type: string
      enum:
        - image_not_found
        - source_forbidden
        - destination_forbidden
        - destination_exists
        - duplicate_source
        - duplicate_destination
        - active_build
        - invalid_move
        - invalid_name
        - invalid_tag
        - destination_quota_exceeded
        - billing_cutover_failed
        - update_failed
      title: ImageMutationErrorCode
      description: Stable machine-readable per-item failure codes for PATCH /images.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````