Realms (API Isolation)

Overview

The Realms endpoint returns the unique realm identifiers (24-character hexadecimal strings) associated with your projects, containers, servers, and auth tokens. Realms provide API isolation and multi-tenant organization — each resource belongs to a realm, and you can scope operations to a specific realm. This endpoint requires the resources.realms permission.

List realm IDs

`GET /api/v1/realms/`

Returns a deduplicated list of realm_id values found across your resources. Use this to discover which realms your resources belong to before making realm-scoped requests.

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 data. Default: `false`

Response

{
  "statusCode": 200,
  "message": "Realm IDs retrieved successfully",
  "data": {
    "realm_ids": [
      "507f1f77bcf86cd799439011",
      "507f1f77bcf86cd799439012"
    ],
    "total": 2
  }
}

When called with include_usage=true, each entry in data.usage contains resource counts:

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

Field	Type	Description
`statusCode`	number	HTTP status code (200)
`message`	string	Human-readable success message
`data.realm_ids`	array	Unique 24-hex realm identifiers found in your resources
`data.total`	number	Total number of unique realms
`data.usage`	object	Resource counts per realm (only present when `include_usage=true`)

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

Error Code	Title	Description	Resolution
`UNAUTHORIZED`	Authentication required	No valid authentication credentials provided	Provide a valid JWT 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

SDK usage

The SDK method api.realms.list takes a single positional boolean argument. Pass true to include resource usage counts, or omit the argument entirely when usage is not required.

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

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

console.log(realms.data.total);
console.log(realmsWithUsage.data.usage);

cURL

curl -X GET "https://api.hoody.com/api/v1/realms/" \
  -H "Authorization: Bearer <token>"

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