get_guide_readiness

Publish checklist: blocking gates, warnings, review link.

GET/v1/guides/{productId}/readiness
MCP tool get_guide_readinessScope: readStableSince 2026-09-17
Markdown

Run this before handing the draft back. blocking is the publish gates themselves (agreement, at least one live spot, a pin and a photo on every live spot, a price), the same check publishing enforces. warnings flag coordinate outliers, spots without text, missing credits, an incomplete sales page, facts past their review-by or valid-until dates, dead, parked, spam or redirected links, photos taken far from the pin or before a change at the spot, places far from their spots or in another time zone, stated distances shorter than the straight line, text search map links, dates in the text that have passed, best months missing from a month property, directions that disagree with the pins, best light outside the opening hours and extra pins far from their spot; checks holds the rows behind each warning and every reviewNotes entry. handoff lists the clicks only the creator can make (Publish guide, Publish sales page) with their studio links: plan the hand-off from the start. Send the creator the reviewUrl. For a live guide, see get_publish_status and publish_changes.

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

Path parameters

Returns

200 OK with Readiness: The publish checklist of a guide.

  • productIdstring · guide idrequired

    The guide's id.

  • namestringrequired

    The guide's title.

  • statusstringrequired

    draft, published or archived.

    draftpublishedarchived
  • canPublishbooleanrequired

    true when no publish gate is open.

  • blockingarray of PublishGaterequired

    The publish gates that are open: the same check publishing enforces.

    Show 2 fieldsof PublishGate
    • codestringrequired

      Which gate is open.

      agreement_outdatedno_spotsmissing_coordinatesmissing_photosno_price
    • messagestringrequired

      What to fix, in plain words.

  • warningsarray of objectsrequired

    Checks that do not block a publish but deserve a look.

    Show 2 fields
    • codestringrequired

      A stable code for the warning (see the readiness guide for the list).

    • messagestringrequired

      What it means, in plain words.

  • checksobjectrequired

    The rows behind each warning and gate.

    Show 29 fields
    • staleFactsarray of StaleFactrequired

      Dated facts past their dates.

      Show 7 fieldsof StaleFact
      • kindstringrequired

        The kind of row.

        spotplacerouteareaphoto
      • idstringrequired

        The row's id.

      • namestringrequired

        The row's name.

      • fieldstringrequired

        The field that needs a new check (fees, status, schedule, reviewBy ...).

      • reasonstringrequired

        Why it is listed.

        review_dueendednot_checked_recently
      • datestring or nullrequired

        The date that passed (YYYY-MM-DD).

      • detailstringrequired

        What ran out, in plain words.

    • reviewNotesarray of objectsrequired

      Every reviewNotes entry in the guide.

      Show 4 fields
      • kindstringrequired

        The kind of row.

        spotplaceroutephoto
      • idstringrequired

        The row's id.

      • namestringrequired

        The row's name.

      • notestringrequired

        The review note.

    • spotsWithoutSourcesnumberrequired

      Live spots without any source.

    • linksobjectrequired

      Link health (get_link_report has every link).

      Show 4 fields
      • totalnumberrequired

        Links buyers can open.

      • flaggedarray of objectsrequired

        Links that look dead, parked or redirected.

        Show 5 fields
        • urlstringrequired

          The link.

        • statestringrequired

          Its state (broken, suspicious, tls, redirected).

        • reasonstring or nullrequired

          Why, in words.

        • finalUrlstring or nullrequired

          Where a redirect ends.

        • usedByarray of objectsrequired

          Where the link is used.

          Show 3 fields
          • kindstringrequired

            The kind of row.

          • namestringrequired

            The row's name.

          • fieldstringrequired

            The field that holds the link.

      • unverifiablenumberrequired

        Links on sites that turn scripts away.

      • uncheckednumberrequired

        Links not checked yet.

    • photosobjectrequired

      Photo checks.

      Show 4 fields
      • farFromPinarray of objectsrequired

        Photos with a precise location more than 2 km from the pin.

        Show 6 fields
        • kindstringrequired

          Always photo.

          spotplacerouteareaphoto
        • idstringrequired

          The photo's id.

        • namestringrequired

          The photo's caption or file.

        • spotIdstringrequired

          The spot the photo belongs to.

        • spotTitlestringrequired

          The spot's title.

        • detailstringrequired

          What looks wrong.

      • judgementarray of objectsrequired

        Photos whose location needs the creator's judgement.

        Show 6 fields
        • kindstringrequired

          Always photo.

          spotplacerouteareaphoto
        • idstringrequired

          The photo's id.

        • namestringrequired

          The photo's caption or file.

        • spotIdstringrequired

          The spot the photo belongs to.

        • spotTitlestringrequired

          The spot's title.

        • detailstringrequired

          What looks wrong.

      • beforeChangearray of objectsrequired

        Photos captured before the spot's siteChange.

        Show 6 fields
        • kindstringrequired

          Always photo.

          spotplacerouteareaphoto
        • idstringrequired

          The photo's id.

        • namestringrequired

          The photo's caption or file.

        • spotIdstringrequired

          The spot the photo belongs to.

        • spotTitlestringrequired

          The spot's title.

        • detailstringrequired

          What looks wrong.

      • nearDuplicatesarray of objectsrequired

        Photos that look like another photo of the guide.

        Show 6 fields
        • kindstringrequired

          Always photo.

          spotplacerouteareaphoto
        • idstringrequired

          The photo's id.

        • namestringrequired

          The photo's caption or file.

        • spotIdstringrequired

          The spot the photo belongs to.

        • spotTitlestringrequired

          The spot's title.

        • detailstringrequired

          What looks wrong.

    • placesobjectrequired

      Place checks.

      Show 4 fields
      • farFromSpotsarray of objectsrequired

        Places far from the spots they serve.

        Show 4 fields
        • kindstringrequired

          The kind of row.

          spotplacerouteareaphoto
        • idstringrequired

          The row's id.

        • namestringrequired

          The row's name.

        • detailstringrequired

          What looks wrong.

      • zoneDiffersarray of objectsrequired

        Places in another time zone than their spot.

        Show 4 fields
        • kindstringrequired

          The kind of row.

          spotplacerouteareaphoto
        • idstringrequired

          The row's id.

        • namestringrequired

          The row's name.

        • detailstringrequired

          What looks wrong.

      • distanceTooShortarray of objectsrequired

        Stated distances shorter than the straight line.

        Show 4 fields
        • kindstringrequired

          The kind of row.

          spotplacerouteareaphoto
        • idstringrequired

          The row's id.

        • namestringrequired

          The row's name.

        • detailstringrequired

          What looks wrong.

      • searchLinksarray of objectsrequired

        Map links that are a text search (they can open a namesake).

        Show 4 fields
        • kindstringrequired

          The kind of row.

          spotplacerouteareaphoto
        • idstringrequired

          The row's id.

        • namestringrequired

          The row's name.

        • detailstringrequired

          What looks wrong.

    • textobjectrequired

      Text checks.

      Show 3 fields
      • pastDatesarray of objectsrequired

        Dates in the text that have passed.

        Show 5 fields
        • kindstringrequired

          The kind of row.

          spotplacerouteareaphoto
        • idstringrequired

          The row's id.

        • namestringrequired

          The row's name.

        • fieldstringrequired

          The field the text is in.

        • detailstringrequired

          What looks wrong.

      • monthMismatcharray of objectsrequired

        Best months in the text missing from a month property.

        Show 5 fields
        • kindstringrequired

          The kind of row.

          spotplacerouteareaphoto
        • idstringrequired

          The row's id.

        • namestringrequired

          The row's name.

        • fieldstringrequired

          The field the text is in.

        • detailstringrequired

          What looks wrong.

      • directionsarray of objectsrequired

        Directions that disagree with the pins.

        Show 5 fields
        • kindstringrequired

          The kind of row.

          spotplacerouteareaphoto
        • idstringrequired

          The row's id.

        • namestringrequired

          The row's name.

        • fieldstringrequired

          The field the text is in.

        • detailstringrequired

          What looks wrong.

    • lightarray of objectsrequired

      Best light outside the opening hours.

      Show 5 fields
      • kindstringrequired

        The kind of row.

        spotplacerouteareaphoto
      • idstringrequired

        The row's id.

      • namestringrequired

        The row's name.

      • fieldstringrequired

        The field the text is in.

      • detailstringrequired

        What looks wrong.

    • pinsarray of objectsrequired

      Extra pins far from their spot.

      Show 5 fields
      • kindstringrequired

        The kind of row.

        spotplacerouteareaphoto
      • idstringrequired

        The row's id.

      • namestringrequired

        The row's name.

      • fieldstringrequired

        The field the text is in.

      • detailstringrequired

        What looks wrong.

    • agreementCurrentbooleanrequired

      Whether the creator accepted the current agreement.

    • spotCountnumberrequired

      Live spots.

    • archivedSpotCountnumberrequired

      Archived spots.

    • missingCoordinatesarray of objectsrequired

      Live spots without a pin.

      Show 2 fields
      • spotIdstring · spot idrequired

        The spot's id.

      • titlestringrequired

        The spot's title.

    • coordinateOutliersarray of objectsrequired

      Spots unusually far from the others.

      Show 3 fields
      • spotIdstring · spot idrequired

        The spot's id.

      • titlestringrequired

        The spot's title.

      • distanceKmnumberrequired

        Distance from the guide's center in kilometers.

    • outlierThresholdKmnumberrequired

      The distance above which a spot counts as an outlier.

    • outsideRegionarray of objectsrequired

      Spots outside the region's bbox.

      Show 2 fields
      • spotIdstring · spot idrequired

        The spot's id.

      • titlestringrequired

        The spot's title.

    • spotsWithoutPhotosarray of objectsrequired

      Live spots with photos on but none uploaded.

      Show 2 fields
      • spotIdstring · spot idrequired

        The spot's id.

      • titlestringrequired

        The spot's title.

    • spotsWithoutTextarray of objectsrequired

      Spots without a short or a long description.

      Show 2 fields
      • spotIdstring · spot idrequired

        The spot's id.

      • titlestringrequired

        The spot's title.

    • photoCountnumberrequired

      Photos in the guide.

    • photosWithoutCreditnumberrequired

      Photos without a credit.

    • priceobject or nullrequired

      The active price.

      Show 2 fields
      • amountMinornumberrequired

        The price in minor units (2900 is 29.00).

      • currencystringrequired

        ISO 4217 code in lower case (usd, eur, chf).

    • chapterCountnumberrequired

      Chapters and collections.

    • routeCountnumberrequired

      Routes.

    • regionMapRegion or nullrequired

      The map region.

      Show 5 fieldsof MapRegion
      • labelstringoptional

        A name buyers recognise for the region, at most 120 characters (Hokkaido, the Dolomites).

      • centerLatnumberoptional

        Latitude of the opening center (-90 to 90), usually the middle of the spots.

      • centerLonnumberoptional

        Longitude of the opening center (-180 to 180).

      • defaultZoomnumberoptional

        The opening zoom level, 0 to 22; 8 to 11 suits a region.

      • bboxarray of numbersoptional

        The bounding box as [west, south, east, north] in decimal degrees, exactly four numbers. It should contain every spot: readiness flags spots outside it.

    • storeTagsarray of stringsrequired

      Store tags.

    • countrystring or nullrequired

      Country code, or null for worldwide.

    • hasThumbnailbooleanrequired

      Whether a store thumbnail is set.

    • salesPageobjectrequired

      The sales page.

      Show 3 fields
      • draftProblemsarray of stringsrequired

        What the sales page draft still lacks.

      • existsbooleanrequired

        Whether a sales page draft exists.

      • publishedbooleanrequired

        Whether the sales page is published.

    • lastApiWriteAtnumber or nullrequired

      When a key last changed the guide.

  • handoffobjectrequired

    What the creator does in the studio.

    Show 3 fields
    • remainingarray of stringsrequired

      The clicks only the creator can make, still open.

    • studioUrlstringrequired

      Where the creator publishes the guide.

    • salesPageUrlstringrequired

      Where the creator publishes the sales page.

  • reviewUrlstringrequired

    The guide in the studio, for the creator's review.

  • nextStepstringrequired

    One sentence on what to do next.

