From eba3e894a9827b718f9e0292fdc9464e6890ad8a Mon Sep 17 00:00:00 2001 From: Jerome Jaggi Date: Fri, 13 Mar 2026 15:29:29 +0100 Subject: [PATCH 1/2] docs: add REST API reference section to images page Signed-off-by: Jerome Jaggi --- pages/platform/images.mdx | 51 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/pages/platform/images.mdx b/pages/platform/images.mdx index 3ebefb0..7c9f9a2 100644 --- a/pages/platform/images.mdx +++ b/pages/platform/images.mdx @@ -185,6 +185,57 @@ kraft cloud instance create \ You now have a new instance created from the existing image. +## REST API reference + +### List images + +``` +GET /v1/images +``` + +Returns all images in your account. +Each image object includes: + +| Field | Type | Description | +|-------|------|-------------| +| `uuid` | string | Image UUID. | +| `name` | string | Image name (if present). | +| `created_at` | timestamp | Creation time. | +| `url` | string | Full image address (includes digest). | +| `initrd_or_rom` | bool | Whether the image includes an initrd or ROM component. | +| `size_in_bytes` | int64 | Total image size in bytes. | +| `args` | array of strings | Default arguments (omitted if none). | + +### Look up by UUID + +``` +GET /v1/images?uuid=[,…] +``` + +Returns one or more images by UUID. + +### Look up by digest + +``` +GET /v1/images/list +``` + +Pass a `digest` string in the request body to return the image matching that digest: + +```json title="GET /v1/images/list" +{ + "digest": "sha256:278cb8b14f9faf9c2702dddd8bfb6124912d82c11b4a2c6590b6e32fc4049472" +} +``` + +The response includes `digest`, `tags`, `initrd`, `size_in_bytes`, and `args`. + +:::note +Tag-based filtering (`tag` field in the list body) appears in the API schema but the platform doesn't act on it yet. +The platform accepts and ignores the field. +Use the digest or UUID endpoints to look up a specific image. +::: + ## Learn more * The `kraft cloud` [CLI reference](/cli/) From 3b6fbc37a064b80f52bf88e5f2b0792787440d34 Mon Sep 17 00:00:00 2001 From: Maria Sfiraiala Date: Tue, 17 Mar 2026 23:22:42 +0200 Subject: [PATCH 2/2] docs: Fix minor inconsistencies with images Signed-off-by: Maria Sfiraiala --- pages/platform/images.mdx | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/pages/platform/images.mdx b/pages/platform/images.mdx index 7c9f9a2..57d4bdb 100644 --- a/pages/platform/images.mdx +++ b/pages/platform/images.mdx @@ -193,18 +193,21 @@ You now have a new instance created from the existing image. GET /v1/images ``` -Returns all images in your account. +Returns all images accessible for your account and known by the platform. Each image object includes: | Field | Type | Description | |-------|------|-------------| | `uuid` | string | Image UUID. | -| `name` | string | Image name (if present). | | `created_at` | timestamp | Creation time. | +| `owner` | string | Owner of the image (omitted if not root account). | | `url` | string | Full image address (includes digest). | +| `tags` | array of strings | List of shortened tags. | | `initrd_or_rom` | bool | Whether the image includes an initrd or ROM component. | | `size_in_bytes` | int64 | Total image size in bytes. | | `args` | array of strings | Default arguments (omitted if none). | +| `env` | map of strings | Default environmental variables (omitted if none). | +| `users` | array of strings | Users with access to the image (omitted if not root account). | ### Look up by UUID @@ -217,24 +220,34 @@ Returns one or more images by UUID. ### Look up by digest ``` -GET /v1/images/list +GET /v1/images ``` Pass a `digest` string in the request body to return the image matching that digest: -```json title="GET /v1/images/list" +```json title="GET /v1/images" { - "digest": "sha256:278cb8b14f9faf9c2702dddd8bfb6124912d82c11b4a2c6590b6e32fc4049472" + "digest": "user/image@sha256:278cb8b14f9faf9c2702dddd8bfb6124912d82c11b4a2c6590b6e32fc4049472" } ``` -The response includes `digest`, `tags`, `initrd`, `size_in_bytes`, and `args`. +The response includes `url`, `tags`, `initrd_or_rom`, `size_in_bytes`, args` and `env`. -:::note -Tag-based filtering (`tag` field in the list body) appears in the API schema but the platform doesn't act on it yet. -The platform accepts and ignores the field. -Use the digest or UUID endpoints to look up a specific image. -::: +### Look up by tag + +``` +GET /v1/images +``` + +Pass a `tag` string in the request body to return the image matching that tag: + +```json title="GET /v1/images" +{ + "tag": "user/image:tag" +} +``` + +The response includes `url`, `tags`, `initrd_or_rom`, `size_in_bytes`, args` and `env`. ## Learn more