# list_chapters

Chapters and collections with their members.

`GET /v1/guides/{productId}/chapters` · MCP tool `list_chapters` · scope `read` · stable · since 2026-09-17

A chapter is a guide section (a region, a day) that can carry prose and front matter; a collection is a plain spot set (top picks). Members reference spots by spotKey, or chapters by id inside a collection.

## Path parameters

- `productId` (string, required): Id of the guide (a product of type map). From list_guides or create_guide.

## Returns

200.

- `productId` (string, required): The guide's id.
- `chapters` (array of Chapter, required): Every chapter and collection in guide order.
  Fields of Chapter: https://developers.sceniq.earth/fields/chapter.md

## Examples

### List chapters and collections in guide order

```bash
curl "https://sceniq.earth/api/v1/guides/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/chapters" \
  -H "Authorization: Bearer $SCENIQ_API_KEY"
```

MCP `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_chapters",
    "arguments": {
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2"
    }
  }
}
```

Response 200:

```json
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "chapters": [
    {
      "collectionId": "kn7q65ntqkryzm6y45h5dyxqt0p454y8",
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "name": "Introduction",
      "slug": "introduction",
      "description": null,
      "kind": "chapter",
      "body": [],
      "intro": {
        "coverKicker": "A photographer's field guide",
        "sections": [
          {
            "kind": "prose",
            "kicker": "How to use this guide",
            "title": "Timed for the light",
            "deck": "Every spot says when to be there and where to park, so the light and the crowds work for you.",
            "paragraphs": [
              "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."
            ],
            "photoStorageId": "kg2gsfxz27kpg15n437vtmc3zj91qz34"
          },
          {
            "kind": "prose",
            "kicker": "Plan",
            "title": "Before you go",
            "cells": [
              {
                "title": "Passes",
                "body": "Each park charges 35 USD per vehicle for 7 days. An annual pass covers both."
              },
              {
                "title": "Seasons",
                "body": "Late May to September suits both parks. Some roads close from November."
              },
              {
                "title": "Driving",
                "body": "Yellowstone to Yosemite is about 1,400 km by road: two long days."
              },
              {
                "title": "Drones",
                "body": "Banned in every US national park."
              }
            ]
          },
          {
            "kind": "chapters",
            "kicker": "The parks",
            "title": "Two parks, a long drive apart",
            "items": [
              {
                "collectionId": "kn7e5r9t3y7v1j5p9p3a7s1d5f9g3h7j",
                "line": "Hot springs, geysers and bison",
                "color": "#b45309"
              },
              {
                "collectionId": "kn73r7x6mp88mxa9swcbshwd3e7zvr39",
                "line": "Granite walls and the valley from above",
                "color": "#1d4ed8"
              }
            ]
          },
          {
            "kind": "collections",
            "title": "Short on time",
            "items": [
              {
                "collectionId": "kn7a2s4d6f8g0h2j4k6k8z0x2c4v6b8n",
                "photoStorageId": "kg29fadcmt160qtrce3h3rm82yc6hhtb"
              }
            ]
          }
        ]
      },
      "order": 1024,
      "coverUrl": null,
      "coverStorageId": null,
      "members": [],
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000
    },
    {
      "collectionId": "kn7e5r9t3y7v1j5p9p3a7s1d5f9g3h7j",
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "name": "Yellowstone",
      "slug": "yellowstone",
      "description": "Hot springs, geysers and bison",
      "kind": "chapter",
      "body": [
        "Yellowstone's hot springs and geysers line the Grand Loop Road, so a car and early starts do most of the work. The spots in this chapter run from Midway Geyser Basin in the southwest to Lamar Valley in the northeast, about three hours apart by road.",
        "Steam decides the photos here. On cold mornings it hides the colors of the hot springs; on warm, dry days it lifts by mid morning. Keep the thermal basins for late morning and the first light for Lamar Valley."
      ],
      "intro": null,
      "order": 2048,
      "coverUrl": "https://quiet-heron-512.convex.cloud/api/storage/yellowstone-cover.webp",
      "coverStorageId": "kg2a8c4e0g6j2k8m4p0q6s2v8w4y0a6c",
      "members": [
        {
          "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y",
          "memberCollectionId": null,
          "order": 1024
        },
        {
          "spotKey": "01M3GYV6A0Y3SYC62RBPEA9S0C",
          "memberCollectionId": null,
          "order": 2048
        }
      ],
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000
    },
    {
      "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": [
        {
          "spotKey": "01M2Z1G0Y0R2K5P8S1V4X7Z0C3",
          "memberCollectionId": null,
          "order": 1024
        },
        {
          "spotKey": "01M3H2AWH0F9PB64V7QB8QS0MC",
          "memberCollectionId": null,
          "order": 2048
        },
        {
          "spotKey": "01M3H2AXG8GB8YNF4FCEFARFN5",
          "memberCollectionId": null,
          "order": 3072
        },
        {
          "spotKey": "01M3KMNRY0V8ZPTG4HCY75DZFB",
          "memberCollectionId": null,
          "order": 4096
        },
        {
          "spotKey": "01M3H2AYFG8169CVH0JCQY2BN2",
          "memberCollectionId": null,
          "order": 5120
        }
      ],
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000
    },
    {
      "collectionId": "kn7a2s4d6f8g0h2j4k6k8z0x2c4v6b8n",
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "name": "Top picks",
      "slug": null,
      "description": "If you only have a day in each park",
      "kind": "collection",
      "body": [],
      "intro": null,
      "order": 4096,
      "coverUrl": null,
      "coverStorageId": null,
      "members": [
        {
          "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y",
          "memberCollectionId": null,
          "order": 1024
        },
        {
          "spotKey": "01M2Z1G0Y0R2K5P8S1V4X7Z0C3",
          "memberCollectionId": null,
          "order": 2048
        },
        {
          "spotKey": "01M3H2AWH0F9PB64V7QB8QS0MC",
          "memberCollectionId": null,
          "order": 3072
        }
      ],
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000
    },
    {
      "collectionId": "kn7hh1xv41qmtn8mk9n7g2wc7qfrfpte",
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "name": "The two parks",
      "slug": null,
      "description": null,
      "kind": "collection",
      "body": [],
      "intro": null,
      "order": 5120,
      "coverUrl": null,
      "coverStorageId": null,
      "members": [
        {
          "spotKey": null,
          "memberCollectionId": "kn7e5r9t3y7v1j5p9p3a7s1d5f9g3h7j",
          "order": 1024
        },
        {
          "spotKey": null,
          "memberCollectionId": "kn73r7x6mp88mxa9swcbshwd3e7zvr39",
          "order": 2048
        }
      ],
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000
    }
  ]
}
```

## 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).
- `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.
- `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.
- `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/list_chapters