Images

List Available Images

get

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

{
  "images": [
    {
      "id": "1",
      "type": "image",
      "attributes": {
        "id": 1,
        "name": "Template #123",
        "size": 107374182400,
        "status": "available",
        "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
              }
            }
          ]
        }
      }
    }
  ],
  "count": 10,
  "page": 1,
  "next_page": 2
}

Success Response Fields

Field	Type	Description
images	Array	Array of image objects
images[].id	Integer	Image ID
images[].attributes.name	String	Image name
images[].attributes.size	Integer	Image size in bytes
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.softwares	Object	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 this is the last page

Query parameters

pageintegerOptional

(Optional) Page number. Default: 1

Example: 1

per_pageintegerOptional

(Optional) Records per page. Default: 20

Example: 20

qstringOptional

(Optional) Search by image name

Responses

get

/organization-management/v1/images

HTTPcURLJavaScriptPython

GET /organization-management/v1/images HTTP/1.1
Host: api.vagon.io
Accept: */*

Create Image from Machine

post

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. If not provided, auto-generated as "Template #{image_id}"

Request Body

{
  "machine_id": 1,
  "name": "My Custom Template"
}

Success Response Example

{
  "id": "1",
  "type": "image",
  "attributes": {
    "id": 1,
    "name": "My Custom Template",
    "size": 107374182400,
    "status": "pending",
    "source": "seat",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z",
    "softwares": {
      "data": []
    }
  }
}

Error Responses

Status	Description
400	Bad request
404	Machine not found or does not belong to organization
4208	Machine has no image
4209	Machine is not off (must be stopped)
4212	Machine has a pending image being created

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

Body

application/json

machine_idintegerOptional

namestringOptional

Responses

post

/organization-management/v1/images

HTTPcURLJavaScriptPython

POST /organization-management/v1/images HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 44

{
  "machine_id": 1,
  "name": "My Custom Template"
}

Create Image from Application List

post

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

{
  "name": "Design Suite Template",
  "software_ids": [1, 2, 3],
  "base_image_id": 1
}

Success Response Example

{
  "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
          }
        }
      ]
    }
  }
}

Success Response Fields

Field	Type	Description
id	Integer	Image ID
attributes.name	String	Image name
attributes.size	Integer	Image size in bytes (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.softwares	Object	Array of pre-installed software

Error Responses

Status	Description
400	Bad request
404	Base image not found (if base_image_id provided)

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

Body

application/json

namestringOptional

software_idsinteger[]Optional

base_image_idintegerOptional

Responses

post

/organization-management/v1/images/install

HTTPcURLJavaScriptPython

POST /organization-management/v1/images/install HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 73

{
  "name": "Design Suite Template",
  "software_ids": [
    1,
    2,
    3
  ],
  "base_image_id": 1
}

Assign Image to Machines

post

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

{
  "machine_ids": [1, 2, 3]
}

Success Response

{
    "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

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.

Path parameters

idanyRequired

(Required) Image ID

Example: 1

Body

application/json

machine_idsinteger[]Optional

Responses

post

/organization-management/v1/images/{id}/assign

HTTPcURLJavaScriptPython

POST /organization-management/v1/images/{id}/assign HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "machine_ids": [
    1,
    2,
    3
  ]
}

Delete Image

delete

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

{
    "client_code": 200,
    "message": "OK",
    "timestamp": "2026-01-15T15:14:09Z"
}

Error Responses

Status	Description
404	Image not found or does not belong to organization
4213	Image is building (cannot delete while building)

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

Path parameters

idintegerRequired

(Required) Image ID

Example: 1

Responses

delete

/organization-management/v1/images/{id}

HTTPcURLJavaScriptPython

DELETE /organization-management/v1/images/{id} HTTP/1.1
Host: api.vagon.io
Accept: */*