Realms

POST /api/v1/realms

Creates a new realm owned by the authenticated user. Returns 201 Created with the new realm object. The three gardener settings are optional and control which gardeners run for the realm.

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 or gardener settings of an existing realm. Every field is optional, but at least one must be provided. Requires the Edit Realm permission (Admin role or above); members without it receive 404 Not Found. Returns 200 with the updated realm object. See Permissions for the full role breakdown.

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","enableQuestExtraction":false}'

{
  "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.

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.

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,
  "enableEntityExtraction": true,
  "enableQuestExtraction": true,
  "enableDescriptionAutoSync": true,
  "lastActiveAt": 1716500000000,
  "users": [
    {
      "userId": "usr_abc...",
      "color": "#7c3aed",
      "createdAt": 1716000000000,
      "isStoryteller": true,
      "avatarUrl": "https://...",
      "userName": "Mordecai"
    }
  ],
  "createdAt": 1716000000000,
  "updatedAt": 1716500000000
}