The Container Images API lets you browse the public image catalog, manage images you have imported or purchased, and submit ratings. Use these endpoints to discover available operating systems and architectures, retrieve detailed metadata, and add images to your workspace so they can be used when launching containers.

Note

Endpoints that operate on user-owned images (/user, /import, /purchase, /rate) require authentication via a bearer token.

Public Images

GET /api/v1/images/public

List all public container images with optional filtering by operating system, architecture, price, rating, and free-text search. Results are paginated.

Parameters

Name	In	Type	Required	Description
os	query	string	No	Filter images by operating system — e.g., ubuntu, debian, alpine, centos
architecture	query	string	No	Filter images by CPU architecture — e.g., amd64, arm64, armhf
min_price	query	number	No	Minimum price filter for paid images. 0 includes free images
max_price	query	number	No	Maximum price filter for paid images — useful for budget constraints
min_rating	query	number	No	Minimum average rating filter — includes images with rating at least this value (0–5 stars)
max_rating	query	number	No	Maximum average rating filter — includes images with rating at most this value (0–5 stars)
search	query	string	No	Search term to filter images by name, description, or tags
page	query	integer	No	Page number for pagination — starts from 1. Default: 1
limit	query	integer	No	Number of images to return per page — maximum 100 items. Default: 20
sort_by	query	string	No	Field to sort images by. Allowed values: alias, added_date, price, rating
sort_order	query	string	No	Sort direction. Allowed values: asc, desc

Request

cURL

curl -X GET "/api/v1/images/public?os=ubuntu&architecture=amd64&page=1&limit=20&sort_by=alias&sort_order=asc" \
  -H "Authorization: Bearer YOUR_TOKEN"

SDK

const publicImages = await client.api.images.listPublicIterator({
  os: "ubuntu",
  architecture: "amd64",
  page: 1,
  limit: 20,
  sort_by: "alias",
  sort_order: "asc"
});

Responses

200

{
  "statusCode": 200,
  "message": "Public images retrieved successfully",
  "data": {
    "images": [
      {
        "id": "507f1f77bcf86cd799439021",
        "alias": "ubuntu/22.04",
        "description": "Ubuntu 22.04 LTS (Jammy Jellyfish)",
        "image_name": "ubuntu-22.04-amd64",
        "architecture": "amd64",
        "os": "ubuntu",
        "release": "22.04",
        "variant": "default",
        "size": 512000000,
        "price": 0,
        "added_date": "2025-01-10T08:00:00.000Z",
        "average_rating": 4.5,
        "rating_count": 142,
        "icon_url": "/api/v1/images/507f1f77bcf86cd799439021/icon",
        "prespawn": true
      }
    ],
    "pagination": {
      "total": 87,
      "page": 1,
      "limit": 20,
      "totalPages": 5
    }
  }
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to retrieve public images"
}

---

GET /api/v1/images/public/{id}

Retrieve full details for a specific public container image, including its serial identifier and prespawn capability.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the public container image to retrieve details for

Request

cURL

curl -X GET "/api/v1/images/public/507f1f77bcf86cd799439021" \
  -H "Authorization: Bearer YOUR_TOKEN"

SDK

const details = await client.api.images.getDetails({
  id: "507f1f77bcf86cd799439021"
});

Responses

200

{
  "statusCode": 200,
  "message": "Public image details retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439021",
    "alias": "ubuntu/22.04",
    "description": "Ubuntu 22.04 LTS (Jammy Jellyfish)",
    "image_name": "ubuntu-22.04-amd64",
    "architecture": "amd64",
    "os": "ubuntu",
    "release": "22.04",
    "serial": "20250110",
    "variant": "default",
    "size": 512000000,
    "price": 0,
    "added_date": "2025-01-10T08:00:00.000Z",
    "average_rating": 4.5,
    "rating_count": 142,
    "icon_url": "/api/v1/images/507f1f77bcf86cd799439021/icon",
    "prespawn": true
  }
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Public image not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to retrieve public image details"
}

---

GET /api/v1/images/{id}/icon

Fetch the icon (PNG image) associated with a container image.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container image to retrieve icon for

