# Realms (API Isolation)

**Page:** api/realms

[Download Raw Markdown](./api/realms.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Realms (API Isolation)

The Realms API lets you discover the multi-tenant realms (identified by 24-hexadecimal strings) that your resources belong to. Use these endpoints to audit which realms your projects, containers, servers, and auth tokens are associated with.

This page covers the **List Realms** endpoint, which returns a deduplicated list of realm identifiers found across your resources. Requires the `resources.realms` permission.

### List Realms

`GET /api/v1/realms/`

Returns all unique `realm_id` values found in your projects, containers, servers (via pool memberships), and auth tokens. The response is a deduplicated list of 24-hexadecimal realm identifiers that your resources belong to.

Pass `include_usage=true` to also receive a per-realm count of projects, containers, servers, and auth tokens.

#### 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` |

#### Request

This endpoint accepts no request body.


  
```bash
curl -X GET "https://api.hoody.com/api/v1/realms/?include_usage=true" \
  -H "Authorization: Bearer <token>"
```
  
  
```javascript
const { data } = await client.api.realms.list({ include_usage: true });
```
  


#### Response

**200 — Success**


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

The `usage` object is only present when `include_usage=true` is passed in the query string.
  


**401 — Unauthorized**


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

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


**403 — Permission Denied**


  
```json
{
  "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 `resources.realms` permission | Recreate token with `full_access` template or explicitly add `resources.realms: true` to token permissions |