Quests API

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

Returns a paginated list of quests the authenticated user has access to, ordered by most recently updated. Filter by status or entityId to narrow the results. Any realm member can call this endpoint.

curl https://realmsofshod.com/api/v1/realms/clxyz.../compendium/quests?status=active \
  -H "Authorization: Bearer ros_your_token_here"

{
  "data": [
    {
      "id": "quest_abc...",
      "realmId": "realm_xyz...",
      "title": "The Silver Locket",
      "hook": "A merchant offers coin for a locket lost in the sewers.",
      "goalTitle": "Recover the locket",
      "goalDescription": "Bring the locket back to the merchant.",
      "rewardTitle": "50 gold",
      "rewardDescription": "Paid on delivery.",
      "mechanic": "fetch",
      "motive": "wealth",
      "source": "commission",
      "isPublicToRealm": true,
      "accessIds": [],
      "entityIds": ["ent_def..."],
      "steps": [],
      "status": "proposed",
      "originSceneId": null,
      "createdAt": 1716500000000,
      "updatedAt": 1716500000000
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

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

Creates a new quest in the realm with an empty step timeline. Requires the Collaborator role or above; members without it receive 404. The creating user is automatically added to the access list unless the quest is public to the realm. Returns 201 Created.

curl -X POST https://realmsofshod.com/api/v1/realms/clxyz.../compendium/quests \
  -H "Authorization: Bearer ros_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "The Silver Locket",
    "hook": "A merchant offers coin for a locket lost in the sewers.",
    "goalTitle": "Recover the locket",
    "goalDescription": "Bring the locket back to the merchant.",
    "reward": {"title": "50 gold", "description": "Paid on delivery."},
    "mechanic": "fetch",
    "motive": "wealth",
    "source": "commission",
    "entityIds": [],
    "isPublicToRealm": true,
    "accessIds": []
  }'

{
  "id": "quest_abc...",
  "realmId": "realm_xyz...",
  "title": "The Silver Locket",
  "hook": "A merchant offers coin for a locket lost in the sewers.",
  "goalTitle": "Recover the locket",
  "goalDescription": "Bring the locket back to the merchant.",
  "rewardTitle": "50 gold",
  "rewardDescription": "Paid on delivery.",
  "mechanic": "fetch",
  "motive": "wealth",
  "source": "commission",
  "isPublicToRealm": true,
  "accessIds": [],
  "entityIds": [],
  "steps": [],
  "status": "proposed",
  "originSceneId": null,
  "createdAt": 1716500000000,
  "updatedAt": 1716500000000
}

GET /api/v1/realms/:realmId/compendium/quests/:questId

Returns a single quest, including its full step timeline. Returns 404 if the quest does not exist or the caller lacks viewer access. Any realm member with access to the quest can call this endpoint.

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

{
  "id": "quest_abc...",
  "realmId": "realm_xyz...",
  "title": "The Silver Locket",
  "hook": "A merchant offers coin for a locket lost in the sewers.",
  "goalTitle": "Recover the locket",
  "goalDescription": "Bring the locket back to the merchant.",
  "rewardTitle": "50 gold",
  "rewardDescription": "Paid on delivery.",
  "mechanic": "fetch",
  "motive": "wealth",
  "source": "commission",
  "isPublicToRealm": true,
  "accessIds": [],
  "entityIds": ["ent_def..."],
  "steps": [
    {
      "id": "step_001...",
      "type": "discovery",
      "note": "The party learned the locket fell into the sewer grate on Mill Street.",
      "sceneId": null,
      "createdAt": 1716550000000,
      "updatedAt": 1716550000000
    }
  ],
  "status": "active",
  "originSceneId": null,
  "createdAt": 1716500000000,
  "updatedAt": 1716550000000
}

PATCH /api/v1/realms/:realmId/compendium/quests/:questId

Updates one or more fields of an existing quest, including its visibility. All body fields are optional; supply only the fields you want to change. Requires the Collaborator role or above; there is no restriction to the quest's own creator. Returns 200 with the updated quest on success.

curl -X PATCH https://realmsofshod.com/api/v1/realms/clxyz.../compendium/quests/quest_abc... \
  -H "Authorization: Bearer ros_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"goalDescription":"Bring the locket back to the merchant before nightfall."}'

{
  "id": "quest_abc...",
  "realmId": "realm_xyz...",
  "title": "The Silver Locket",
  "hook": "A merchant offers coin for a locket lost in the sewers.",
  "goalTitle": "Recover the locket",
  "goalDescription": "Bring the locket back to the merchant before nightfall.",
  "rewardTitle": "50 gold",
  "rewardDescription": "Paid on delivery.",
  "mechanic": "fetch",
  "motive": "wealth",
  "source": "commission",
  "isPublicToRealm": true,
  "accessIds": [],
  "entityIds": ["ent_def..."],
  "steps": [],
  "status": "proposed",
  "originSceneId": null,
  "createdAt": 1716500000000,
  "updatedAt": 1716600000000
}

DELETE /api/v1/realms/:realmId/compendium/quests/:questId

Permanently deletes a quest and its step timeline. Requires the Collaborator role or above. Returns 204 No Content on success.

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

POST /api/v1/realms/:realmId/compendium/quests/:questId/steps

Adds a step to the end of a quest's timeline. Requires the Collaborator role or above. Returns 400 if the quest already has an ending step (completed, failed, or abandoned). A quest can have at most one ending step, and it must be the last one. Returns 201 Created with the full updated quest.

curl -X POST https://realmsofshod.com/api/v1/realms/clxyz.../compendium/quests/quest_abc.../steps \
  -H "Authorization: Bearer ros_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"type":"completed","note":"The party returned the locket and collected their reward."}'

PATCH /api/v1/realms/:realmId/compendium/quests/:questId/steps/:stepId

Updates one or more fields of an existing step. Both body fields are optional; supply only the fields you want to change. Only the latest step on the timeline can be changed into an ending step. Requires the Collaborator role or above. Returns 200 with the full updated quest on success.

curl -X PATCH https://realmsofshod.com/api/v1/realms/clxyz.../compendium/quests/quest_abc.../steps/step_001... \
  -H "Authorization: Bearer ros_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"note":"The party learned the locket fell through a grate on Mill Street."}'

DELETE /api/v1/realms/:realmId/compendium/quests/:questId/steps/:stepId

Permanently deletes a step from a quest's timeline. Deleting an ending step reopens the quest. Requires the Collaborator role or above. Returns 200 with the full updated quest on success.

curl -X DELETE https://realmsofshod.com/api/v1/realms/clxyz.../compendium/quests/quest_abc.../steps/step_001... \
  -H "Authorization: Bearer ros_your_token_here"

The mechanic, motive, and source fields are optional tags. The status field is always derived from the step timeline and cannot be set directly: add a step with an ending type to move a quest out of active.