# get_publish_status

What buyers see, unpublished changes, and what blocks a publish.

`GET /v1/guides/{productId}/publish` · MCP tool `get_publish_status` · scope `read` · stable · since 2026-09-29

Whether the guide is live, the live version and when it went live, whether the draft holds changes buyers do not see yet (and the last edit time), whether a publish is still building (pendingSince), blocking: the publish gates, the same check publish_changes enforces, and warnings that do not block (facts past their review-by date, link problems). Read it before publish_changes, and poll it afterwards until pendingSince is null and published.version went up. Any key can read it.

## Path parameters

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

## Returns

200: PublishStatus.

- `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

### A live guide with unpublished changes and nothing blocking (a link warning does not block)

```bash
curl "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": "get_publish_status",
    "arguments": {
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2"
    }
  }
}
```

Response 200:

```json
{
  "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": null,
  "canPublishChanges": true,
  "nextStep": "Ready. Call publish_changes only when the creator asked you to publish."
}
```

### Polling after publish_changes: the build is in and the version went up

```bash
curl "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": "get_publish_status",
    "arguments": {
      "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2"
    }
  }
}
```

Response 200:

```json
{
  "productId": "j5738kd1q9x2m7v4c6b8n0p3r5t1w9y2",
  "name": "American West: Parks at First Light",
  "status": "published",
  "live": true,
  "published": {
    "publishedAt": 1790673249000,
    "version": 4
  },
  "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": false,
  "pendingSince": null,
  "canPublishChanges": false,
  "nextStep": "Buyers already see every change. Nothing to publish."
}
```

## 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/get_publish_status