Request

cURL

curl -X GET "/api/v1/images/507f1f77bcf86cd799439021/icon" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output image-icon.png

SDK

const iconBlob = await client.api.images.getIcon({
  id: "507f1f77bcf86cd799439021"
});

Responses

200

The response body is a binary PNG image (Content-Type: image/png).

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Image icon not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to retrieve image icon"
}

---

User Images

GET /api/v1/images/user

List all container images the authenticated user has imported or purchased, including the user’s own rating for each image.

Parameters

Name	In	Type	Required	Description
page	query	integer	No	Page number for pagination — starts from 1. Default: 1
limit	query	integer	No	Number of images to return per page — maximum 100 items. Default: 20
sort_by	query	string	No	Field to sort user images by — currently only supports creation date. Allowed values: created_at
sort_order	query	string	No	Sort direction. Allowed values: asc, desc

Request

cURL

curl -X GET "/api/v1/images/user?page=1&limit=20&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer YOUR_TOKEN"

SDK

const userImages = await client.api.images.listIterator({
  page: 1,
  limit: 20,
  sort_by: "created_at",
  sort_order: "desc"
});

Responses

200

{
  "statusCode": 200,
  "message": "User images retrieved successfully",
  "data": {
    "images": [
      {
        "id": "507f1f77bcf86cd799439021",
        "alias": "ubuntu/22.04",
        "description": "Ubuntu 22.04 LTS (Jammy Jellyfish)",
        "image_name": "ubuntu-22.04-amd64",
        "architecture": "amd64",
        "os": "ubuntu",
        "release": "22.04",
        "variant": "default",
        "size": 512000000,
        "price": 0,
        "user_rating": 5,
        "has_rated": true,
        "average_rating": 4.5,
        "rating_count": 142,
        "icon_url": "/api/v1/images/507f1f77bcf86cd799439021/icon",
        "prespawn": true
      }
    ],
    "pagination": {
      "total": 12,
      "page": 1,
      "limit": 20,
      "totalPages": 1
    }
  }
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to retrieve user images"
}

---

Image Lifecycle

POST /api/v1/images/import/{id}

Import a free public container image into the authenticated user’s library so it can be used to launch containers.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the public container image to import

Request

cURL

curl -X POST "/api/v1/images/import/507f1f77bcf86cd799439021" \
  -H "Authorization: Bearer YOUR_TOKEN"

SDK

const result = await client.api.images.importFree({
  id: "507f1f77bcf86cd799439021"
});

Responses

200

{
  "statusCode": 200,
  "message": "Free image imported successfully",
  "data": {}
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Image is not free or already imported"
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Image not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to import image"
}

---

POST /api/v1/images/purchase/{id}

Purchase a paid container image. The cost is deducted from the user’s balance and the image is added to their library.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the paid container image to purchase

Request

cURL

curl -X POST "/api/v1/images/purchase/507f1f77bcf86cd799439021" \
  -H "Authorization: Bearer YOUR_TOKEN"

SDK

const result = await client.api.images.purchase({
  id: "507f1f77bcf86cd799439021"
});

Responses

200

{
  "statusCode": 200,
  "message": "Image purchased successfully",
  "data": {
    "price_paid": 5.99,
    "remaining_balance": 44.01
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Insufficient balance or image already owned"
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Image not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to purchase image"
}

---

POST /api/v1/images/rate/{id}

Submit or update a rating for a container image. Ratings must be between 0 and 5 stars (decimal values allowed).

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container image to rate

Request Body

Name	Type	Required	Description
rating	number	Yes	Rating for the image from 0 to 5 stars

Request

cURL

curl -X POST "/api/v1/images/rate/507f1f77bcf86cd799439021" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rating": 5}'

SDK

const result = await client.api.images.rate({
  id: "507f1f77bcf86cd799439021",
  data: { rating: 5 }
});

Responses

200

{
  "statusCode": 200,
  "message": "Image rated successfully",
  "data": {
    "new_rating": 5,
    "average_rating": 4.6,
    "rating_count": 143
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid rating value (must be 0-5)"
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Image not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to rate image"
}