API Reference
Realms
List and inspect the realms you have access to. All endpoints require a valid Bearer token and return realm data for the authenticated user only.
GET /api/v1/realms
Returns a paginated list of realms the authenticated user is a member of, ordered newest first.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Number of results per page. Default: 50. Values above 100 are clamped to 100. Returns 400 if not a positive integer. |
| cursor | string | Opaque pagination cursor returned in nextCursor from the previous response. Omit to start from the first page. |
Response
| Parameter | Type | Description |
|---|---|---|
| data* | Realm[] | Array of realm objects for this page. |
| nextCursor* | string | null | Cursor to pass as cursor in the next request. null when there are no more pages. |
| hasMore* | boolean | True when additional pages exist. |
Realm
| Parameter | Type | Description |
|---|---|---|
| id* | string | Unique realm identifier. |
| title* | string | Display name of the realm. |
| createdAt* | integer | Unix timestamp (milliseconds) when the realm was created. |
| coverImageUrl* | string | null | URL of the realm cover image, or null if none is set. |
| creatorId* | string | User ID of the realm creator. |
curl https://realmsofshod.com/api/v1/realms \
-H "Authorization: Bearer ros_your_token_here"{
"data": [
{
"id": "clxyz...",
"title": "The Shattered Realm",
"createdAt": 1716000000000,
"coverImageUrl": "https://...",
"creatorId": "usr_abc..."
}
],
"nextCursor": "eyJjIjox...",
"hasMore": true
}Pass the nextCursor value as the cursor query parameter to fetch the next page. Cursors are opaque; treat them as strings and do not parse their contents.
GET /api/v1/realms/:realmId
Returns detailed information about a single realm. You must be a member of the realm; non-members receive 404 Not Found.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| realmId* | string | The ID of the realm to retrieve. Must be a realm you are a member of. |
Response
| Parameter | Type | Description |
|---|---|---|
| id* | string | Unique realm identifier. |
| creatorId* | string | User ID of the realm creator. |
| title* | string | Display name of the realm. |
| coverImageUrl* | string | null | Cover image URL, or null. |
| enableVideo* | boolean | Whether video is enabled for this realm. |
| allowPartyInvites* | boolean | Whether players can invite others. |
| lastActiveAt* | integer | null | Unix timestamp (ms) of last activity, or null. |
| users* | RealmMember[] | List of realm members. See RealmMember below. |
| createdAt* | integer | Unix timestamp (ms) when the realm was created. |
| updatedAt* | integer | Unix timestamp (ms) when the realm was last updated. |
RealmMember
| Parameter | Type | Description |
|---|---|---|
| userId* | string | The member's user ID. |
| color* | string | The member's color in the realm (hex). |
| createdAt* | integer | Unix timestamp (ms) when the member joined. |
| isStoryteller* | boolean | True if the member has Storyteller access. |
| avatarUrl | string | null | The member's avatar URL, or null. |
| streamedAt | integer | null | Unix timestamp (ms) of the member's last stream, or null. |
| connectedAt | integer | null | Unix timestamp (ms) when the member last connected, or null. |
| userName | string | null | The member's display name, or null. |
| realmName | string | null | The member's in-realm name, or null. |
Member email addresses and avatar keys are not included in the response.
curl https://realmsofshod.com/api/v1/realms/clxyz... \
-H "Authorization: Bearer ros_your_token_here"{
"id": "clxyz...",
"creatorId": "usr_abc...",
"title": "The Shattered Realm",
"coverImageUrl": "https://...",
"enableVideo": true,
"allowPartyInvites": false,
"lastActiveAt": 1716500000000,
"users": [
{
"userId": "usr_abc...",
"color": "#7c3aed",
"createdAt": 1716000000000,
"isStoryteller": true,
"avatarUrl": "https://...",
"userName": "Mordecai"
}
],
"createdAt": 1716000000000,
"updatedAt": 1716500000000
}