# Catalog API

> The plans, images, and regions a machine is created from, each selected by ID and exact version.

- [List plans](#list-plans): `GET /v1/plans`
- [List images](#list-images): `GET /v1/images`
- [List regions](#list-regions): `GET /v1/regions`

## List plans

`GET /v1/plans`

Seeded plans report their `size`; pick the one whose `backend` matches the region. See [Sizes and prices](/docs/guides/sizes-and-prices).

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | `integer` | No |  |
| `cursor` | query | `string` | No |  |
| `X-Organization-ID` | header | `string (uuid)` | No | Organization context. Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`PlanPage`](/docs/api/schemas#planpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `500` | Internal error (`internal_error`); quote the `correlation_id`. | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/plans" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "backend": "mock",
      "cpu": 0,
      "disk_gib": 0,
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "memory_mib": 0,
      "name": "small",
      "network_access": {
        "egress_options": [
          "none"
        ],
        "interactive_access": "managed_terminal",
        "public_ingress": "disabled",
        "ssh_key_selection": "unavailable"
      },
      "price": {
        "currency": "USD",
        "effective_from": "2026-01-01T00:00:00.000000Z",
        "hourly": "0.012500",
        "monthly": "9.125000"
      },
      "size": "string",
      "version": 0
    }
  ],
  "next_cursor": "string"
}
```

## List images

`GET /v1/images`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | `integer` | No |  |
| `cursor` | query | `string` | No |  |
| `X-Organization-ID` | header | `string (uuid)` | No | Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`ImagePage`](/docs/api/schemas#imagepage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/images" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "digest": "sha256:3f5a…",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "ubuntu-24.04",
      "version": 0
    }
  ],
  "next_cursor": "string"
}
```

## List regions

`GET /v1/regions`

- **API key:** `Authorization: Bearer vmy_…` with preset `read_only`, `use_existing`, `create_and_use`, `full_access`.
- **Browser session:** the `vmyard_session` cookie.
- **Who:** Any member.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | `integer` | No |  |
| `cursor` | query | `string` | No |  |
| `X-Organization-ID` | header | `string (uuid)` | No | Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| `200` | — | [`RegionPage`](/docs/api/schemas#regionpage) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/regions" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="Response 200"
{
  "items": [
    {
      "backend": "mock",
      "capacity_status": "available",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "eu-central",
      "version": 0
    }
  ],
  "next_cursor": "string"
}
```