Images

Server

An image is a collection of objects representing a VM which can be deployed on Unikraft Cloud. Its format is based on the OCI Image Specification. Within the context of Unikraft Cloud, these images also include a kernel component.

Get Images in Store

GET

https://api.sfo.unikraft.cloud

/v1/image-store

Retrieve all images in store.

Get Images in Store › query Parameters

digest

string

tag

string

Get Images in Store › Request Body optional

Images.GetImagesRequestTagOrDigest[]

Images.GetImagesRequestTagOrDigest

digest

string

tag

string

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: digest
	type = object · requires: tag

Properties for Variant 1:

digest

string · required

tag

string

Get Images in Store › Responses

200

The request has succeeded.

The response message for getting one or more image(s).

Images.GetImagesResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

GET/v1/image-store

curl https://api.sfo.unikraft.cloud/v1/image-store \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  {
    "digest": "digest",
    "tag": "tag"
  }
]'

Example Request Body

[
  {
    "digest": "digest",
    "tag": "tag"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "images": [
      {
        "url": "url",
        "created_at": "2024-08-25T15:00:00Z",
        "initrd_or_rom": true,
        "size_in_bytes": 0,
        "args": [
          "string"
        ],
        "env": {
          "key": "string"
        },
        "tags": [
          "string"
        ],
        "users": [
          "string"
        ],
        "persistent": true
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Get Images

GET

https://api.sfo.unikraft.cloud

/v1/images

Retrieve all images.

Get Images › query Parameters

digest

string

tag

string

Get Images › Request Body optional

Images.GetImagesRequestTagOrDigest[]

Images.GetImagesRequestTagOrDigest

digest

string

tag

string

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: digest
	type = object · requires: tag

Properties for Variant 1:

digest

string · required

tag

string

Get Images › Responses

200

The request has succeeded.

The response message for getting one or more image(s).

Images.GetImagesResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

GET/v1/images

curl https://api.sfo.unikraft.cloud/v1/images \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  {
    "digest": "digest",
    "tag": "tag"
  }
]'

Example Request Body

[
  {
    "digest": "digest",
    "tag": "tag"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "images": [
      {
        "url": "url",
        "created_at": "2024-08-25T15:00:00Z",
        "initrd_or_rom": true,
        "size_in_bytes": 0,
        "args": [
          "string"
        ],
        "env": {
          "key": "string"
        },
        "tags": [
          "string"
        ],
        "users": [
          "string"
        ],
        "persistent": true
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Pin Images

POST

https://api.sfo.unikraft.cloud

/v1/images

Pull and pin one or more images so they stay cached and are never evicted, without relying on an on-demand pull to succeed at instance start. If a pull fails, the agent's error is returned in the entry's message field.

Pin Images › Request Body

Images.PinImageRequestItem[]

The request item for pinning a single image.

Images.PinImageRequestItem

url

string · required

The image URL to pull and pin.

Example: user/image:latest

timeout_s

integer · int64 · required

Number of seconds to wait for the pull to complete. Required and must be non-zero; -1 waits up to the platform's maximum timeout.

Example: 30

credentials

string

Optional credentials for authenticating to an OCI registry. Only valid for OCI registry URLs; the platform rejects this field for non-OCI schemes.

Example: dXNlcjpwYXNzd29yZA==

object

Optional HTTP headers to send when fetching the image.

Example: {"Authorization":"Bearer token123"}

pull_policy

string · enum

Controls when the image is pulled relative to what is already cached on the node. If unset, this is inferred from the URL.

Enum values:

always

if_not_present

never

merge_requests

boolean

Avoid duplicate pulls by merging with any in-flight request for the same image. Defaults to true.

Example: true

object

Automatically unpin the image after a period of inactivity.

Pin Images › Responses

200

The request has succeeded.

The response message for pinning one or more images.

Images.PinImagesResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

POST/v1/images

curl https://api.sfo.unikraft.cloud/v1/images \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  {
    "url": "user/image:latest",
    "credentials": "dXNlcjpwYXNzd29yZA==",
    "headers": {
      "Authorization": "Bearer token123"
    },
    "pull_policy": "always",
    "timeout_s": 30,
    "merge_requests": true,
    "autokill": {
      "time_ms": 60000
    }
  }
]'

Example Request Body

[
  {
    "url": "user/image:latest",
    "credentials": "dXNlcjpwYXNzd29yZA==",
    "headers": {
      "Authorization": "Bearer token123"
    },
    "pull_policy": "always",
    "timeout_s": 30,
    "merge_requests": true,
    "autokill": {
      "time_ms": 60000
    }
  }
]

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "images": [
      {
        "status": "success",
        "message": "message",
        "error": 0,
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "created_at": "2021-01-01T00:00:00Z",
        "state": "ready",
        "url": "user/image:latest",
        "persistent": true,
        "tags": [
          "string"
        ]
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Unpin Images

DELETE

https://api.sfo.unikraft.cloud

/v1/images

Unpin one or more images by UUID, making them eligible for normal cache eviction again. This does not delete the image.

Unpin Images › Request Body

Images.UnpinImageRequestItem[]

The request item for unpinning a single image.

Images.UnpinImageRequestItem

uuid

string · uuid · required

The UUID of the image to unpin. Only UUID is supported; name, URL, tag, and digest are not.

Unpin Images › Responses

200

The request has succeeded.

The response message for unpinning one or more images.

Images.UnpinImagesResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

Users Certificates