Skip to Content
kosemdocs
ReferenceAPIEnvironments

Create image in project

Creates an image, which kosem prepares so that the environments that run it start and read its files faster. The image is checked as its organization's or project's environments would pull it, and refused as CheckImage refuses one. Its size counts against the organization's quota.

POST
/v1/projects/{project}/images

Creates an image, which kosem prepares so that the environments that run it start and read its files faster.

The image is checked as its organization's or project's environments would pull it, and refused as CheckImage refuses one. Its size counts against the organization's quota.

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
availability?

For an organization's image: the projects whose environments use it. None, unless set. Setting it also takes environments.images.setAvailability.

displayName*string

What people call the image.

Length1 <= length <= 100
followTag?boolean

Whether kosem resolves its tag again every hour; true unless set.

keepVersions?integer

How many of its newest versions it keeps, from 1 to 10; 3 unless set.

Formatint32
Range1 <= value <= 10
source*string

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

Lengthlength <= 512

Response Body

Created

application/json
  1. response
availability*

For an organization's image: the projects whose environments use it. A project's image is available to none.

checkTime?string

When kosem last resolved its source; unset until it has.

Formatdate-time
createTime*string

When the image was created.

Formatdate-time
displayName*string

What people call the image.

followTag*boolean

Whether kosem resolves its tag again every hour, as RefreshImage does, so that it prepares each new version. A source named by a digest never moves.

keepVersions*integer

How many of its newest versions it keeps. An older one is deleted once no environment runs it.

Formatint32
name*string

Resource name, organizations/{organization_id}/images/{image_id} or projects/{project_id}/images/{image_id}.

refreshReason*string

Why kosem's last check of its tag couldn't refresh it, which leaves it as it was; empty once a check can.

registry?string

The registry that kosem signs in with to pull it, when it's private.

source*string

The image's reference, with a tag or a digest, in its shortest spelling, such as node:24 for docker.io/library/node:24. Set when the image is created, and never changed.

state*string

PREPARING until its latest version is ready to run, READY once it is, and FAILED if kosem can't prepare it.

Value in"PREPARING""READY""FAILED"
stateReason*string

Why kosem can't prepare it, when it can't.

updateTime*string

When the image last changed.

Formatdate-time
versions*array<>

What its source named each time it was resolved, newest first.

Example Request
curl -X POST 'https://api.kosem.ai/v1/projects/string/images' \
  -H 'Content-Type: application/json' \
  -d '{
  "displayName": "string",
  "source": "string"
}'
Example Response
{
  "availability": {
    "allProjects": true,
    "projects": [
      "string"
    ]
  },
  "checkTime": "2019-08-24T14:15:22Z",
  "createTime": "2019-08-24T14:15:22Z",
  "displayName": "string",
  "followTag": true,
  "keepVersions": 0,
  "name": "string",
  "refreshReason": "string",
  "registry": "string",
  "source": "string",
  "state": "PREPARING",
  "stateReason": "string",
  "updateTime": "2019-08-24T14:15:22Z",
  "versions": [
    {
      "createTime": "2019-08-24T14:15:22Z",
      "digest": "string",
      "environments": 0,
      "prepareTime": "2019-08-24T14:15:22Z",
      "sizeBytes": 0
    }
  ]
}