Response 200
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "name": "American West: Parks at First Light",
  "status": "draft",
  "canPublish": false,
  "blocking": [
    {
      "code": "missing_coordinates",
      "message": "1 spot has no coordinates (Lamar Valley)"
    },
    {
      "code": "missing_photos",
      "message": "2 spots have no photo (Lamar Valley, Taft Point)"
    }
  ],
  "warnings": [
    {
      "code": "spots_without_text",
      "message": "1 spot(s) have neither a short nor a long description"
    },
    {
      "code": "sales_page_incomplete",
      "message": "Sales page draft: the hero needs between 2 and 6 bullets"
    },
    {
      "code": "no_thumbnail",
      "message": "No store thumbnail set (the creator picks it in the dashboard)"
    },
    {
      "code": "review_due",
      "message": "1 row is past its review-by date; re-check the facts and set a new reviewBy"
    },
    {
      "code": "stale_facts",
      "message": "2 dated facts have run out or not been checked recently (notices, fees, hours, timetables); see checks.staleFacts or list_stale_notices"
    },
    {
      "code": "link_problems",
      "message": "1 link is dead, parked, spam, redirected elsewhere or failing TLS; see checks.links (confirm a false alarm with set_link_verified)"
    }
  ],
  "checks": {
    "staleFacts": [
      {
        "kind": "spot",
        "id": "k1736b344br1c7m8qk8ks4sfndxyyftj",
        "name": "Glacier Point",
        "field": "reviewBy",
        "reason": "review_due",
        "date": "2026-09-15",
        "detail": "facts were due for a new check on 2026-09-15"
      },
      {
        "kind": "place",
        "id": "km73j9h5g1f7d3s9a5p1p7j3v9y5t1r7",
        "name": "Old Faithful Inn",
        "field": "schedule",
        "reason": "ended",
        "date": "2026-09-27",
        "detail": "hours valid until 2026-09-27"
      },
      {
        "kind": "route",
        "id": "kx7f2h8j4k0k6z2x8c4v0b6n2m8q4w0e",
        "name": "Fairy Falls trail",
        "field": "status",
        "reason": "ended",
        "date": "2026-09-25",
        "detail": "the closed notice ran until 2026-09-25; update or clear it"
      }
    ],
    "reviewNotes": [
      {
        "kind": "spot",
        "id": "k1709e2vj4sk8q6x0d3m5r7t9w1y3b5c",
        "name": "Grand Prismatic Spring",
        "note": "The overlook pin comes from your GPX of 18 September; please confirm it. The trail distance is from the NPS page (0.6 mi each way)."
      },
      {
        "kind": "spot",
        "id": "k17rwzt006kbqwjbs5jrqk4jjf5srec9",
        "name": "Lamar Valley",
        "note": "No pin yet: the creator is sending the pullout they use for the bison herds."
      }
    ],
    "spotsWithoutSources": 7,
    "links": {
      "total": 26,
      "flagged": [
        {
          "url": "https://www.nps.gov/yose/planyourvisit/glacierpoint.htm",
          "state": "broken",
          "reason": "http_404",
          "finalUrl": null,
          "usedBy": [
            {
              "kind": "spot",
              "name": "Glacier Point",
              "field": "links"
            }
          ]
        }
      ],
      "unverifiable": 1,
      "unchecked": 2
    },
    "photos": {
      "farFromPin": [],
      "judgement": [
        {
          "kind": "photo",
          "id": "kg7m9n1b3v5c7x9z1k3k5j7h9g1f3d5s",
          "name": "Tunnel View as a December storm clears",
          "spotId": "k17bc3xz8h6f4d2s0q9w7e5r3t1y2v4j",
          "spotTitle": "Tunnel View",
          "detail": "location rests on judgement, not a geotag or a landmark"
        }
      ],
      "beforeChange": [],
      "nearDuplicates": []
    },
    "places": {
      "farFromSpots": [],
      "zoneDiffers": [],
      "distanceTooShort": [],
      "searchLinks": []
    },
    "text": {
      "pastDates": [],
      "monthMismatch": [],
      "directions": []
    },
    "light": [],
    "pins": [],
    "agreementCurrent": true,
    "spotCount": 12,
    "archivedSpotCount": 1,
    "missingCoordinates": [
      {
        "spotId": "k17rwzt006kbqwjbs5jrqk4jjf5srec9",
        "title": "Lamar Valley"
      }
    ],
    "coordinateOutliers": [],
    "outlierThresholdKm": 1590,
    "outsideRegion": [],
    "spotsWithoutPhotos": [
      {
        "spotId": "k17rwzt006kbqwjbs5jrqk4jjf5srec9",
        "title": "Lamar Valley"
      },
      {
        "spotId": "k17hdgc1c8j423kgq30t9x5hyv1tv8yb",
        "title": "Taft Point"
      }
    ],
    "spotsWithoutText": [
      {
        "spotId": "k17rwzt006kbqwjbs5jrqk4jjf5srec9",
        "title": "Lamar Valley"
      }
    ],
    "photoCount": 31,
    "photosWithoutCredit": 0,
    "price": {
      "amountMinor": 2900,
      "currency": "usd"
    },
    "chapterCount": 5,
    "routeCount": 2,
    "region": {
      "label": "Yellowstone and Yosemite",
      "centerLat": 41.2,
      "centerLon": -115,
      "defaultZoom": 5,
      "bbox": [
        -120,
        37.4,
        -109.8,
        45.2
      ]
    },
    "storeTags": [
      "photography",
      "hiking",
      "road-trips"
    ],
    "country": "US",
    "hasThumbnail": false,
    "salesPage": {
      "draftProblems": [
        "the hero needs between 2 and 6 bullets"
      ],
      "exists": true,
      "published": false
    },
    "lastApiWriteAt": 1790586840000
  },
  "handoff": {
    "remaining": [
      "Publish guide: the creator puts the draft on sale in the studio (Publish)",
      "Publish sales page: the creator publishes the sales page draft in the studio"
    ],
    "studioUrl": "https://creators.sceniq.earth/products/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
    "salesPageUrl": "https://creators.sceniq.earth/products/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2/listing"
  },
  "reviewUrl": "https://creators.sceniq.earth/products/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "nextStep": "Resolve the blocking items, then ask the creator to review the draft in the dashboard"
}

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.