---
title: "Push an image to a remote registry"
method: POST
path: "/pushes"
---

# Push an image to a remote registry

`POST /pushes`

## Request

- Base URL: `http://localhost:4973`
- URL: `http://localhost:4973/pushes`
- Auth: HTTP bearer

Creates a push job that exports a hypeman image from the local OCI
cache to a remote registry (e.g. AWS ECR, Docker Hub). Only images in the
ready state can be pushed.

## Request body

- CreatePushRequest
  - `image` string, required: Hypeman image name to push (tag or digest form)
  - `target` string, required: Full remote reference to push to
  - `insecure` boolean: Allow pushing to plain-HTTP registries
  - `credentials` PushCredentials: Docker-style registry credentials borrowed for one image pull or push request. They remain in memory and are never persisted or logged. When omitted or empty, the server's own registry credentials are used. An interrupted credentialed operation must be retried with fresh credentials.
    - `username` string: Registry username
    - `password` string, password: Registry password or access token
    - `registry_token` string, password: Bearer token for an Authorization header

## Response `202`

Push job created

- Push
  - `id` string, required: Push job identifier
  - `image` string, required: Hypeman image name (normalized ref)
  - `digest` string, required: Cached manifest digest being pushed
  - `target` string, required: Remote reference the image is pushed to
  - `status` 'queued' | 'pushing' | 'pushed' | 'failed', required
  - `queue_position` integer, nullable: Position in the push queue
  - `error` string, nullable: Error message
  - `layers` integer: Number of layers pushed
  - `bytes` integer: Total compressed layer bytes pushed
  - `created_at` string, date-time, required
  - `completed_at` string, date-time, nullable

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `404`: Image not found
- `409`: Image exists but is not ready
- `500`: Internal server error

## Changes

- **2026-08-21** `b00eacfe26b2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kernel/apis/hypeman-api/changes/pushes/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)