GET /api/v1/realms/:realmId/compendium/entities

Returns a paginated list of entities in the realm, ordered newest first. Non-creator members only see entities their user ID appears in accessIds (or entities with an empty accessIds).

curl https://realmsofshod.com/api/v1/realms/clxyz.../compendium/entities \
  -H "Authorization: Bearer ros_your_token_here"

{
  "data": [
    {
      "id": "ent_abc...",
      "name": "Elara Dusk",
      "type": "character",
      "description": "A wandering mage from the eastern provinces.",
      "accessIds": [],
      "coverImageUrl": "https://cdn.realmsofshod.com/entity-image/...",
      "createdAt": 1716000000000
    }
  ],
  "nextCursor": "eyJjIjox...",
  "hasMore": true
}

GET /api/v1/realms/:realmId/compendium/entities/:entityId

Returns a single entity with its full notes and embedded relationship list. Returns 404 if the entity does not exist or the caller lacks viewer access.

curl https://realmsofshod.com/api/v1/realms/clxyz.../compendium/entities/ent_abc... \
  -H "Authorization: Bearer ros_your_token_here"

{
  "id": "ent_abc...",
  "name": "Elara Dusk",
  "type": "character",
  "description": "A wandering mage from the eastern provinces.",
  "notes": "First appeared in session 3. May be connected to the Silver Covenant.",
  "accessIds": [],
  "images": [
    { "id": "img_001...", "order": 0, "imageUrl": "https://cdn.realmsofshod.com/entity-image/..." },
    { "id": "img_002...", "order": 1, "imageUrl": "https://cdn.realmsofshod.com/entity-image/..." }
  ],
  "relationships": [
    {
      "id": "rel_xyz...",
      "type": "allied_with",
      "fromEntityId": "ent_abc...",
      "toEntityId": "ent_def...",
      "accessIds": [],
      "entity": {
        "id": "ent_def...",
        "type": "faction",
        "name": "The Silver Covenant"
      }
    }
  ],
  "createdAt": 1716000000000,
  "updatedAt": 1716500000000
}

POST /api/v1/realms/:realmId/compendium/entities

Creates a new entity in the realm. Requires the authenticated user to be the realm creator; other members receive 404. Returns 201 Created.

curl -X POST https://realmsofshod.com/api/v1/realms/clxyz.../compendium/entities \
  -H "Authorization: Bearer ros_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Elara Dusk","type":"character","description":"A wandering mage","accessIds":[]}'

{
  "id": "ent_abc...",
  "name": "Elara Dusk",
  "type": "character",
  "description": "A wandering mage",
  "accessIds": []
}

PATCH /api/v1/realms/:realmId/compendium/entities/:entityId

Updates one or more fields of an existing entity. All body fields are optional; supply only the fields you want to change. Requires realm creator access.

Returns 200 with the updated entity on success.

curl -X PATCH https://realmsofshod.com/api/v1/realms/clxyz.../compendium/entities/ent_abc... \
  -H "Authorization: Bearer ros_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"description":"Updated description"}'

{
  "id": "ent_abc...",
  "name": "Elara Dusk",
  "type": "character",
  "description": "Updated description",
  "accessIds": [],
  "coverImageUrl": "https://cdn.realmsofshod.com/entity-image/..."
}

GET /api/v1/realms/:realmId/compendium/relationships

Returns a paginated list of relationships in the realm, ordered newest first. Note that relationship rows do not include the names of the connected entities. Use the entity endpoints to resolve IDs to names.

curl https://realmsofshod.com/api/v1/realms/clxyz.../compendium/relationships \
  -H "Authorization: Bearer ros_your_token_here"

{
  "data": [
    {
      "id": "rel_xyz...",
      "type": "allied_with",
      "fromEntityId": "ent_abc...",
      "toEntityId": "ent_def...",
      "accessIds": [],
      "createdAt": 1716000000000
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

POST /api/v1/realms/:realmId/compendium/relationships

Creates a new relationship between two entities. Requires realm creator access. Returns 201 Created with the new relationship ID.

Returns 409 RELATIONSHIP_EXISTS if an identical relationship already exists, or 400 INVALID_ENTITY if either entity ID does not belong to the realm.

curl -X POST https://realmsofshod.com/api/v1/realms/clxyz.../compendium/relationships \
  -H "Authorization: Bearer ros_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"type":"allied_with","fromEntityId":"ent_abc...","toEntityId":"ent_def...","accessIds":[]}'

{ "id": "rel_xyz..." }

DELETE /api/v1/realms/:realmId/compendium/relationships/:relationshipId

Permanently deletes a relationship. Requires realm creator access. Returns 204 No Content with an empty body on success.

curl -X DELETE https://realmsofshod.com/api/v1/realms/clxyz.../compendium/relationships/rel_xyz... \
  -H "Authorization: Bearer ros_your_token_here"