SceniqDevelopers

list_itineraries

Day-by-day trips of a guide, including archived ones.

GET/v1/guides/{productId}/itineraries
MCP tool list_itinerariesScope: readBetaSince 2026-10-06.3
Markdown

All itineraries in display order. Days come back exactly as stored: edit them and send them to set_itinerary_days. What buyers see is decided at publish: archived itineraries and ones with no spot, route or place stop buyers can open stay hidden. get_guide_readiness lists unarchived trips with no such stop.

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

Path parameters

Returns

200 OK with ItineraryList: All a guide's itineraries in display order.

  • productIdstring · guide idrequired

    The guide's id.

  • itinerariesarray of Itineraryrequired

    All the guide's itineraries in order, archived ones included.

    Show 15 fieldsof Itinerary
    • itineraryIdstring · itineraries idrequired

      The itinerary's id.

    • productIdstring · guide idrequired

      The guide's id.

    • namestringrequired

      The trip's name.

    • descriptionstring or nullrequired

      Short description, or null when empty.

    • bodystring or nullrequired

      Before you go: the creator's trip notes, or null.

    • coverMediaIdstring or null · photo idrequired

      A photo of this guide, or null for no cover.

    • travelModestring or nullrequired

      How to get around on the whole trip, or null when unknown.

      carpublic_transportcampervanbikeon_footboatmixed
    • seasonItinerarySeason or nullrequired

      Months and a season note, or null when unset.

      Show 2 fieldsof ItinerarySeason
      • monthsarray of numbersoptional

        Optional month numbers, 1 to 12. Stored sorted with duplicates removed; [] drops.

      • notestringoptional

        Optional season note, at most 300 characters. Empty text drops.

    • startsAtstring or nullrequired

      Where the trip starts, in words, or null.

    • endsAtstring or nullrequired

      Where the trip ends, in words, or null.

    • daysarray of ItineraryDayrequired

      The days exactly as stored, with absent optional fields and no nulls inside. Edit this array and send it straight to set_itinerary_days.

      Show 4 fieldsof ItineraryDay
      • titlestringoptional

        Optional day title, at most 120 characters. Empty text drops.

      • notestringoptional

        Optional day note, at most 2000 characters. Empty text drops.

      • stopsarray of ItineraryStoprequired

        Ordered stops, 0 to 40, with no stop ids.

      • overnightItineraryOvernightoptional

        Where to sleep: a stay of this guide, words, or both, plus a note.

        Show 3 fieldsof ItineraryOvernight
        • facilityIdstringoptional

          Optional facilityId from list_facilities: a stay's helper spotId, or an id from before 2026-10-04 that still resolves. Must be a stay of this guide (kind hut or hut in extraKinds).

        • namestringoptional

          Optional place in words, at most 120 characters. Can accompany a stay id or stand alone.

        • notestringoptional

          Optional overnight note, at most 1000 characters. Empty text drops.

    • ordernumberrequired

      Position in the guide, ascending and fractional.

    • archivedbooleanrequired

      true hides this itinerary from buyers and keeps it editable.

    • createdAtnumberrequired

      When the row was created (Unix time in milliseconds).

    • updatedAtnumberrequired

      When the row last changed (Unix time in milliseconds).

Response 200
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "itineraries": [
    {
      "itineraryId": "ki7a2c4e6g8j0m2p4s6v8y0b2d4f6h8k",
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
      "name": "Yellowstone over two days",
      "description": "Thermal colors, a night at Old Faithful and first light in Lamar Valley.",
      "body": "Book the inn ahead. Check road conditions and keep wildlife at a distance.",
      "coverMediaId": "kg71s3d5f7g9h1j3k5k7z9x1c3v5b7n9",
      "travelMode": "car",
      "season": {
        "months": [
          6,
          7,
          8,
          9
        ],
        "note": "Check the park road status before setting out."
      },
      "startsAt": "Old Faithful",
      "endsAt": "Lamar Valley",
      "days": [
        {
          "title": "Thermal basins and the overlook",
          "note": "Wait for the steam to lift before the overlook.",
          "stops": [
            {
              "kind": "place",
              "facilityId": "k17d4f6g8h0j2k4k6z8x0c2v4b6n8m0q",
              "when": "morning"
            },
            {
              "kind": "route",
              "routeId": "kx7f2h8j4k0k6z2x8c4v0b6n2m8q4w0e",
              "when": "morning"
            },
            {
              "kind": "spot",
              "spotKey": "01M2Z1G0Y0QG7M2V6N9R3T5W8Y",
              "when": "midday",
              "note": "See the colors from the platform, then walk the boardwalk."
            },
            {
              "kind": "travel",
              "mode": "car",
              "from": "Midway Geyser Basin",
              "to": "Old Faithful",
              "when": "afternoon"
            },
            {
              "kind": "place",
              "facilityId": "k17j9h5g1f7d3s9a5p1p7j3v9y5t1r7m",
              "when": "evening"
            }
          ],
          "overnight": {
            "facilityId": "k17j9h5g1f7d3s9a5p1p7j3v9y5t1r7m",
            "name": "Old Faithful Inn",
            "note": "Reserve before the trip."
          }
        },
        {
          "title": "First light in Lamar Valley",
          "stops": [
            {
              "kind": "travel",
              "mode": "car",
              "from": "Old Faithful",
              "to": "Lamar Valley",
              "when": "night"
            },
            {
              "kind": "spot",
              "spotKey": "01M3GYV6A0Y3SYC62RBPEA9S0C",
              "when": "sunrise"
            },
            {
              "kind": "note",
              "title": "Keep wildlife at a distance",
              "note": "Follow the park's current wildlife guidance."
            }
          ]
        }
      ],
      "order": 1024,
      "archived": false,
      "createdAt": 1789895640000,
      "updatedAt": 1790586840000
    }
  ]
}

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).
  • 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.
  • 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.
  • 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.