API reference

Catalog API

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

View as Markdown

List plans: GET /v1/plans
List images: GET /v1/images
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.

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`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`500`	Internal error (`internal_error`); quote the `correlation_id`.	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/plans" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

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`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/images" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

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`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/regions" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

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