---
title: "Update Images"
method: PATCH
path: "/api/v1/images"
tags: ["Images"]
---

# Update Images

`PATCH /api/v1/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.

## Request body

- UpdateImagesRequest — 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.
  - `mode` 'explicit'
  - `dryRun` boolean
  - `updates` ImageUpdateItem[], required — Logical-image patches (max 100 per request)
    - `source` ImageUpdateSource, required — 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.
      - `owner` union
        - PersonalImageOwner — The authenticated caller's personal scope.
          - `type` 'personal'
        - TeamImageOwner — A team scope; the caller's relationship to it is checked per item.
          - `type` 'team'
          - `teamId` string, required
        - PlatformImageOwner — Org-less platform scope (admin-managed, always PUBLIC).
          - `type` 'platform'
      - `name` string, nullable
      - `tag` string, nullable
      - `reference` string, nullable
    - `set` ImageUpdatePatch, required — Partial patch applied to one logical image; omitted fields keep their current value. At least one field must be provided.
      - `name` string, nullable
      - `tag` string, nullable
      - `owner` union
        - PersonalImageOwner — The authenticated caller's personal scope.
          - `type` 'personal'
        - TeamImageOwner — A team scope; the caller's relationship to it is checked per item.
          - `type` 'team'
          - `teamId` string, required
        - PlatformImageOwner — Org-less platform scope (admin-managed, always PUBLIC).
          - `type` 'platform'
      - `visibility` 'PRIVATE' | 'PUBLIC'

## Response `200`

Successful Response

- UpdateImagesResponse — Response for both explicit and search update modes.
  - `success` boolean, required — True only when every item succeeded
  - `dryRun` boolean, required
  - `results` ImageUpdateResult[]
    - `source` ImageUpdateSource, required — 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.
      - `owner` union
        - PersonalImageOwner — The authenticated caller's personal scope.
          - `type` 'personal'
        - TeamImageOwner — A team scope; the caller's relationship to it is checked per item.
          - `type` 'team'
          - `teamId` string, required
        - PlatformImageOwner — Org-less platform scope (admin-managed, always PUBLIC).
          - `type` 'platform'
      - `name` string, nullable
      - `tag` string, nullable
      - `reference` string, nullable
    - `success` boolean, required
    - `before` ImageCoordinateState — Canonical logical-image coordinate plus effective visibility.
      - `owner` union, required
        - PersonalImageOwner — The authenticated caller's personal scope.
          - `type` 'personal'
        - TeamImageOwner — A team scope; the caller's relationship to it is checked per item.
          - `type` 'team'
          - `teamId` string, required
        - PlatformImageOwner — Org-less platform scope (admin-managed, always PUBLIC).
          - `type` 'platform'
      - `name` string, required
      - `tag` string, required
      - `visibility` 'PRIVATE' | 'PUBLIC', required
    - `after` ImageCoordinateState — Canonical logical-image coordinate plus effective visibility.
      - `owner` union, required
        - PersonalImageOwner — The authenticated caller's personal scope.
          - `type` 'personal'
        - TeamImageOwner — A team scope; the caller's relationship to it is checked per item.
          - `type` 'team'
          - `teamId` string, required
        - PlatformImageOwner — Org-less platform scope (admin-managed, always PUBLIC).
          - `type` 'platform'
      - `name` string, required
      - `tag` string, required
      - `visibility` 'PRIVATE' | 'PUBLIC', required
    - `error` ImageMutationError — Stable machine-readable failure for one update item.
      - `code` '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', required — Stable machine-readable per-item failure codes for PATCH /images.
      - `message` string, required

## Other responses

- `401` — Authorization failed
- `422` — Invalid request data

---

[API](https://skmtc.net/primeintellect/apis/pi-api.md) · [All operations](https://skmtc.net/primeintellect/apis/pi-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/primeintellect/pi-api/revisions/3d3868828a78/schema)