Entity Graph API

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

Creates a new entity in the realm. Requires the Collaborator role or above; members without it 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 the Collaborator role or above.

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/..."
}

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

Permanently deletes an entity and all of its associated relationships, images, and access records. Requires the Collaborator role or above. Returns 204 No Content on success.

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

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

Merges one or more source entities into a single surviving entity. The source entities are permanently deleted after the merge. Use the boolean flags to control which data is folded in from the sources. Requires the Collaborator role or above. Returns 201 Created with the surviving entity.

curl -X POST https://realmsofshod.com/api/v1/realms/clxyz.../compendium/entities/merge \
  -H "Authorization: Bearer ros_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "survivingEntityId": "ent_abc...",
    "entityIds": ["ent_def...", "ent_ghi..."],
    "mergeNotes": true,
    "mergeRelationships": true,
    "mergeAccess": true,
    "mergeImages": false
  }'

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

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

Replaces the authenticated user's private notes on an entity. Notes are per-user — each realm member maintains their own and cannot see others', including the realm's creator. Any realm member with viewer access to the entity can call this endpoint; no elevated role is required. Returns 204 No Content on success.

curl -X PATCH https://realmsofshod.com/api/v1/realms/clxyz.../compendium/entities/ent_abc.../notes \
  -H "Authorization: Bearer ros_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"notes":"First appeared in session 3. May be connected to the Silver Covenant."}'

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

Requests a presigned upload for a new entity image. This is the first of two steps — upload the file to the returned URL, then call Finalize Entity Image Upload below with the returned key. Requires the Collaborator role or above. Returns 201 Created.

curl -X POST https://realmsofshod.com/api/v1/realms/clxyz.../compendium/entities/ent_abc.../images \
  -H "Authorization: Bearer ros_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"fileType":"image/png","size":204800}'

{
  "key": "entity-image/realm_xyz.../ent_abc.../1716000000000-a1b2c3-0",
  "url": "https://storage.example.com/bucket-name",
  "fields": {
    "key": "entity-image/realm_xyz.../ent_abc.../1716000000000-a1b2c3-0",
    "Content-Type": "image/png",
    "bucketName": "bucket-name",
    "acl": "public-read"
  }
}

Upload the file directly to the returned url as a multipart form, including every entry from fields alongside the file:

curl -X POST https://storage.example.com/bucket-name \
  -F key="entity-image/realm_xyz.../ent_abc.../1716000000000-a1b2c3-0" \
  -F Content-Type="image/png" \
  -F bucketName="bucket-name" \
  -F acl="public-read" \
  -F file=@portrait.png

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

Finalizes a previously uploaded image, attaching it to the entity as the last image in its list. Call this only after the file has been uploaded to the URL returned by Request Entity Image Upload above. Requires the Collaborator role or above. Returns 200 with the new image on success.

Returns 400 if the entity already has 10 images, or 409 IMAGE_KEY_ALREADY_USED if the key has already been finalized.

curl -X PATCH https://realmsofshod.com/api/v1/realms/clxyz.../compendium/entities/ent_abc.../images \
  -H "Authorization: Bearer ros_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"key":"entity-image/realm_xyz.../ent_abc.../1716000000000-a1b2c3-0"}'

{
  "id": "img_003...",
  "order": 2,
  "imageUrl": "https://cdn.realmsofshod.com/entity-image/realm_xyz.../ent_abc.../1716000000000-a1b2c3-0"
}

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

Returns a paginated list of entities in the realm, ordered newest first. Visibility is per-entity: every member, including the realm's creator, only sees 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/relationships

Creates a new relationship between two entities. Requires the Collaborator role or above. 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 the Collaborator role or above. 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"

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
}