---
title: "Find Container Image"
method: POST
path: "/registries/images/find"
tags: ["ContainerRegistries"]
---

# Find Container Image

`POST /registries/images/find`

## Request

- Base URL: `https://api.bunny.net/mc`
- URL: `https://api.bunny.net/mc/registries/images/find`
- Auth: API key in header `AccessKey`
- TypeScript: <https://skmtc.dev/bunny/apis/magic-containers-api/docs/registries/images/find/post.ts> (a function with typed inputs; its response is checked against the schema)

Parses an image reference like "ghcr.io/owner/app:v1" or "owner/app" and checks whether the image tag exists in the selected registries of the user (only those of the reference's host when it has one). A reference without a tag finds nothing, not even "latest": the image's tags are suggested instead. Returns every registry that has the image tag with its id, hostname, the image namespace, name, tag and digest, and how each searched registry answered: found, not found, unauthorized (its credentials are refused) or unavailable. When none has it, suggests the image's tags from the registries that have the image, and images with a similar name.

## Request body

- FindContainerImageRequest
  - `image` string, required: Image reference in the docker format: [registry/]namespace/name[:tag], e.g. "ghcr.io/owner/app:v1" or "owner/app". Without a registry host all of the user's registries are searched. Without a tag nothing is found, not even "latest": the image's tags are suggested instead.
  - `registryIds` string[], required: The registries to search: ids of the user's registries, or "dockerhub" / "github". At least one is required; ids that are not the user's registries are skipped. With a registry host in the image reference, only the selected registries of that host are searched.

## Response `200`

The registries were searched: every one that has the image tag is listed (none when it was found nowhere), with how each searched registry answered.

- FindContainerImageResponse: Every registry of the user that has the image tag, in the order they were queried (the user's own private registries first, then public and platform ones). Empty when none has it.
  - `items` FoundContainerImage[]
    - `imageNamespace` string, required
    - `imageName` string, required
    - `registryId` string, required
    - `registryHostname` string, required
    - `isPublic` boolean, required
    - `imageTag` string, required
    - `imageDigest` string, required
  - `meta` ListMeta
    - `totalItems` integer
  - `cursor` string, nullable
  - `registries` FindContainerImageRegistryResult[]: How each searched registry answered, in the order they were queried.
    - `registryId` string, required
    - `status` 'found' | 'notFound' | 'unauthorized' | 'unavailable', required
    - `message` string, nullable: Why the registry could not be searched; only for Unauthorized and Unavailable.
  - `suggestions` FindContainerImageSuggestions
    - `sameImageTags` SuggestedContainerImageTags[]: The image with its first tags, from each registry that has the image but not the tag.
      - `registryId` string, required
      - `imageNamespace` string, required
      - `imageName` string, required
      - `tags` string[], required
    - `similarImages` SuggestedContainerImage[]: Other images whose name is like the one asked for, from the registries' search or catalog.
      - `registryId` string, required
      - `imageNamespace` string, required
      - `imageName` string, required

## Other responses

- `400`: The request is invalid, e.g. no registry is selected.
- `401`: User is unauthorized.
- `404`: None of the selected registries is the user's or is for the image host.
- `422`: The image reference is invalid.
- `500`: Unexpected server error.

## Changes

- **2026-11-12** `7bb58a0591b0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bunny/apis/magic-containers-api/changes/registries/images/find/post.md)

---

[API](https://skmtc.dev/bunny/apis/magic-containers-api.md) - [All operations](https://skmtc.dev/bunny/apis/magic-containers-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bunny/apis/magic-containers-api/revisions/7bb58a0591b0?raw)