API Reference
Notes API
Create and manage notes in your realm. All realm members can read notes they have been granted access to; only the realm creator can create, update, or delete notes.
GET /api/v1/realms/:realmId/compendium/notes
Returns a paginated list of notes the authenticated user has access to, ordered by most recently updated. Note text is not included in list results — use the Get Note endpoint to retrieve the full content. Any realm member can call this endpoint.
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* | NoteStub[] | Array of note 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. |
NoteStub
| Parameter | Type | Description |
|---|---|---|
| id* | string | Unique note identifier. |
| name* | string | Display name of the note. |
| accessIds* | string[] | User IDs that have viewer access to this note. |
| updatedAt* | integer | Unix timestamp (ms) when the note was last updated. |
curl https://realmsofshod.com/api/v1/realms/clxyz.../compendium/notes \
-H "Authorization: Bearer ros_your_token_here"{
"data": [
{
"id": "note_abc...",
"name": "Session 3 Recap",
"accessIds": ["user_def..."],
"updatedAt": 1716500000000
}
],
"nextCursor": null,
"hasMore": false
}GET /api/v1/realms/:realmId/compendium/notes/:noteId
Returns a single note including its full text. Returns 404 if the note does not exist or the caller lacks viewer access. Any realm member with access to the note can call this endpoint.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| realmId* | string | The realm ID. |
| noteId* | string | The note ID. |
Response
| Parameter | Type | Description |
|---|---|---|
| id* | string | Unique note identifier. |
| name* | string | Display name of the note. |
| text* | string | Full text content of the note (may be empty string). |
| accessIds* | string[] | User IDs that have viewer access to this note. |
| updatedAt* | integer | Unix timestamp (ms) when the note was last updated. |
curl https://realmsofshod.com/api/v1/realms/clxyz.../compendium/notes/note_abc... \
-H "Authorization: Bearer ros_your_token_here"{
"id": "note_abc...",
"name": "Session 3 Recap",
"text": "The party arrived at Thornhaven and met the innkeeper...",
"accessIds": ["user_def..."],
"updatedAt": 1716500000000
}POST /api/v1/realms/:realmId/compendium/notes
Creates a new note in the realm. Requires the authenticated user to be the realm creator; other members receive 404. The creator is automatically added to the access list. Returns 201 Created.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| realmId* | string | The realm ID. |
Request Body
| Parameter | Type | Description |
|---|---|---|
| name* | string | Display name of the note. |
| text | string | null | Note content. Pass null or omit to create an empty note. |
| accessIds | string[] | User IDs to grant viewer access. Pass an empty array or omit to create a private note. |
Response (201)
| Parameter | Type | Description |
|---|---|---|
| id* | string | Unique note identifier. |
| name* | string | Display name of the note. |
| text* | string | Full text content of the note (may be empty string). |
| accessIds* | string[] | User IDs that have viewer access to this note. |
| updatedAt* | integer | Unix timestamp (ms) when the note was last updated. |
curl -X POST https://realmsofshod.com/api/v1/realms/clxyz.../compendium/notes \
-H "Authorization: Bearer ros_your_token_here" \
-H "Content-Type: application/json" \
-d '{"name":"Session 3 Recap","text":"The party arrived at Thornhaven...","accessIds":["user_def..."]}'{
"id": "note_abc...",
"name": "Session 3 Recap",
"text": "The party arrived at Thornhaven...",
"accessIds": ["user_def..."],
"updatedAt": 1716500000000
}PATCH /api/v1/realms/:realmId/compendium/notes/:noteId
Updates one or more fields of an existing note. All body fields are optional; supply only the fields you want to change. Requires realm creator access. Returns 200 with the updated note on success.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| realmId* | string | The realm ID. |
| noteId* | string | The note ID. |
Request Body
| Parameter | Type | Description |
|---|---|---|
| name | string | New display name. Omit to keep the current value. |
| text | string | null | New content, null to clear it, or omit to keep the current value. |
| accessIds | string[] | Replacement access list. Omit to keep the current value. |
Response
| Parameter | Type | Description |
|---|---|---|
| id* | string | Unique note identifier. |
| name* | string | Display name of the note. |
| text* | string | Full text content of the note (may be empty string). |
| accessIds* | string[] | User IDs that have viewer access to this note. |
| updatedAt* | integer | Unix timestamp (ms) when the note was last updated. |
curl -X PATCH https://realmsofshod.com/api/v1/realms/clxyz.../compendium/notes/note_abc... \
-H "Authorization: Bearer ros_your_token_here" \
-H "Content-Type: application/json" \
-d '{"text":"Updated session recap text."}'{
"id": "note_abc...",
"name": "Session 3 Recap",
"text": "Updated session recap text.",
"accessIds": ["user_def..."],
"updatedAt": 1716600000000
}DELETE /api/v1/realms/:realmId/compendium/notes/:noteId
Permanently deletes a note. Requires realm creator access. Returns 204 No Content on success.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| realmId* | string | The realm ID. |
| noteId* | string | The note ID. |
curl -X DELETE https://realmsofshod.com/api/v1/realms/clxyz.../compendium/notes/note_abc... \
-H "Authorization: Bearer ros_your_token_here"