API Reference
Realms
Create, update, and inspect the realms you have access to. All endpoints require a valid Bearer token. Creating a realm requires only a valid token; editing requires realm creator access.
POST /api/v1/realms
Creates a new realm owned by the authenticated user. Returns 201 Created with the new realm object.
Request Body
| Parameter | Type | Description |
|---|---|---|
| title* | string | Display name for the new realm. |
Response (201)
| Parameter | Type | Description |
|---|---|---|
| realmId* | string | ID of the newly created realm. |
| title* | string | Display name of the realm. |
| createdAt* | integer | Unix timestamp (ms) when the realm was created. |
| coverImageUrl* | string | null | Cover image URL, or null. |
| isCreator* | boolean | Always true for the creating user. |
| lastActiveAt* | integer | null | Unix timestamp (ms) of last activity, or null. |
| users* | RealmMember[] | Current realm members (initially just the creator). |
curl -X POST https://realmsofshod.com/api/v1/realms \
-H "Authorization: Bearer ros_your_token_here" \
-H "Content-Type: application/json" \
-d '{"title":"The Shattered Realm"}'{
"realmId": "clxyz...",
"title": "The Shattered Realm",
"createdAt": 1716000000000,
"coverImageUrl": null,
"isCreator": true,
"lastActiveAt": null,
"users": [
{
"userId": "usr_abc...",
"color": "#7c3aed",
"createdAt": 1716000000000,
"isStoryteller": true,
"avatarUrl": null
}
]
}PATCH /api/v1/realms/:realmId
Updates the title of an existing realm. Requires the authenticated user to be the realm creator; other members receive 404 Not Found. Returns 200 with the updated realm object.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| realmId* | string | The ID of the realm to update. You must be the realm creator. |
Request Body
| Parameter | Type | Description |
|---|---|---|
| title* | string | New display name for the realm. |
curl -X PATCH https://realmsofshod.com/api/v1/realms/clxyz... \
-H "Authorization: Bearer ros_your_token_here" \
-H "Content-Type: application/json" \
-d '{"title":"Realm of Ash and Iron"}'{
"realmId": "clxyz...",
"title": "Realm of Ash and Iron",
"createdAt": 1716000000000,
"coverImageUrl": null,
"isCreator": true,
"lastActiveAt": 1716500000000,
"users": [...]
}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
}