---
title: "Create or update a local image tag"
method: POST
path: "/images/{name}/tag"
---

# Create or update a local image tag

`POST /images/{name}/tag`

## Request

- Base URL: `http://localhost:4973`
- URL: `http://localhost:4973/images/{name}/tag`
- Auth: HTTP bearer

## Path parameters

- `name` string, required

## Request body

- TagImageRequest
  - `target` string, required: Target OCI image reference with a tag. The local tag points to the source image without pulling it again.

## Response `200`

Image tag created

- Image
  - `name` string, required: Normalized OCI image reference (tag or digest)
  - `digest` string, required: Resolved manifest digest
  - `platform` string: Resolved image platform as os/arch[/variant] (e.g. "linux/amd64")
  - `status` 'pending' | 'pulling' | 'converting' | 'ready' | 'failed', required: Build status
  - `queue_position` integer, nullable: Position in build queue (null if not queued)
  - `error` string, nullable: Error message if status is failed
  - `size_bytes` integer, nullable: Disk size in bytes (null until ready)
  - `entrypoint` string[], nullable: Entrypoint from container metadata
  - `cmd` string[], nullable: CMD from container metadata
  - `env` object: Environment variables from container metadata
  - `tags` Tags: User-defined key-value tags.
  - `working_dir` string, nullable: Working directory from container metadata
  - `created_at` string, date-time, required: Creation timestamp (RFC3339)

## Other responses

- `400`: Invalid source or target image reference
- `401`: Unauthorized
- `404`: Source image not found
- `409`: Source image is not ready
- `500`: Internal server error

## Changes

- **2026-09-01** `ede452fd5380`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kernel/apis/hypeman-api/changes/images/:name/tag/post.md)

---

[API](https://skmtc.dev/kernel/apis/hypeman-api.md) - [All operations](https://skmtc.dev/kernel/apis/hypeman-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kernel/apis/hypeman-api/revisions/befe3f654ef6?raw)