# set_chapter_pages Replace a chapter's ordered page stack. `PUT /v1/chapters/{collectionId}/pages` · MCP tool `set_chapter_pages` · scope `write` · beta · since 2026-10-06.2 Full replacement, chapters only. Send all desired pages in reading order, at most 40. Fields unused by the page type are dropped; invalid variants or refs are refused. Missing and changed-kind targets, self Contents refs and removed photos are dropped silently. Other-guide ids are not_found; product- or listing-owned photos are invalid_request. Unused chapter-owned photos are released when no other chapter uses them. Legacy intro and body are cleared. The reply includes the pages as stored. ## Path parameters - `collectionId` (string, required): Id of a chapter from list_chapters. Plain collections refuse pages. ## Body parameters - `pages` (array of ChapterPage, required): Complete ordered ChapterPage array, up to 40 pages and 150,000 JSON characters after normalisation. [] clears the stack. Every page field other than id and type is optional; empty pages are valid. Fields of ChapterPage: https://developers.sceniq.earth/fields/chapter-page.md - `expectedUpdatedAt` (number, optional): Optional staleness guard: the chapter's updatedAt you last read (list_chapters). The write is refused with stale_editor when the chapter changed since. ## Returns 200. - `ok` (boolean, required): Always true: the write went through. Always `true`. - `collectionId` (string, required): The chapter's or collection's id. - `updatedAt` (number, required): The stored chapter revision in epoch milliseconds. Use it as expectedUpdatedAt for the next write. - `pages` (array of ChapterPage, required): The normalised pages stored by this replacement, including silent removal of stale refs and photos. Fields of ChapterPage: https://developers.sceniq.earth/fields/chapter-page.md ## Examples ### Cover, text, gallery and chosen spots, using uploaded and existing guide photos ```bash curl -X PUT "https://sceniq.earth/api/v1/chapters/kn7q65ntqkryzm6y45h5dyxqt0p454y8/pages" \ -H "Authorization: Bearer $SCENIQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "pages": [ { "id": "page0001", "type": "cover", "variant": "split", "kicker": "A photographer'\''s field guide", "title": "US National Parks", "byline": true, "photos": [ { "mediaId": "kg7d6v4r2t8y0w6q4p2n8m0k6j4h2g8f" } ] }, { "id": "page0002", "type": "text", "kicker": "How to use this guide", "title": "Timed for the light", "body": [ "Each spot lists its best time of day, how crowded it gets and how far it is from the car. Most are short walks; the hikes are marked.", "- One day per park? Start with Top picks.\n- Check the park road status before a sunrise drive." ] }, { "id": "page0003", "type": "gallery", "title": "From the parks", "photos": [ { "mediaId": "kg71s3d5f7g9h1j3k5k7z9x1c3v5b7n9", "caption": "Grand Prismatic Spring" }, { "mediaId": "kg7p2p4j6v8y0t2r4e6w8q0a2s4d6f8g", "caption": "Midway Geyser Basin" }, { "mediaId": "kg7m9n1b3v5c7x9z1k3k5j7h9g1f3d5s", "caption": "Tunnel View" } ] }, { "id": "page0004", "type": "spots", "variant": "reader", "refs": [ { "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y" }, { "spotKey": "01M2Z1G0Y0R2K5P8S1V4X7Z0C3" } ] } ], "expectedUpdatedAt": 1789895640000 }' ``` MCP `tools/call`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "set_chapter_pages", "arguments": { "collectionId": "kn7q65ntqkryzm6y45h5dyxqt0p454y8", "pages": [ { "id": "page0001", "type": "cover", "variant": "split", "kicker": "A photographer's field guide", "title": "US National Parks", "byline": true, "photos": [ { "mediaId": "kg7d6v4r2t8y0w6q4p2n8m0k6j4h2g8f" } ] }, { "id": "page0002", "type": "text", "kicker": "How to use this guide", "title": "Timed for the light", "body": [ "Each spot lists its best time of day, how crowded it gets and how far it is from the car. Most are short walks; the hikes are marked.", "- One day per park? Start with Top picks.\n- Check the park road status before a sunrise drive." ] }, { "id": "page0003", "type": "gallery", "title": "From the parks", "photos": [ { "mediaId": "kg71s3d5f7g9h1j3k5k7z9x1c3v5b7n9", "caption": "Grand Prismatic Spring" }, { "mediaId": "kg7p2p4j6v8y0t2r4e6w8q0a2s4d6f8g", "caption": "Midway Geyser Basin" }, { "mediaId": "kg7m9n1b3v5c7x9z1k3k5j7h9g1f3d5s", "caption": "Tunnel View" } ] }, { "id": "page0004", "type": "spots", "variant": "reader", "refs": [ { "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y" }, { "spotKey": "01M2Z1G0Y0R2K5P8S1V4X7Z0C3" } ] } ], "expectedUpdatedAt": 1789895640000 } } } ``` Response 200: ```json { "ok": true, "collectionId": "kn7q65ntqkryzm6y45h5dyxqt0p454y8", "updatedAt": 1790586840000, "pages": [ { "id": "page0001", "type": "cover", "variant": "split", "kicker": "A photographer's field guide", "title": "US National Parks", "byline": true, "photos": [ { "mediaId": "kg7d6v4r2t8y0w6q4p2n8m0k6j4h2g8f" } ] }, { "id": "page0002", "type": "text", "kicker": "How to use this guide", "title": "Timed for the light", "body": [ "Each spot lists its best time of day, how crowded it gets and how far it is from the car. Most are short walks; the hikes are marked.", "- One day per park? Start with Top picks.\n- Check the park road status before a sunrise drive." ] }, { "id": "page0003", "type": "gallery", "title": "From the parks", "photos": [ { "mediaId": "kg71s3d5f7g9h1j3k5k7z9x1c3v5b7n9", "caption": "Grand Prismatic Spring" }, { "mediaId": "kg7p2p4j6v8y0t2r4e6w8q0a2s4d6f8g", "caption": "Midway Geyser Basin" }, { "mediaId": "kg7m9n1b3v5c7x9z1k3k5j7h9g1f3d5s", "caption": "Tunnel View" } ] }, { "id": "page0004", "type": "spots", "variant": "reader", "refs": [ { "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y" }, { "spotKey": "01M2Z1G0Y0R2K5P8S1V4X7Z0C3" } ] } ] } ``` ### Clear all pages without changing the chapter's own spots ```bash curl -X PUT "https://sceniq.earth/api/v1/chapters/kn7q65ntqkryzm6y45h5dyxqt0p454y8/pages" \ -H "Authorization: Bearer $SCENIQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "pages": [] }' ``` MCP `tools/call`: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "set_chapter_pages", "arguments": { "collectionId": "kn7q65ntqkryzm6y45h5dyxqt0p454y8", "pages": [] } } } ``` Response 200: ```json { "ok": true, "collectionId": "kn7q65ntqkryzm6y45h5dyxqt0p454y8", "updatedAt": 1790586840000, "pages": [] } ``` ## Errors - `invalid_argument` (400): A required field is missing, a field is unknown, or a value does not match its type (the Convex validator's path and value are in the message). - `invalid_request` (400): A writer refused a value: a map link on a host that is not allowed, a title that is too long, a date that does not exist, too many items in a list. The message is the writer's own sentence. - `stale_editor` (409): The row changed after the expectedUpdatedAt you sent (update_chapter, set_chapter_pages, update_itinerary, set_itinerary_days, save_sales_page_draft). - `unauthenticated` (401): The request carries no key. Send it as Authorization: Bearer sk_sceniq_... (or X-Api-Key). - `invalid_api_key` (401): The key is unknown, revoked or expired. - `api_scope_required` (403): A read-only key called a write operation, or a key without the publish option called publish_changes. - `forbidden` (403): The key belongs to a creator account that is no longer active. - `not_found` (404): The id does not exist or belongs to another creator. The two answers are identical on purpose, so ids never reveal what exists. - `payload_too_large` (413): A JSON body over 2 MB, an image over 6 MB, a batch upload over 19 MB, or an MCP message over 2 MB. - `rate_limited` (429): Over a limit: requests per key per minute, per creator per hour, uploads per key per minute, or check_links per guide per hour. - `internal_error` (500): An unexpected failure. The message is hidden on purpose. Reference: https://developers.sceniq.earth/reference/set_chapter_pages