Realms (API Isolation)

A realm is a 24-hexadecimal identifier used by Hoody to group resources (projects, containers, servers, auth tokens) under a shared multi-tenant boundary. This endpoint returns the deduplicated set of realm_id values found across the resources your token can access. Use it to discover which realms your account touches and, optionally, how many resources you have in each one.

All realm operations require the resources.realms permission on the calling token.

`GET /api/v1/realms/`

Retrieve every unique realm_id referenced by your projects, containers, server pool memberships, and realm-scoped auth tokens. When include_usage=true, the response also includes per-realm counts of each resource type.

Parameters

Name	In	Type	Required	Description
`include_usage`	query	boolean	No	Include resource counts per `realm_id` (projects, containers, servers, auth tokens). Adds a `usage` object to the response. Defaults to `false`.

This endpoint accepts no request body.

curl -X GET "https://api.hoody.icu/api/v1/realms/?include_usage=true" \
  -H "Authorization: Bearer <token>"

// With usage counts
const result = await client.api.realms.list(true);

// Without usage counts
const minimal = await client.api.realms.list();

{
  "statusCode": 200,
  "message": "Realm IDs retrieved successfully",
  "data": {
    "realm_ids": [
      "507f1f77bcf86cd799439011",
      "507f1f77bcf86cd799439012"
    ],
    "total": 2,
    "usage": {
      "507f1f77bcf86cd799439011": {
        "projects": 2,
        "containers": 15,
        "servers": 1,
        "auth_tokens": 1
      },
      "507f1f77bcf86cd799439012": {
        "projects": 1,
        "containers": 8,
        "servers": 0,
        "auth_tokens": 0
      }
    }
  }
}

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

Error Code	Title	Description	Resolution
`UNAUTHORIZED`	Authentication required	No valid authentication credentials provided	Provide a valid JWT token or auth token in the `Authorization` header

{
  "statusCode": 403,
  "error": "PERMISSION_DENIED",
  "message": "This token does not have permission: resources.realms"
}

Error Code	Title	Description	Resolution
`PERMISSION_DENIED`	Permission denied	Auth token does not have the `resources.realms` permission	Recreate the token with the `full_access` template, or explicitly add `resources.realms: true` to the token’s permissions