# Check image

`POST /v1/projects/{project}/images/check`, operation `environments.CheckImage`

Checks an image as the project's environments would pull it: with the registry that covers it, if any, saying its digest and size.

Refused with failed_precondition and a reason when kosem can't pull it: IMAGE_PULL_DENIED, REGISTRY_SIGN_IN_REFUSED, IMAGE_NOT_FOUND or IMAGE_TOO_LARGE; unavailable when its registry can't be reached. A registry that refuses its sign-in needs attention, and one that takes it no longer does.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `project` | path | Yes | `string` | The project's ID. |

## Request body

Content-Type: `application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `image` | `string` | Yes | The image's reference, with a tag or a digest, such as ghcr.io/acme/devbox:2026.10. |

## Responses

### 200

OK

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `access` | `string` | Yes | How kosem pulls it: KOSEM, its own image; PUBLIC, without signing in; REGISTRY, signed in with registry. Values: `KOSEM`, `PUBLIC`, `REGISTRY`. |
| `compressedBytes` | `integer (int64)` | Yes | The size of the linux/amd64 image's layers and config, compressed, as its registry sends them; 0 for kosem's own image. |
| `digest` | `string` | Yes | The digest of the manifest the reference names now, an index's for an image of several platforms; empty for kosem's own image. |
| `image` | `string` | Yes | The image's reference, as checked. |
| `pinned` | `string` | Yes | The reference with the digest its registry gave, keeping its tag, such as ghcr.io/acme/devbox:2026.10@sha256:…: what an agent's environment pulls once its image is set. kosem's own image as it is. |
| `registry` | `string` | No | For REGISTRY, the registry kosem signs in with: the project's, or one its organization shares with it. |

### default

Error

Base URL: `https://api.kosem.ai`. See [API conventions](https://docs.kosem.ai/reference/api-conventions.md) for authentication, pagination and errors, and [https://docs.kosem.ai/openapi.yaml](https://docs.kosem.ai/openapi.yaml) for the full OpenAPI document.