Container Images

The Container Images API provides endpoints for browsing the public image catalog, managing images that have been imported or purchased by the authenticated user, and performing image-level actions such as importing, purchasing, and rating. Use these endpoints to discover base images for container deployments, retrieve icon assets, and interact with image metadata.

---

Public Images

GET /api/v1/images/public

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

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 - filters images with rating ≥ this value (0-5 stars)
max_rating	query	number	No	Maximum average rating filter - filters images with rating ≤ 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

cURL

curl -X GET "https://api.hoody.com/api/v1/images/public?os=ubuntu&architecture=amd64&min_price=0&max_price=10&page=1&limit=20&sort_by=added_date&sort_order=desc" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.api.images.listPublicIterator({
  os: "ubuntu",
  architecture: "amd64",
  min_price: 0,
  max_price: 10,
  page: 1,
  limit: 20,
  sort_by: "added_date",
  sort_order: "desc"
});

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}

Get details of a specific public container image, including its full metadata, pricing, and rating statistics.

Parameters

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

cURL

curl -X GET "https://api.hoody.com/api/v1/images/public/507f1f77bcf86cd799439021" \
  -H "Authorization: Bearer <token>"

SDK

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

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

Retrieve the PNG icon associated with a container image. The response body is a binary image.

Parameters

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

cURL

curl -X GET "https://api.hoody.com/api/v1/images/507f1f77bcf86cd799439021/icon" \
  -H "Authorization: Bearer <token>" \
  -o image-icon.png

SDK

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

200

The response body is a binary PNG image (Content-Type: image/png). The body contains the raw image bytes — there is no JSON payload to parse.

<binary PNG data>

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 container images that the authenticated user has imported or purchased. Results are paginated.

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

cURL

curl -X GET "https://api.hoody.com/api/v1/images/user?page=1&limit=20&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer <token>"

SDK

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

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 Actions

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

Import a free public container image into the authenticated user’s account so it can be used for deployments.

Parameters

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

cURL

curl -X POST "https://api.hoody.com/api/v1/images/import/507f1f77bcf86cd799439021" \
  -H "Authorization: Bearer <token>"

SDK

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

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 authenticated user’s account balance.

Parameters

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

cURL

curl -X POST "https://api.hoody.com/api/v1/images/purchase/507f1f77bcf86cd799439021" \
  -H "Authorization: Bearer <token>"

SDK

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

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 a rating (0-5 stars) for a container image. Each call updates the user’s existing rating and recomputes the average.

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

cURL

curl -X POST "https://api.hoody.com/api/v1/images/rate/507f1f77bcf86cd799439021" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5
  }'

SDK

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

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

Note

The rating value must be a number between 0 and 5 inclusive. Submitting fractional values is allowed but the server may round or truncate the value before persisting it.