# Container Images

**Page:** api/container-images

[Download Raw Markdown](./api/container-images.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## 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` |



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


```typescript
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"
});
```


```json
{
  "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
    }
  }
}
```


```json
{
  "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 |



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


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


```json
{
  "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
  }
}
```


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


```json
{
  "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 |



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


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


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


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


```json
{
  "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` |



```bash
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
const result = await client.api.images.listIterator({
  page: 1,
  limit: 20,
  sort_by: "created_at",
  sort_order: "desc"
});
```


```json
{
  "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
    }
  }
}
```


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


```json
{
  "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 |



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


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


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


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


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


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


```json
{
  "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 |



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


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


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


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


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


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


```json
{
  "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 |



```bash
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
const result = await client.api.images.rate({
  id: "507f1f77bcf86cd799439021",
  data: {
    rating: 5
  }
});
```


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


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


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


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


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




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.