# publish_changes

Publish a live guide's draft changes to buyers.

`POST /v1/guides/{productId}/publish` · MCP tool `publish_changes` · scope `publish` · stable · since 2026-09-29

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.

## Path parameters

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

## Returns

200: PublishQueued.

- `queued` (boolean, required): true when this call queued a build; false when one was already running.
- `productId` (string, required): The guide's id.
- `name` (string, required): The guide's title.
- `status` (string, required): draft, published or archived. One of `draft`, `published`, `archived`.
- `live` (boolean, required): true when the guide is on sale.
- `published` (object or null, required): What buyers see, or null before the first build.
  - `publishedAt` (number, required): When the live version went live (Unix time in milliseconds).
  - `version` (number or null, required): The live version's number.
- `hasUnpublishedChanges` (boolean, required): true when the draft holds changes buyers do not see yet.
- `lastEditAt` (number or null, required): When the draft last changed.
- `pendingSince` (number or null, required): When a publish started building; null when none is running.
- `blocking` (array of PublishGate, required): The publish gates that are open.
  Fields of PublishGate: https://developers.sceniq.earth/fields/publish-gate.md
- `warnings` (array of objects, required): Problems that do not block: review_due, stale_facts, link_problems.
  - `code` (string, required): A stable code for the warning (see the readiness guide for the list).
  - `message` (string, required): What it means, in plain words.
- `canPublishChanges` (boolean, required): true when publish_changes would queue a build now.
- `nextStep` (string, required): One sentence on what to do next.
- `reviewUrl` (string, required): The guide in the studio.

## Examples

### Publish the draft changes the creator asked for; the build is queued

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

MCP `tools/call`:

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

Response 200:

```json
{
  "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)."
}
```

### Calling again while the build runs queues nothing new

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

MCP `tools/call`:

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

Response 200:

```json
{
  "queued": false,
  "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

- `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).
- `invalid_request` (400): A 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.
- `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.
- `api_scope_required` (403): A read-only key called a write operation, or a key without the publish option called publish_changes.
- `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.
- `not_publishable` (409): publish_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 }.
- `not_live` (409): publish_changes on a draft or archived guide. A draft's first publish happens in the studio.
- `no_changes` (409): publish_changes when buyers already see every change.
- `agreement_outdated` (409): A price change or a publish before the creator accepted the current creator agreement.
- `payload_too_large` (413): A JSON body over 2 MB, an image over 6 MB, a batch upload over 19 MB, or an MCP message over 2 MB.
- `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/publish_changes