> For the complete documentation index, see [llms.txt](https://docs.vagon.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vagon.io/teams/reference/images.md).

# Images

## List Available Images

> Lists all organization images (templates).\
> \
> This endpoint returns all silver images (templates) created by the organization. Images can be created from machines or installed with pre-configured software.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### \*\*Query Parameters\*\*\
> \
> \| Parameter | Type | Default | Description |\
> \| --- | --- | --- | --- |\
> \| \`page\` | Integer | 1 | Page number |\
> \| \`per\_page\` | Integer | 20 | Record count per page |\
> \| \`q\` | String | \\- | Search query by image name |\
> \
> \### \*\*Success Response Example\*\*\
> \
> \`\`\` json\
> {\
>     "images": \[\
>         {\
>             "id": "347",\
>             "type": "image",\
>             "attributes": {\
>                 "id": 347,\
>                 "name": "My Custom Template",\
>                 "size": 75,\
>                 "status": "available",\
>                 "source": "seat",\
>                 "created\_at": "2026-02-04T12:47:07.761Z",\
>                 "updated\_at": "2026-02-04T12:48:11.194Z",\
>                 "softwares": \[]\
>             }\
>         },\
>         {\
>             "id": "346",\
>             "type": "image",\
>             "attributes": {\
>                 "id": 346,\
>                 "name": "Template #346",\
>                 "size": 21,\
>                 "status": "available",\
>                 "source": "pre\_installation",\
>                 "created\_at": "2026-02-03T14:37:20.238Z",\
>                 "updated\_at": "2026-02-03T14:48:13.643Z",\
>                 "softwares": \[\
>                     {\
>                         "id": "1",\
>                         "type": "software",\
>                         "attributes": {\
>                             "id": 1,\
>                             "name": "Blender",\
>                             "size": 1.4\
>                         }\
>                     }\
>                 ]\
>             }\
>         }\
>     ],\
>     "count": 2,\
>     "page": 1,\
>     "next\_page": 2,\
>     "client\_code": 200,\
>     "message": "OK",\
>     "timestamp": "2026-02-04T12:50:06Z"\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Success Response Fields\*\*\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`images\` | Array | Array of image objects |\
> \| \`images\[].id\` | String | Image ID |\
> \| \`images\[].type\` | String | Always "image" |\
> \| \`images\[].attributes.id\` | Integer | Image ID (numeric) |\
> \| \`images\[].attributes.name\` | String | Image name |\
> \| \`images\[].attributes.size\` | Integer | Image size in GB |\
> \| \`images\[].attributes.status\` | String | Image status: \`pending\`, \`building\`, \`available\`, \`failed\` |\
> \| \`images\[].attributes.source\` | String | Image source: \`pre\_installation\` (created with software) or \`seat\` (created from machine) |\
> \| \`images\[].attributes.created\_at\` | String | Creation timestamp (ISO 8601) |\
> \| \`images\[].attributes.updated\_at\` | String | Last update timestamp (ISO 8601) |\
> \| \`images\[].attributes.softwares\` | Array | Array of pre-installed software (if source is \`pre\_installation\`) |\
> \| \`count\` | Integer | Total number of images |\
> \| \`page\` | Integer | Current page number |\
> \| \`next\_page\` | Integer | Next page number. null if last page |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/images":{"get":{"summary":"List Available Images","parameters":[{"name":"page","in":"query","description":"(Optional) Page number. Default: 1","schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"(Optional) Records per page. Default: 20","schema":{"type":"integer"}},{"name":"q","in":"query","description":"(Optional) Search by image name","schema":{"type":"string"}}],"responses":{"200":{"description":"List of images","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListImagesResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Images"],"description":"Lists all organization images (templates).\n\nThis endpoint returns all silver images (templates) created by the organization. Images can be created from machines or installed with pre-configured software.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### **Query Parameters**\n\n| Parameter | Type | Default | Description |\n| --- | --- | --- | --- |\n| `page` | Integer | 1 | Page number |\n| `per_page` | Integer | 20 | Record count per page |\n| `q` | String | \\- | Search query by image name |\n\n### **Success Response Example**\n\n``` json\n{\n    \"images\": [\n        {\n            \"id\": \"347\",\n            \"type\": \"image\",\n            \"attributes\": {\n                \"id\": 347,\n                \"name\": \"My Custom Template\",\n                \"size\": 75,\n                \"status\": \"available\",\n                \"source\": \"seat\",\n                \"created_at\": \"2026-02-04T12:47:07.761Z\",\n                \"updated_at\": \"2026-02-04T12:48:11.194Z\",\n                \"softwares\": []\n            }\n        },\n        {\n            \"id\": \"346\",\n            \"type\": \"image\",\n            \"attributes\": {\n                \"id\": 346,\n                \"name\": \"Template #346\",\n                \"size\": 21,\n                \"status\": \"available\",\n                \"source\": \"pre_installation\",\n                \"created_at\": \"2026-02-03T14:37:20.238Z\",\n                \"updated_at\": \"2026-02-03T14:48:13.643Z\",\n                \"softwares\": [\n                    {\n                        \"id\": \"1\",\n                        \"type\": \"software\",\n                        \"attributes\": {\n                            \"id\": 1,\n                            \"name\": \"Blender\",\n                            \"size\": 1.4\n                        }\n                    }\n                ]\n            }\n        }\n    ],\n    \"count\": 2,\n    \"page\": 1,\n    \"next_page\": 2,\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T12:50:06Z\"\n}\n\n ```\n\n### **Success Response Fields**\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `images` | Array | Array of image objects |\n| `images[].id` | String | Image ID |\n| `images[].type` | String | Always \"image\" |\n| `images[].attributes.id` | Integer | Image ID (numeric) |\n| `images[].attributes.name` | String | Image name |\n| `images[].attributes.size` | Integer | Image size in GB |\n| `images[].attributes.status` | String | Image status: `pending`, `building`, `available`, `failed` |\n| `images[].attributes.source` | String | Image source: `pre_installation` (created with software) or `seat` (created from machine) |\n| `images[].attributes.created_at` | String | Creation timestamp (ISO 8601) |\n| `images[].attributes.updated_at` | String | Last update timestamp (ISO 8601) |\n| `images[].attributes.softwares` | Array | Array of pre-installed software (if source is `pre_installation`) |\n| `count` | Integer | Total number of images |\n| `page` | Integer | Current page number |\n| `next_page` | Integer | Next page number. null if last page |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |"}}},"components":{"schemas":{"ListImagesResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"count":{"type":"integer","description":"Total number of images"},"page":{"type":"integer","description":"Current page number"},"next_page":{"type":"integer","nullable":true,"description":"Next page number (null if no more pages)"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Image":{"type":"object","description":"Image (template) object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/ImageAttributes"}}},"ImageAttributes":{"type":"object","description":"Image (template) attributes","properties":{"id":{"type":"integer","description":"Image ID"},"name":{"type":"string","description":"Image name"},"size":{"type":"integer","description":"Image size in GB"},"status":{"type":"string","enum":["pending","building","available","failed"],"description":"Image build status"},"source":{"type":"string","enum":["pre_installation","seat"],"description":"How the image was created"},"created_at":{"type":"string","format":"date-time","description":"Image creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Image last update timestamp"},"softwares":{"type":"array","description":"List of pre-installed software in this image","items":{"$ref":"#/components/schemas/SoftwareData"}}}},"SoftwareData":{"type":"object","description":"Software data with id, type, and attributes wrapper","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/Software"}}},"Software":{"type":"object","description":"Software package that can be pre-installed on images","properties":{"id":{"type":"integer","description":"Software ID"},"name":{"type":"string","description":"Software name"},"size":{"type":"number","format":"float","description":"Software size in GB"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Create Image from Machine

> Creates an image (template) from an existing machine.\
> \
> The machine must be stopped (off) and have an available image. The created image can then be assigned to other machines.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### \*\*Body Parameters\*\*\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`machine\_id\`\\\* | Integer | Yes | Machine ID to create image from |\
> \| \`name\` | String | No | Custom name for the image (max 30 characters). If not provided, auto-generated as "Template #{image\_id}" |\
> \
> \### Request Body\
> \
> \`\`\` json\
> {\
>   "machine\_id": 1,\
>   "name": "My Custom Template"\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Success Response Example\*\*\
> \
> \`\`\` json\
> {\
>     "id": "347",\
>     "type": "image",\
>     "attributes": {\
>         "id": 347,\
>         "name": "My Custom Template",\
>         "size": 75,\
>         "status": "pending",\
>         "source": "seat",\
>         "created\_at": "2026-02-04T12:47:07.761Z",\
>         "updated\_at": "2026-02-04T12:47:07.761Z",\
>         "softwares": \[]\
>     },\
>     "client\_code": 200,\
>     "message": "OK",\
>     "timestamp": "2026-02-04T12:47:07Z"\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Error Responses\*\*\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request |\
> \| 404 | Machine not found or does not belong to organization |\
> \| 4208 | Machine image not found |\
> \| 4209 | Machine is not stopped |\
> \| 4212 | Machine image is still being created |\
> \| 4710 | Permission required |\
> \
> \### \*\*Notes\*\*\
> \
> \- Machine status will be set to \`installing\` during image creation\
> \- Image creation is asynchronous and may take time\
> \- Image status will be \`pending\` initially, then \`building\`, and finally \`available\` when ready\
> \- Only machines that are stopped (off) can be used to create images

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/images":{"post":{"summary":"Create Image from Machine","responses":{"200":{"description":"Image created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateImageResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4208":{"description":"Machine has no image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4208Response"}}}},"4209":{"description":"Machine is not stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4209Response"}}}},"4212":{"description":"Machine has pending image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4212Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Images"],"description":"Creates an image (template) from an existing machine.\n\nThe machine must be stopped (off) and have an available image. The created image can then be assigned to other machines.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### **Body Parameters**\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `machine_id`\\* | Integer | Yes | Machine ID to create image from |\n| `name` | String | No | Custom name for the image (max 30 characters). If not provided, auto-generated as \"Template #{image_id}\" |\n\n### Request Body\n\n``` json\n{\n  \"machine_id\": 1,\n  \"name\": \"My Custom Template\"\n}\n\n ```\n\n### **Success Response Example**\n\n``` json\n{\n    \"id\": \"347\",\n    \"type\": \"image\",\n    \"attributes\": {\n        \"id\": 347,\n        \"name\": \"My Custom Template\",\n        \"size\": 75,\n        \"status\": \"pending\",\n        \"source\": \"seat\",\n        \"created_at\": \"2026-02-04T12:47:07.761Z\",\n        \"updated_at\": \"2026-02-04T12:47:07.761Z\",\n        \"softwares\": []\n    },\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T12:47:07Z\"\n}\n\n ```\n\n### **Error Responses**\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request |\n| 404 | Machine not found or does not belong to organization |\n| 4208 | Machine image not found |\n| 4209 | Machine is not stopped |\n| 4212 | Machine image is still being created |\n| 4710 | Permission required |\n\n### **Notes**\n\n- Machine status will be set to `installing` during image creation\n- Image creation is asynchronous and may take time\n- Image status will be `pending` initially, then `building`, and finally `available` when ready\n- Only machines that are stopped (off) can be used to create images","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["machine_id","name"],"properties":{"machine_id":{"type":"integer","description":"ID of the machine to create image from"},"name":{"type":"string","maxLength":30,"description":"Name for the new image template. Max 30 characters."}}}}}}}}},"components":{"schemas":{"CreateImageResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"$ref":"#/components/schemas/Image"}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Image":{"type":"object","description":"Image (template) object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/ImageAttributes"}}},"ImageAttributes":{"type":"object","description":"Image (template) attributes","properties":{"id":{"type":"integer","description":"Image ID"},"name":{"type":"string","description":"Image name"},"size":{"type":"integer","description":"Image size in GB"},"status":{"type":"string","enum":["pending","building","available","failed"],"description":"Image build status"},"source":{"type":"string","enum":["pre_installation","seat"],"description":"How the image was created"},"created_at":{"type":"string","format":"date-time","description":"Image creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Image last update timestamp"},"softwares":{"type":"array","description":"List of pre-installed software in this image","items":{"$ref":"#/components/schemas/SoftwareData"}}}},"SoftwareData":{"type":"object","description":"Software data with id, type, and attributes wrapper","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/Software"}}},"Software":{"type":"object","description":"Software package that can be pre-installed on images","properties":{"id":{"type":"integer","description":"Software ID"},"name":{"type":"string","description":"Software name"},"size":{"type":"number","format":"float","description":"Software size in GB"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4208Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4209Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4212Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Create Image from Application List

> Creates an image (template) with pre-installed software.\
> \
> This endpoint creates a new image by installing software on a base image. The image can then be assigned to machines.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### \*\*Body Parameters\*\*\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`name\` | String | No | Custom name for the image (max 30 characters). If not provided, auto-generated as "Template #{base\_image\_id}" |\
> \| \`software\_ids\` | Array\\\[Integer\\] | No | Array of software IDs to pre-install. Use \`GET /software\` to see available software. Default: empty array |\
> \| \`base\_image\_id\` | Integer | No | Base image ID. If not provided, uses the latest base image. Use \`GET /software\` to see available base images |\
> \
> \### Request Body\
> \
> \`\`\` json\
> {\
>   "name": "Design Suite Template",\
>   "software\_ids": \[1, 2],\
>   "base\_image\_id": 1\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Success Response Example\*\*\
> \
> \`\`\` json\
> {\
>   "id": "1",\
>   "type": "image",\
>   "attributes": {\
>     "id": 1,\
>     "name": "Design Suite Template",\
>     "size": 107374182400,\
>     "status": "pending",\
>     "source": "pre\_installation",\
>     "created\_at": "2024-01-15T10:00:00Z",\
>     "updated\_at": "2024-01-15T10:00:00Z",\
>     "softwares": {\
>       "data": \[\
>         {\
>           "id": "1",\
>           "type": "software",\
>           "attributes": {\
>             "id": 1,\
>             "name": "Adobe Photoshop",\
>             "size": 5583457484\
>           }\
>         },\
>         {\
>           "id": "1",\
>           "type": "software",\
>           "attributes": {\
>             "id": 2,\
>             "name": "Blender",\
>             "size": 5583457484\
>           }\
>         }\
>       ]\
>     }\
>   }\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Success Response Fields\*\*\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\` | String | Image ID |\
> \| \`type\` | String | Always "image" |\
> \| \`attributes.id\` | Integer | Image ID (numeric) |\
> \| \`attributes.name\` | String | Image name |\
> \| \`attributes.size\` | Integer | Image size in GB (includes 5% buffer) |\
> \| \`attributes.status\` | String | Image status: \`pending\` initially, then \`building\`, and finally \`available\` |\
> \| \`attributes.source\` | String | Always \`pre\_installation\` for this endpoint |\
> \| \`attributes.created\_at\` | String | Creation timestamp (ISO 8601) |\
> \| \`attributes.updated\_at\` | String | Last update timestamp (ISO 8601) |\
> \| \`attributes.softwares\` | Object | Array of pre-installed software |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |\
> \
> \### \*\*Error Responses\*\*\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request |\
> \| 404 | Base image not found (if base\_image\_id provided) |\
> \| 4710 | Permission required |\
> \
> \### \*\*Notes\*\*\
> \
> \- Image creation is asynchronous and may take time\
>     \
> \- Image size is calculated with a 5% buffer\
>     \
> \- If \`software\_ids\` is empty, only the base image size (with buffer) is used\
>     \
> \- Image status will be \`pending\` initially, then \`building\`, and finally \`available\` when ready\
>     \
> \- Use \`GET /images/:id\` to check image status

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/images/install":{"post":{"summary":"Create Image from Application List","responses":{"200":{"description":"Image created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateImageResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Base image not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Images"],"description":"Creates an image (template) with pre-installed software.\n\nThis endpoint creates a new image by installing software on a base image. The image can then be assigned to machines.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### **Body Parameters**\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | String | No | Custom name for the image (max 30 characters). If not provided, auto-generated as \"Template #{base_image_id}\" |\n| `software_ids` | Array\\[Integer\\] | No | Array of software IDs to pre-install. Use `GET /software` to see available software. Default: empty array |\n| `base_image_id` | Integer | No | Base image ID. If not provided, uses the latest base image. Use `GET /software` to see available base images |\n\n### Request Body\n\n``` json\n{\n  \"name\": \"Design Suite Template\",\n  \"software_ids\": [1, 2],\n  \"base_image_id\": 1\n}\n\n ```\n\n### **Success Response Example**\n\n``` json\n{\n  \"id\": \"1\",\n  \"type\": \"image\",\n  \"attributes\": {\n    \"id\": 1,\n    \"name\": \"Design Suite Template\",\n    \"size\": 107374182400,\n    \"status\": \"pending\",\n    \"source\": \"pre_installation\",\n    \"created_at\": \"2024-01-15T10:00:00Z\",\n    \"updated_at\": \"2024-01-15T10:00:00Z\",\n    \"softwares\": {\n      \"data\": [\n        {\n          \"id\": \"1\",\n          \"type\": \"software\",\n          \"attributes\": {\n            \"id\": 1,\n            \"name\": \"Adobe Photoshop\",\n            \"size\": 5583457484\n          }\n        },\n        {\n          \"id\": \"1\",\n          \"type\": \"software\",\n          \"attributes\": {\n            \"id\": 2,\n            \"name\": \"Blender\",\n            \"size\": 5583457484\n          }\n        }\n      ]\n    }\n  }\n}\n\n ```\n\n### **Success Response Fields**\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `id` | String | Image ID |\n| `type` | String | Always \"image\" |\n| `attributes.id` | Integer | Image ID (numeric) |\n| `attributes.name` | String | Image name |\n| `attributes.size` | Integer | Image size in GB (includes 5% buffer) |\n| `attributes.status` | String | Image status: `pending` initially, then `building`, and finally `available` |\n| `attributes.source` | String | Always `pre_installation` for this endpoint |\n| `attributes.created_at` | String | Creation timestamp (ISO 8601) |\n| `attributes.updated_at` | String | Last update timestamp (ISO 8601) |\n| `attributes.softwares` | Object | Array of pre-installed software |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |\n\n### **Error Responses**\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request |\n| 404 | Base image not found (if base_image_id provided) |\n| 4710 | Permission required |\n\n### **Notes**\n\n- Image creation is asynchronous and may take time\n    \n- Image size is calculated with a 5% buffer\n    \n- If `software_ids` is empty, only the base image size (with buffer) is used\n    \n- Image status will be `pending` initially, then `building`, and finally `available` when ready\n    \n- Use `GET /images/:id` to check image status","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","base_image_id"],"properties":{"name":{"type":"string","maxLength":30,"description":"Name for the new image template. Max 30 characters."},"software_ids":{"type":"array","description":"List of software IDs to pre-install","items":{"type":"integer"}},"base_image_id":{"type":"integer","description":"Base image ID to build from"}}}}}}}}},"components":{"schemas":{"CreateImageResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"$ref":"#/components/schemas/Image"}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Image":{"type":"object","description":"Image (template) object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/ImageAttributes"}}},"ImageAttributes":{"type":"object","description":"Image (template) attributes","properties":{"id":{"type":"integer","description":"Image ID"},"name":{"type":"string","description":"Image name"},"size":{"type":"integer","description":"Image size in GB"},"status":{"type":"string","enum":["pending","building","available","failed"],"description":"Image build status"},"source":{"type":"string","enum":["pre_installation","seat"],"description":"How the image was created"},"created_at":{"type":"string","format":"date-time","description":"Image creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Image last update timestamp"},"softwares":{"type":"array","description":"List of pre-installed software in this image","items":{"$ref":"#/components/schemas/SoftwareData"}}}},"SoftwareData":{"type":"object","description":"Software data with id, type, and attributes wrapper","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"$ref":"#/components/schemas/Software"}}},"Software":{"type":"object","description":"Software package that can be pre-installed on images","properties":{"id":{"type":"integer","description":"Software ID"},"name":{"type":"string","description":"Software name"},"size":{"type":"number","format":"float","description":"Software size in GB"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Assign Image to Machines

> Assigns an image (template) to one or more machines.\
> \
> This endpoint assigns a template image to machines. The machines will be terminated and recreated with the assigned image on next start. Only images with \`available\` status can be assigned.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\`\\\* | Integer | Image ID to assign |\
> \
> \### \*\*Body Parameters\*\*\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`machine\_ids\`\\\* | Array\\\[Integer\\] | Yes | Array of machine IDs to assign the image to |\
> \
> \### Request Body\
> \
> \`\`\` json\
> {\
>   "machine\_ids": \[1, 2, 3]\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Success Response\*\*\
> \
> \`\`\` json\
> {\
>     "client\_code": 200,\
>     "message": "OK",\
>     "timestamp": "2026-01-15T15:14:09Z"\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Error Responses\*\*\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request |\
> \| 404 | Image not found or does not belong to organization |\
> \| 4210 | Image status is not available (must be \`available\`) |\
> \| 4211 | No machines found or machines do not belong to organization |\
> \| 4214 | Machine is not assignable for template (has pending session image) |\
> \| 4510 | Image size exceeds machine disk size |\
> \| 4710 | Permission required |\
> \
> \### \*\*Notes\*\*\
> \
> \- Only images with \`available\` status can be assigned.\
>     \
> \- Machine data will be reset and recreated with the assigned image on next start.\
>     \
> \- Image size must not exceed the machine's disk size.\
>     \
> \- Machine will be turned to installing machine state, at the first run after the image/template assignment.

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/images/{id}/assign":{"post":{"summary":"Assign Image to Machines","responses":{"200":{"description":"Image assigned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Image not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4210":{"description":"Image status is not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4210Response"}}}},"4211":{"description":"No machines found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4211Response"}}}},"4214":{"description":"Machine not assignable for template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4214Response"}}}},"4510":{"description":"Image size exceeds machine disk size","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4510Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Images"],"description":"Assigns an image (template) to one or more machines.\n\nThis endpoint assigns a template image to machines. The machines will be terminated and recreated with the assigned image on next start. Only images with `available` status can be assigned.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Image ID to assign |\n\n### **Body Parameters**\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `machine_ids`\\* | Array\\[Integer\\] | Yes | Array of machine IDs to assign the image to |\n\n### Request Body\n\n``` json\n{\n  \"machine_ids\": [1, 2, 3]\n}\n\n ```\n\n### **Success Response**\n\n``` json\n{\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-01-15T15:14:09Z\"\n}\n\n ```\n\n### **Error Responses**\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request |\n| 404 | Image not found or does not belong to organization |\n| 4210 | Image status is not available (must be `available`) |\n| 4211 | No machines found or machines do not belong to organization |\n| 4214 | Machine is not assignable for template (has pending session image) |\n| 4510 | Image size exceeds machine disk size |\n| 4710 | Permission required |\n\n### **Notes**\n\n- Only images with `available` status can be assigned.\n    \n- Machine data will be reset and recreated with the assigned image on next start.\n    \n- Image size must not exceed the machine's disk size.\n    \n- Machine will be turned to installing machine state, at the first run after the image/template assignment.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["machine_ids"],"properties":{"machine_ids":{"type":"array","description":"List of machine IDs to assign the image to","items":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"SuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4210Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4211Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4214Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4510Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Delete Image

> Deletes an image (template).\
> \
> This endpoint deletes an organization image. Images that are currently being built cannot be deleted.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\`\\\* | Integer | Image ID to delete |\
> \
> \### \*\*Success Response\*\*\
> \
> \`\`\` json\
> {\
>     "client\_code": 200,\
>     "message": "OK",\
>     "timestamp": "2026-01-15T15:14:09Z"\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Error Responses\*\*\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request |\
> \| 404 | Image not found or does not belong to organization |\
> \| 4213 | Image is building (cannot delete while building) |\
> \| 4710 | Permission required |\
> \
> \### \*\*Notes\*\*\
> \
> \- Images with \`building\` status cannot be deleted\
>     \
> \- Images with \`pending\` or \`available\` status can be deleted\
>     \
> \- Deletion is asynchronous and may take time to complete\
>     \
> \- The image will be marked as deleted and cleaned up

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/images/{id}":{"delete":{"summary":"Delete Image","responses":{"200":{"description":"Image deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Image not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4213":{"description":"Image is building","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4213Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Images"],"description":"Deletes an image (template).\n\nThis endpoint deletes an organization image. Images that are currently being built cannot be deleted.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Image ID to delete |\n\n### **Success Response**\n\n``` json\n{\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-01-15T15:14:09Z\"\n}\n\n ```\n\n### **Error Responses**\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request |\n| 404 | Image not found or does not belong to organization |\n| 4213 | Image is building (cannot delete while building) |\n| 4710 | Permission required |\n\n### **Notes**\n\n- Images with `building` status cannot be deleted\n    \n- Images with `pending` or `available` status can be deleted\n    \n- Deletion is asynchronous and may take time to complete\n    \n- The image will be marked as deleted and cleaned up"}}},"components":{"schemas":{"SuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4213Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````