Skip to Content
kosemdocs
ReferenceAPIEnvironments

Check image

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.

POST
/v1/projects/{project}/images/check

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.

Authorization

bearer
headerAuthorizationBearer <token>

An access token, or an API key.

Path Parameters

project*string

The project's ID.

Match^prj_[0-7][0-9a-hjkmnp-tv-z]{25}$

Request Body

application/json
  1. body
image*string

The image's reference, with a tag or a digest, such as ghcr.io/acme/devbox:2026.10.

Lengthlength <= 512

Response Body

OK

application/json
  1. response
access*string

How kosem pulls it: KOSEM, its own image; PUBLIC, without signing in; REGISTRY, signed in with registry.

Value in"KOSEM""PUBLIC""REGISTRY"
compressedBytes*integer

The size of the linux/amd64 image's layers and config, compressed, as its registry sends them; 0 for kosem's own image.

Formatint64
digest*string

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

The image's reference, as checked.

pinned*string

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

For REGISTRY, the registry kosem signs in with: the project's, or one its organization shares with it.

Example Request
curl -X POST 'https://api.kosem.ai/v1/projects/string/images/check' \
  -H 'Content-Type: application/json' \
  -d '{
  "image": "string"
}'
Example Response
{
  "access": "KOSEM",
  "compressedBytes": 0,
  "digest": "string",
  "image": "string",
  "pinned": "string",
  "registry": "string"
}