Images

oneOf

Exactly one variant must match.

Decision Table

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

Properties for digest:

digest

string · required

Get Images in Store › Responses

default

status

string · enum · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 123

message

string

An optional message providing additional information about the response.

Example: No images found

object

The response data for this request.

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

GET/v1/image-store

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

Example Request Body

[
  {
    "digest": "sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "No images found",
  "data": {
    "images": [
      {
        "url": "my-image:latest",
        "created_at": "2021-01-01T00:00:00Z",
        "initrd_or_rom": true,
        "size_in_bytes": 10485760,
        "args": [
          "--verbose"
        ],
        "env": {
          "production": "on"
        },
        "tags": [
          "latest"
        ],
        "users": [
          "root"
        ],
        "persistent": true
      }
    ]
  },
  "errors": [
    {
      "status": 401
    }
  ],
  "op_time_us": 123
}

json

application/json

Get Images

GET

https://api.fra.unikraft.cloud

/v1/images

Retrieve all images.

Get Images › query Parameters

digest

string

tag

string

Get Images › Request Body

oneOf

Exactly one variant must match.

Decision Table

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

Properties for digest:

digest

string · required

Get Images › Responses

default

status

string · enum · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 123

message

string

An optional message providing additional information about the response.

Example: No images found

object

The response data for this request.

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

GET/v1/images

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

Example Request Body

[
  {
    "digest": "sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "No images found",
  "data": {
    "images": [
      {
        "url": "my-image:latest",
        "created_at": "2021-01-01T00:00:00Z",
        "initrd_or_rom": true,
        "size_in_bytes": 10485760,
        "args": [
          "--verbose"
        ],
        "env": {
          "production": "on"
        },
        "tags": [
          "latest"
        ],
        "users": [
          "root"
        ],
        "persistent": true
      }
    ]
  },
  "errors": [
    {
      "status": 401
    }
  ],
  "op_time_us": 123
}

json

application/json

Pin Images

POST

https://api.fra.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

PinImageRequestItem[]

The request item for pinning a single image.

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 · 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

(Optional). Automatically unpin the image after a period of inactivity.

Pin Images › Responses

default

The response message for pinning one or more images.

PinImagesResponse

status

string · enum · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 123

message

string

An optional message providing additional information about the response. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

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

POST/v1/images

curl https://api.fra.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": "Failed to perform all operations",
  "data": {
    "images": [
      {
        "status": "success",
        "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"
        ],
        "message": "Image pull failed",
        "error": 10
      }
    ]
  },
  "errors": [
    {
      "status": 401
    }
  ],
  "op_time_us": 123
}

json

application/json

Unpin Images

DELETE

https://api.fra.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

UnpinImageRequestItem[]

The request item for unpinning a single image.

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

default

The response message for unpinning one or more images.

UnpinImagesResponse

status

string · enum · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 123

message

string

An optional message providing additional information about the response. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

Unikraft Cloud Platform API

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

DELETE/v1/images

curl https://api.fra.unikraft.cloud/v1/images \
  --request DELETE \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  {
    "uuid": "00000000-0000-0000-0000-000000000000"
  }
]'

Example Request Body

[
  {
    "uuid": "00000000-0000-0000-0000-000000000000"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "Failed to perform all operations",
  "data": {
    "images": [
      {
        "status": "success",
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "message": "No image with UUID '123e4567-e89b-12d3-a456-426614174000'",
        "error": 8
      }
    ]
  },
  "errors": [
    {
      "status": 401
    }
  ],
  "op_time_us": 123
}

json

application/json

Certificates Instances

Images

Server

Get Images in Store

GET

https://api.fra.unikraft.cloud

/v1/image-store

Retrieve all images.

Get Images in Store › query Parameters

digest

string

tag

string

Get Images in Store › Request Body

oneOf

Exactly one variant must match.

Decision Table

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

Properties for digest:

digest

string · required

Get Images in Store › Responses

default

status

string · enum · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 123

message

string

An optional message providing additional information about the response.

Example: No images found

object

The response data for this request.

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

GET/v1/image-store

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

Example Request Body

[
  {
    "digest": "sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "No images found",
  "data": {
    "images": [
      {
        "url": "my-image:latest",
        "created_at": "2021-01-01T00:00:00Z",
        "initrd_or_rom": true,
        "size_in_bytes": 10485760,
        "args": [
          "--verbose"
        ],
        "env": {
          "production": "on"
        },
        "tags": [
          "latest"
        ],
        "users": [
          "root"
        ],
        "persistent": true
      }
    ]
  },
  "errors": [
    {
      "status": 401
    }
  ],
  "op_time_us": 123
}

json

application/json

Get Images

GET

https://api.fra.unikraft.cloud

/v1/images

Retrieve all images.

Get Images › query Parameters

digest

string

tag

string

Get Images › Request Body

oneOf

Exactly one variant must match.

Decision Table

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

Properties for digest:

digest

string · required

Get Images › Responses

default

status

string · enum · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 123

message

string

An optional message providing additional information about the response.

Example: No images found

object

The response data for this request.

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

GET/v1/images

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

Example Request Body

[
  {
    "digest": "sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "No images found",
  "data": {
    "images": [
      {
        "url": "my-image:latest",
        "created_at": "2021-01-01T00:00:00Z",
        "initrd_or_rom": true,
        "size_in_bytes": 10485760,
        "args": [
          "--verbose"
        ],
        "env": {
          "production": "on"
        },
        "tags": [
          "latest"
        ],
        "users": [
          "root"
        ],
        "persistent": true
      }
    ]
  },
  "errors": [
    {
      "status": 401
    }
  ],
  "op_time_us": 123
}

json

application/json

Pin Images

POST

https://api.fra.unikraft.cloud

/v1/images

Pin Images › Request Body

PinImageRequestItem[]

The request item for pinning a single image.

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 · 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

(Optional). Automatically unpin the image after a period of inactivity.

Pin Images › Responses

default

The response message for pinning one or more images.

PinImagesResponse

status

string · enum · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 123

message

string

An optional message providing additional information about the response. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

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

POST/v1/images

curl https://api.fra.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": "Failed to perform all operations",
  "data": {
    "images": [
      {
        "status": "success",
        "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"
        ],
        "message": "Image pull failed",
        "error": 10
      }
    ]
  },
  "errors": [
    {
      "status": 401
    }
  ],
  "op_time_us": 123
}

json

application/json

Unpin Images

DELETE

https://api.fra.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

UnpinImageRequestItem[]

The request item for unpinning a single image.

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

default

The response message for unpinning one or more images.

UnpinImagesResponse

status

string · enum · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 123

message

string

An optional message providing additional information about the response. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.