API Reference
Sessions & Transcriptions
Browse sessions and read transcriptions. All endpoints require a valid Bearer token and realm membership.
GET /api/v1/realms/:realmId/sessions
Returns a paginated list of sessions in the realm, ordered by start time newest first.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| realmId* | string | The realm ID. |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Number of results per page. Default: 50, maximum: 100. |
| cursor | string | Opaque pagination cursor from the previous response. Omit to start from the first page. |
Response
| Parameter | Type | Description |
|---|---|---|
| data* | Session[] | Array of session objects for this page. |
| nextCursor* | string | null | Cursor for the next page, or null on the last page. |
| hasMore* | boolean | True when additional pages exist. |
Session
| Parameter | Type | Description |
|---|---|---|
| id* | string | Unique session identifier. |
| startedAt* | integer | Unix timestamp (ms) when the session started. |
| endedAt* | integer | null | Unix timestamp (ms) when the session ended, or null if still active. |
| title | string | null | Session title, or null if not set. |
| shortSummary | string | null | Brief AI-generated summary, or null. |
| fullSummary | string | null | Full AI-generated summary, or null. |
| discordGuildId | string | null | Discord server ID if the session was linked to Discord, or null. |
| discordChannelId | string | null | Discord channel ID if the session was linked to Discord, or null. |
curl https://realmsofshod.com/api/v1/realms/clxyz.../sessions \
-H "Authorization: Bearer ros_your_token_here"{
"data": [
{
"id": "ses_abc...",
"startedAt": 1716000000000,
"endedAt": 1716010800000,
"title": "The Fall of Ashenveil",
"shortSummary": "The party uncovered the cult's true motives.",
"fullSummary": null,
"discordGuildId": null,
"discordChannelId": null
}
],
"nextCursor": "eyJzIjox...",
"hasMore": true
}GET /api/v1/realms/:realmId/sessions/:sessionId
Returns detailed information about a single session, including its scene breakdown and summary if available.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| realmId* | string | The realm ID. |
| sessionId* | string | The session ID. |
Response
| Parameter | Type | Description |
|---|---|---|
| id* | string | Unique session identifier. |
| realmId* | string | ID of the realm this session belongs to. |
| startedAt* | integer | Unix timestamp (ms) when the session started. |
| endedAt* | integer | null | Unix timestamp (ms) when the session ended, or null. |
| scenes* | Scene[] | Ordered list of scenes within the session. |
| summary* | SessionSummary | null | AI-generated summary, or null if not available. |
Scene
| Parameter | Type | Description |
|---|---|---|
| id* | string | Scene identifier. |
| shortTitle* | string | Brief scene title. |
| longTitle* | string | Full scene title. |
| start* | integer | Unix timestamp (ms) when the scene started. |
| end* | integer | Unix timestamp (ms) when the scene ended. |
SessionSummary
| Parameter | Type | Description |
|---|---|---|
| title* | string | Summary title. |
| shortSummary* | string | Brief summary. |
| fullSummary* | string | Full summary text. |
curl https://realmsofshod.com/api/v1/realms/clxyz.../sessions/ses_abc... \
-H "Authorization: Bearer ros_your_token_here"{
"id": "ses_abc...",
"realmId": "clxyz...",
"startedAt": 1716000000000,
"endedAt": 1716010800000,
"scenes": [
{
"id": "scn_001...",
"shortTitle": "The Ambush",
"longTitle": "Ambush on the Ashenveil Road",
"start": 1716000000000,
"end": 1716003600000
}
],
"summary": {
"title": "The Fall of Ashenveil",
"shortSummary": "The party uncovered the cult's true motives.",
"fullSummary": "After a tense confrontation at the old mill, the adventurers discovered that the Ashenveil cult had been secretly supplying weapons to the regional governor."
}
}GET /api/v1/realms/:realmId/sessions/:sessionId/transcriptions
Returns a paginated list of transcription segments for a session. Unlike other list endpoints, transcriptions are ordered oldest first (ascending by start time) so you can reconstruct the session chronologically by walking pages in order.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| realmId* | string | The realm ID. |
| sessionId* | string | The session ID. |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Number of results per page. Default: 50, maximum: 100. |
| cursor | string | Opaque pagination cursor from the previous response. Omit to start from the beginning of the session. |
Response
| Parameter | Type | Description |
|---|---|---|
| data* | Transcription[] | Array of transcription segments for this page. |
| nextCursor* | string | null | Cursor for the next page, or null when there are no more segments. |
| hasMore* | boolean | True when additional pages exist. |
Transcription
| Parameter | Type | Description |
|---|---|---|
| id* | string | Unique transcription identifier. |
| realmId* | string | ID of the realm. |
| realmSessionId* | string | ID of the session this transcription belongs to. |
| userId* | string | null | ID of the user who spoke, or null if unknown. |
| ownerTitle* | string | null | Display name of the speaker at time of recording, or null. |
| text* | string | Transcribed speech text. |
| startedAt* | integer | Unix timestamp (ms) when this segment started. |
| endedAt* | integer | Unix timestamp (ms) when this segment ended. |
Pass nextCursor as the cursor query parameter to fetch the next page. Cursors are opaque; treat them as strings and do not parse their contents.
curl https://realmsofshod.com/api/v1/realms/clxyz.../sessions/ses_abc.../transcriptions \
-H "Authorization: Bearer ros_your_token_here"{
"data": [
{
"id": "trn_xyz...",
"realmId": "clxyz...",
"realmSessionId": "ses_abc...",
"userId": "usr_abc...",
"ownerTitle": "Mordecai",
"text": "We ride at dawn.",
"startedAt": 1716000000000,
"endedAt": 1716000003500
}
],
"nextCursor": "eyJzIjox...",
"hasMore": true
}