Container Images

The Container Images API provides access to the public image catalog, the images a user has imported or purchased, and the actions available on those images. Use these endpoints to discover base images when provisioning containers, retrieve icon assets, import a free image, purchase a paid image, or submit a star rating.

Browsing images

GET /api/v1/images/public

Get a paginated list of public container images. Supports filtering by operating system, architecture, price range, rating range, and free-text search.

Parameters

Name	In	Type	Required	Description
os	query	string	No	Filter images by operating system - e.g., debian (the platform currently carries debian/13 only)
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 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

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

for await (const image of client.api.images.listPublicIterator({ os: 'debian', architecture: 'amd64', page: 1, limit: 20, sort_by: 'added_date', sort_order: 'desc' })) {
  console.log(image);
}

200

{
  "statusCode": 200,
  "message": "Public images retrieved successfully",
  "data": {
    "images": [
      {
        "id": "507f1f77bcf86cd799439021",
        "alias": "debian/13",
        "description": "Debian 13 (Trixie) - Default base image",
        "image_name": "debian/13",
        "architecture": "amd64",
        "os": "debian",
        "release": "13",
        "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 for a single public container image.

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

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

200

{
  "statusCode": 200,
  "message": "Public image details retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439021",
    "alias": "debian/13",
    "description": "Debian 13 (Trixie) - Default base image",
    "image_name": "debian/13",
    "architecture": "amd64",
    "os": "debian",
    "release": "13",
    "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 icon for a container image. The response is always a PNG; a generic placeholder PNG is returned when the image has no icon, is not public, or does not exist.

Note

This endpoint always responds with HTTP 200 and a PNG body, even when the requested image does not exist or is not public. A generic placeholder PNG is served in those cases. Use the 422 response only to detect IDs that fail the 24-character hexadecimal validation.

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>" \
  --output icon.png

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

const icon = await client.api.images.getIcon('507f1f77bcf86cd799439021');

200

The response body is a binary PNG image. A generic placeholder PNG is returned when the image has no icon, is not public, or does not exist.

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid icon format"
}

422

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "params/id must match pattern \"^[0-9a-f]{24}$\""
}

500

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

Your images

GET /api/v1/images/user

List the container images that the authenticated user has imported or purchased.

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

for await (const image of client.api.images.listIterator({ page: 1, limit: 20, sort_by: 'created_at', sort_order: 'desc' })) {
  console.log(image);
}

200

{
  "statusCode": 200,
  "message": "User images retrieved successfully",
  "data": {
    "images": [
      {
        "id": "507f1f77bcf86cd799439021",
        "alias": "debian/13",
        "description": "Debian 13 (Trixie) - Default base image",
        "image_name": "debian/13",
        "architecture": "amd64",
        "os": "debian",
        "release": "13",
        "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"
}

Managing images

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

Import a free public container image into the authenticated user’s account. The image must have a price of 0 and must not already be owned by the caller.

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.images.importFree('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 public container image. The cost is deducted from the authenticated user’s balance and the image becomes available in the user image list.

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.images.purchase('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 star rating (0-5) for a container image. The response includes the rating that was just submitted, the new average rating, and the total number of ratings.

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.images.rate('507f1f77bcf86cd799439021', { 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"
}