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": "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)

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

Example: string

Responses

200

List of images

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

countintegerOptional

Total number of images

Example: 2

pageintegerOptional

Current page number

Example: 1

next_pageinteger · nullableOptional

Next page number (null if no more pages)

400

Bad request

application/json

404

Not found

application/json

4710

Permission required

application/json

get/images

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

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "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": "1",
            "type": "software",
            "attributes": {
              "id": 1,
              "name": "Blender",
              "size": 1.4
            }
          }
        ]
      }
    }
  ],
  "count": 2,
  "page": 1,
  "next_page": 1
}

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

Request Body

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

Success Response Example

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

Body

machine_idintegerRequired

ID of the machine to create image from

namestring · max: 30Required

Name for the new image template. Max 30 characters.

Responses

200

Image created successfully

application/json

Image (template) object

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

idstringOptionalExample: 347

typestringOptionalExample: image

400

Bad request

application/json

404

Machine not found

application/json

4208

Machine has no image

application/json

4209

Machine is not stopped

application/json

4212

Machine has pending image

application/json

4710

Permission required

application/json

post/images

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

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

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "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": "1",
        "type": "software",
        "attributes": {
          "id": 1,
          "name": "Blender",
          "size": 1.4
        }
      }
    ]
  }
}

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

{
  "name": "Design Suite Template",
  "software_ids": [1, 2],
  "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
          }
        },
        {
          "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

Body

namestring · max: 30Required

Name for the new image template. Max 30 characters.

software_idsinteger[]Optional

List of software IDs to pre-install

base_image_idintegerRequired

Base image ID to build from

Responses

200

Image created successfully

application/json

Image (template) object

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

idstringOptionalExample: 347

typestringOptionalExample: image

400

Bad request

application/json

404

Base image not found

application/json

4710

Permission required

application/json

post/images/install

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
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "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": "1",
        "type": "software",
        "attributes": {
          "id": 1,
          "name": "Blender",
          "size": 1.4
        }
      }
    ]
  }
}

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

Path parameters

idintegerRequired

(Required) Image ID

Example: 347

Body

machine_idsinteger[]Required

List of machine IDs to assign the image to

Responses

200

Image assigned successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

400

Bad request

application/json

404

Image not found

application/json

4210

Image status is not available

application/json

4211

No machines found

application/json

4214

Machine not assignable for template

application/json

4510

Image size exceeds machine disk size

application/json

4710

Permission required

application/json

post/images/{id}/assign

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

{
  "machine_ids": [
    717,
    718,
    719
  ]
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z"
}

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

Path parameters

idintegerRequired

(Required) Image ID

Example: 1

Responses

200

Image deleted successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

400

Bad request

application/json

404

Image not found

application/json

4213

Image is building

application/json

4710

Permission required

application/json

delete/images/{id}

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

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z"
}