API Reference

Notes API

Create and manage notes in your realm. All realm members can read notes they have been granted access to. Creating a note requires the Collaborator role or above; updating or deleting a note is restricted to the note's own creator, though Admins and Owners can also delete any note.

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 Collaborator role or above (see Permissions); members without it receive 404. The creating user is automatically added to the access list and becomes the note's owner. 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. Restricted to the note's own creator. There is no Admin or Owner override for editing someone else's note. 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. Restricted to the note's own creator, or a realm Admin or Owner. 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"

← Previous: Entity Graph API Next Sessions API →

Notes API

List Notes

Get Note

Create Note

Update Note

Delete Note