create_chapter
Create a chapter or a collection.
/v1/guides/{productId}/chapterskind chapter for sections that carry prose (body paragraphs, an intro); kind collection for pure spot sets. Add members afterwards with set_chapter_members.
curl -X POST "https://sceniq.earth/api/v1/guides/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/chapters" \
-H "Authorization: Bearer $SCENIQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Yosemite",
"kind": "chapter",
"slug": "yosemite",
"description": "Granite walls and the valley from above",
"body": [
"Tunnel View, Glacier Point and the trails off Glacier Point Road show the valley from three heights. Glacier Point Road closes to cars in winter, so from November to late May this chapter shrinks to the valley floor.",
"Sunset belongs to Tunnel View and Taft Point; Glacier Point works from late afternoon into the blue hour."
]
}'Path parameters
- productIdstring · guide idrequired
Id of the guide (a product of type map). From
list_guidesorcreate_guide.
Body parameters
- namestringrequired
Chapter title, e.g. Yellowstone or Bernese Oberland. Cannot be empty.
- bodyarray of stringsoptional
Ordered prose paragraphs, chapters only, full replacement ([] clears): at most 100, each at most 10,000 characters; empty paragraphs are dropped.
- descriptionstringoptional
One-line summary shown on the chapter card. Empty string clears.
- kindstringoptional
chapter or collection (default collection).
chaptercollection - slugstringoptional
Optional URL slug, unique in the guide: 1 to 63 lowercase letters, digits or hyphens, a letter or digit first (stored lower case). Empty string clears.
Returns
201 Created with Chapter: A chapter or a collection with its members.
- collectionIdstring · chapter idrequired
The chapter's or collection's id.
- productIdstring · guide idrequired
The guide's id.
- namestringrequired
Its title.
- slugstring or nullrequired
URL slug, unique in the guide.
- descriptionstring or nullrequired
One-line summary on the chapter card.
- kindstringrequired
chapter carries prose and front matter; collection is a plain spot set.
collectionchapter - bodyarray of stringsrequired
Prose paragraphs (chapters only).
Structured front matter (chapters only).
Show 5 fieldsHide fieldsof ChapterIntro
- coverKickerstringoptional
The cover's eyebrow line, at most 120 characters (A Patagonia Field Guide).
- coverTitlestringoptional
The cover title, at most 160 characters. Absent means the guide's name.
- coverAuthorstringoptional
The byline name, shown as By <name>, at most 120 characters. Absent means the creator's display name.
- coverAuthorPhotoStorageIdstring · stored file idoptional
The byline photo, a
storageIdfrom an upload with target=blob. Absent means the creator's avatar. Up to 20 sections in reading order.
Show 9 fieldsHide fieldsof IntroSection
- kindstringoptional
prose (the default), chapters (a row for each other chapter of the guide) or collections (a card for each collection that has spots). The rows and cards derive from the guide; items only restyle them.
prosechapterscollections - kickerstringoptional
The eyebrow above the title, at most 120 characters.
- titlestringrequired
The section title, at most 160 characters. Required.
- deckstringoptional
The standfirst under the title, at most 500 characters.
- paragraphsarray of stringsoptional
Prose sections only: up to 30 paragraphs of at most 10,000 characters. Lines starting with "- " inside a paragraph render as a bulleted list.
- cellsarray of objectsoptional
Prose sections only: up to 8 numbered cells (a plan in steps). A section with cells carries no paragraphs and no photo.
Show 2 fieldsHide fields
- titlestringrequired
The cell's title, at most 120 characters. Required unless the whole cell is empty, which drops it.
- bodystringrequired
The cell's text, at most 600 characters.
- photoStorageIdstring · stored file idoptional
Prose sections only: the side photo, a
storageIdfrom an upload with target=blob. - photoCreditstringoptional
The side photo's credit, at most 80 characters, shown on the photo. Kept only with a photo; absent means the creator's own shot.
Chapters and collections sections only: up to 60 entries, each restyling one row or card.
Show 6 fieldsHide fieldsof IntroItem
- collectionIdstring · chapter idrequired
The chapter (chapters section) or plain collection (collections section) of this guide the entry dresses, once per section.
- titlestringoptional
The name on the row or card, at most 120 characters. Absent means the chapter's or collection's name.
- linestringoptional
Chapters sections only: the short line under the name, at most 200 characters. Absent means the chapter's description.
- colorstringoptional
Chapters sections only: the row's color bar as #rrggbb (stored lower case).
- photoStorageIdstring · stored file idoptional
Collections sections only: the card photo, a
storageIdfrom an upload with target=blob. Absent means the collection's cover. - photoCreditstringoptional
The card photo's credit, at most 80 characters. Kept only with a photo.
- ordernumberrequired
Position in the guide.
- coverUrlstring or nullrequired
The cover image.
- coverStorageIdstring or null · stored file idrequired
The cover's storage id (from an upload with target=blob).
- membersarray of objectsrequired
Members in order: spots, or chapters inside a collection.
Show 3 fieldsHide fields
- spotKeystring or nullrequired
A member spot's key.
- memberCollectionIdstring or null · chapter idrequired
A chapter placed as a card inside a collection.
- ordernumberrequired
Position in the chapter.
- createdAtnumberrequired
When the row was created (Unix time in milliseconds).
- updatedAtnumberrequired
When the row last changed (Unix time in milliseconds).
{
"collectionId": "kn73r7x6mp88mxa9swcbshwd3e7zvr39",
"productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
"name": "Yosemite",
"slug": "yosemite",
"description": "Granite walls and the valley from above",
"kind": "chapter",
"body": [
"Tunnel View, Glacier Point and the trails off Glacier Point Road show the valley from three heights. Glacier Point Road closes to cars in winter, so from November to late May this chapter shrinks to the valley floor.",
"Sunset belongs to Tunnel View and Taft Point; Glacier Point works from late afternoon into the blue hour."
],
"intro": null,
"order": 3072,
"coverUrl": null,
"coverStorageId": null,
"members": [],
"createdAt": 1789895640000,
"updatedAt": 1789895640000
}Errors
Every error is { error: { code, message } }. Act on the code.
- 400invalid_argumentA 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).
- 400invalid_requestA 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.
- 401unauthenticatedThe request carries no key. Send it as Authorization: Bearer sk_sceniq_... (or X-Api-Key).
- 401invalid_api_keyThe key is unknown, revoked or expired.
- 403api_scope_requiredA read-only key called a write operation, or a key without the publish option called publish_changes.
- 403forbiddenThe key belongs to a creator account that is no longer active.
- 404not_foundThe id does not exist or belongs to another creator. The two answers are identical on purpose, so ids never reveal what exists.
- 413payload_too_largeA JSON body over 2 MB, an image over 6 MB, a batch upload over 19 MB, or an MCP message over 2 MB.
- 429rate_limitedOver a limit: requests per key per minute, per creator per hour, uploads per key per minute, or check_links per guide per hour.
- 500internal_errorAn unexpected failure. The message is hidden on purpose.