Realms (API Isolation)

The Realms endpoint returns every unique realm identifier that your projects, containers, servers (via pool memberships), and auth tokens belong to. Realms are 24-character hexadecimal tenant isolation labels used to organize multi-tenant resources on the Hoody platform. Use this endpoint to discover which realms your account spans, and optionally include usage counts to see how many resources live in each one.

The calling token must carry the resources.realms permission.

List your realm IDs

GET /api/v1/realms/

Returns a deduplicated list of 24-hex realm identifiers found across the caller’s projects, containers, servers, and auth tokens. When include_usage=true, each realm is annotated with a usage object containing resource counts.

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

Response

200

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

When include_usage=true, the data object also contains a usage object keyed by realm_id:

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

401

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

403

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

Example request

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.realms.list(true);