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

Page number

per_page

Integer

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

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

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

namestringRequired

Name for the new image template

Responses

200

Image created successfully

application/json

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

Custom name for the image. If not provided, auto-generated as "Template #{base_image_id}"

software_ids

Array[Integer]

Array of software IDs to pre-install. Use GET /software to see available software. Default: empty array

base_image_id

Integer

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

namestringRequired

Name for the new image template

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

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

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

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

PreviousUser Action Logs NextUsages

Last updated 2 days ago

hashtagList Available Images

hashtagHeaders

hashtagQuery Parameters

hashtagSuccess Response Example

hashtagSuccess Response Fields

hashtagCreate Image from Machine

hashtagHeaders

hashtagBody Parameters

hashtagRequest Body

hashtagSuccess Response Example

hashtagError Responses

hashtagNotes

hashtagCreate Image from Application List

hashtagHeaders

hashtagBody Parameters

hashtagRequest Body

hashtagSuccess Response Example

hashtagSuccess Response Fields

hashtagError Responses

hashtagNotes

hashtagAssign Image to Machines

hashtagHeaders

hashtagPath Parameters

hashtagBody Parameters

hashtagRequest Body

hashtagSuccess Response

hashtagError Responses

hashtagNotes

hashtagDelete Image

hashtagHeaders

hashtagPath Parameters

hashtagSuccess Response

hashtagError Responses

hashtagNotes

List Available Images

Headers

Query Parameters

Success Response Example

Success Response Fields

Create Image from Machine

Headers

Body Parameters

Request Body

Success Response Example

Error Responses

Notes

Create Image from Application List

Headers

Body Parameters

Request Body

Success Response Example

Success Response Fields

Error Responses

Notes

Assign Image to Machines

Headers

Path Parameters

Body Parameters

Request Body

Success Response

Error Responses

Notes

Delete Image

Headers

Path Parameters

Success Response

Error Responses

Notes