Container Images

Browse the public image catalog, manage images you have imported or purchased, and rate images. Use these endpoints to discover available images, retrieve metadata, import free images, purchase paid images, and submit ratings.

Public Images

Discover and inspect images available in the Hoody public catalog.

GET /api/v1/images/public

List public container images with rich filtering, search, and pagination.

cURL

curl -X GET "https://api.hoody.icu/api/v1/images/public?os=ubuntu&architecture=amd64&min_rating=4&search=ubuntu&page=1&limit=20&sort_by=alias&sort_order=asc" \
  -H "Authorization: Bearer <token>"

SDK

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

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

Response 500

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

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

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

Retrieve full details for a single public container image by its identifier.

cURL

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

SDK

await client.api.images.getDetails("507f1f77bcf86cd799439021");

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

Response 404

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

Response 500

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

Parameters

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

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

Fetch the PNG icon asset for a container image.

cURL

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

SDK

await client.api.images.getIcon("507f1f77bcf86cd799439021");

Response 200

binary PNG payload

Response 404

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

Response 500

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

Parameters

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

Note

The successful response is a binary PNG image. Render or stream the response body directly rather than parsing it as JSON.

User Images

List images the authenticated user has imported or purchased.

GET /api/v1/images/user

List the authenticated user’s imported and purchased container images with pagination.

cURL

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

SDK

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

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

Response 401

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

Response 500

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

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. Allowed values: created_at
sort_order	query	string	No	Sort direction. Allowed values: asc, desc

Tip

The user_rating and has_rated fields on each result reflect the calling user’s own rating (if any), so you can render a personalized star control in the UI.

Image Actions

Import free images, purchase paid images, and submit ratings.

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

Import a free public container image into the authenticated user’s library.

cURL

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

SDK

await client.api.images.importFree("507f1f77bcf86cd799439021");

Response 200

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

Response 400

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

Response 401

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

Response 404

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

Response 500

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

Parameters

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

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

Purchase a paid container image. The price is deducted from the user’s account balance.

cURL

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

SDK

await client.api.images.purchase("507f1f77bcf86cd799439099");

Response 200

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

Response 400

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

Response 401

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

Response 404

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

Response 500

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

Parameters

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

Caution

A successful purchase is final. The price_paid and remaining_balance fields in the response confirm the deducted cost and the user’s new balance.

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

Submit a rating for a container image. Updates both the user’s rating and the public average.

Request Body

Name	Type	Required	Description
rating	number	Yes	Rating for the image, between 0 and 5 stars

cURL

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

SDK

await client.api.images.rate("507f1f77bcf86cd799439021", {
  rating: 5,
});

Response 200

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

Response 400

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

Response 401

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

Response 404

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

Response 500

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

Parameters

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

Note

The rating field must be a number in the inclusive range 0 to 5. Fractional values such as 4.5 are accepted.