SceniqDevelopers

publish_changes

Publish a live guide's draft changes to buyers.

POST/v1/guides/{productId}/publish
MCP tool publish_changesScope: publishStableSince 2026-09-29
Markdown

Only when the creator asks you to publish, and only after get_publish_status shows unpublished changes and no blocking items. Needs a key with the publish option (403 api_scope_required otherwise). Live guides only: a draft's first publish (putting it on sale), archiving, store visibility and the sales page stay in the dashboard. Runs the same build as the dashboard's Publish changes button; buyers keep the current version until the new one is in. Returns the queued state; then poll get_publish_status until pendingSince is null and published.version went up, usually within seconds. While a publish is still building, calling it again queues nothing new (queued false). Refused with 409 no_changes when buyers already see every change, 409 not_publishable with the blocking list, 409 not_live for a guide that is not on sale.

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

Path parameters

Returns

200 OK with PublishQueued: The publish status after publish_changes.

  • queuedbooleanrequired

    true when this call queued a build; false when one was already running.

  • productIdstring · guide idrequired

    The guide's id.

  • namestringrequired

    The guide's title.

  • statusstringrequired

    draft, published or archived.

    draftpublishedarchived
  • livebooleanrequired

    true when the guide is on sale.

  • publishedobject or nullrequired

    What buyers see, or null before the first build.

    Show 2 fields
    • publishedAtnumberrequired

      When the live version went live (Unix time in milliseconds).

    • versionnumber or nullrequired

      The live version's number.

  • hasUnpublishedChangesbooleanrequired

    true when the draft holds changes buyers do not see yet.

  • lastEditAtnumber or nullrequired

    When the draft last changed.

  • pendingSincenumber or nullrequired

    When a publish started building; null when none is running.

  • blockingarray of PublishGaterequired

    The publish gates that are open.

    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

    Problems that do not block: review_due, stale_facts, link_problems.

    Show 2 fields
    • codestringrequired

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

    • messagestringrequired

      What it means, in plain words.

  • canPublishChangesbooleanrequired

    true when publish_changes would queue a build now.

  • nextStepstringrequired

    One sentence on what to do next.

  • reviewUrlstringrequired

    The guide in the studio.

Response 200
{
  "queued": true,
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "name": "American West: Parks at First Light",
  "status": "published",
  "live": true,
  "published": {
    "publishedAt": 1790241240000,
    "version": 3
  },
  "lastEditAt": 1790586840000,
  "blocking": [],
  "warnings": [
    {
      "code": "link_problems",
      "message": "1 link(s) look dead, parked or redirected; see get_link_report"
    }
  ],
  "reviewUrl": "https://creators.sceniq.earth/products/j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "hasUnpublishedChanges": true,
  "pendingSince": 1790673240000,
  "canPublishChanges": false,
  "nextStep": "A publish is building. Poll get_publish_status until pendingSince is null and published.version went up (usually seconds)."
}

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.
  • 409not_publishablepublish_changes while a gate is open: the agreement, no live spot, a live spot without a pin or a photo, no price. details.blocking lists each gate as { code, message }.
  • 409not_livepublish_changes on a draft or archived guide. A draft's first publish happens in the studio.
  • 409no_changespublish_changes when buyers already see every change.
  • 409agreement_outdatedA price change or a publish before the creator accepted the current creator agreement.
  • 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.