---
title: "Pull and convert OCI image"
method: POST
path: "/images"
---

# Pull and convert OCI image

`POST /images`

## Request body

- CreateImageRequest
  - `name` string, required — OCI image reference (e.g., docker.io/library/nginx:latest)
  - `platform` string — Target platform as os/arch[/variant] (e.g. "linux/amd64"), matching Docker --platform. Omit for the host platform. Not a fixed enum: the os/arch[/variant] grammar is validated server-side and invalid values return 400 invalid_platform. Only os "linux" with arch amd64 or arm64 is accepted today.
  - `tags` Tags — User-defined key-value tags.

## Response `202`

Image build started (async)

- 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` — Bad request
- `401` — Unauthorized
- `404` — Image not found or requested platform not available
- `429` — Registry rate limit exceeded
- `500` — Internal server error

## Changes

- **2026-06-09** `796cd163e0f1` — 3 info
  - added the new optional request property `platform`
  - added the non-success response with the status `429`
  - added the optional property `platform` to the response with the `202` status
- **2026-03-09** `d3b8f05f7a0f` — 2 warning, 2 info
  - removed the request property `metadata`
  - removed the optional property `metadata` from the response with the `202` status
  - added the new optional request property `tags`
  - added the optional property `tags` to the response with the `202` status
- **2026-03-07** `48572ed07140` — 2 info
  - added the new optional request property `metadata`
  - added the optional property `metadata` to the response with the `202` status

[Change history](https://skmtc.dev/kernel/apis/hypeman-api/changes/images/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-service-production.skmtc.workers.dev/v1/apis/kernel/hypeman-api/revisions/b4642bb950dc/schema)