Search Documentation
Search for a documentation page...
Publish API
REST API endpoints for triggering and monitoring store publishes.
Publish your store programmatically – the API equivalent of the admin Publish button. Only stores with platform-managed deployments can use these endpoints.
A publish builds the store, deploys the build, checks that it built the commit you asked for, and points your domains at it. You get one publishId to follow the whole way.
Trigger Publish
Starts a production publish and returns 202 immediately – poll GET /api/v1/publish/{publishId} to track it.
This endpoint requires the store API key (sk-...). OAuth tokens are not accepted and will receive a 403.
Request Body (optional)
| Field | Type | Description |
|---|---|---|
source | "remote" | "workspace" | remote (default) publishes the commit the store repository's main branch points at, without touching the design workspace. workspace saves uncommitted work in the design workspace to main first and publishes that commit – the same as the admin Publish button. |
expectedSha | string | Optional, remote only – the full 40-character SHA you expect on main. If main is anywhere else, nothing is published and you get a 409. Sending it with source: "workspace" returns a 400. |
Response (202)
| Field | Type | Description |
|---|---|---|
publishId | string | Publish identifier – use it to poll status |
status | string | Always queued |
commitSha | string | null | Commit being published – what main pointed at, or the commit the workspace save created |
deploymentId | string | null | Deployment identifier, when the build already has one. Often null at this point – you never need it to follow the publish. |
deploymentUrl | string | null | Deployment URL, when known |
inspectorUrl | string | null | Build inspector URL, when available |
savedChanges | boolean | Whether uncommitted design-workspace work was saved for this publish. Always false for source: "remote" |
managedFilesRestored | string[] | Platform-managed files (instrumentation-client.ts, lib/track.tsx, proxy.ts) whose workspace edits were discarded and put back to the version on main. Those edits are not in this publish. Empty when nothing was restored |
Errors
| Status | Description |
|---|---|
400 | Store does not have a platform-managed deployment, the request body is invalid, or expectedSha was sent with source: "workspace" |
403 | Publishing requires the store API key (OAuth tokens are rejected) |
409 | Can't publish right now – a publish is already running, main is not at expectedSha, or the store's repository couldn't be read. With source: "workspace" also when the design workspace isn't running, doesn't exist yet, or its save collided with another push to main. The error message says which; retry once it clears. |
Get Publish Status
Returns the current status of a publish started via POST /api/v1/publish. Only the store's own publishes are visible.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
publishId | string | The publishId returned by POST /api/v1/publish |
Response (200)
| Field | Type | Description |
|---|---|---|
publishId | string | Publish identifier |
status | string | Where the publish is – see below |
readyState | string | The build's own state: QUEUED, BUILDING, INITIALIZING, READY, ERROR or CANCELED. READY means the build finished, not that it is live. |
deploymentId | string | null | Deployment identifier, once the build has one |
url | string | null | Deployment URL, once known |
commitSha | string | null | Commit being published |
reason | string | null | Plain-language explanation for domain_pending and failed |
Statuses
| Status | Description |
|---|---|
queued | Publish accepted, waiting for a build to start |
building | The store is being built |
verifying | Build finished – checking the commit and pointing the domains at it |
live | Your domains serve the new build (terminal) |
domain_pending | Built and deployed, but a domain isn't attached yet – usually a certificate still being issued. Not live; see reason (terminal) |
failed | Nothing new went live; see reason (terminal) |
Poll every few seconds until status is live, domain_pending or failed.
Errors
| Status | Description |
|---|---|
400 | Store does not have a platform-managed deployment |
404 | No such publish for this store, or a newer publish replaced it (only the running publish and the latest verdict are kept) |
Deployment lookup
The same endpoint also accepts a deployment ID (dpl_...) or a deployment URL or hostname instead of a publishId, and answers with that deployment's state:
Passing your store's hostname (for example your-store.yns.store) returns the deployment it currently serves. The answer covers the deployment alone and says nothing about whether your domains were pointed at it – prefer polling by publishId.