# 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.6"},"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.6"},"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.6"},"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.6"},"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.6"},"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"}]}}}} ```` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.vagon.io/teams/reference/images.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.