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

POST /api/v1/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.

curl -X POST \
-H "Authorization: Bearer sk_your_api_key" \
https://your-store.yns.store/api/v1/publish

Request Body (optional)

FieldTypeDescription
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.
expectedShastringOptional, 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.
curl -X POST \
-H "Authorization: Bearer sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{"expectedSha":"191fe446aa98ce1bced97585adbb910d7ebbeebb"}' \
https://your-store.yns.store/api/v1/publish

Response (202)

{
"publishId": "019642c4-699d-729a-b606-0000000000a1",
"status": "queued",
"commitSha": "191fe446aa98ce1bced97585adbb910d7ebbeebb",
"deploymentId": null,
"deploymentUrl": null,
"inspectorUrl": null,
"savedChanges": false,
"managedFilesRestored": []
}
FieldTypeDescription
publishIdstringPublish identifier – use it to poll status
statusstringAlways queued
commitShastring | nullCommit being published – what main pointed at, or the commit the workspace save created
deploymentIdstring | nullDeployment identifier, when the build already has one. Often null at this point – you never need it to follow the publish.
deploymentUrlstring | nullDeployment URL, when known
inspectorUrlstring | nullBuild inspector URL, when available
savedChangesbooleanWhether uncommitted design-workspace work was saved for this publish. Always false for source: "remote"
managedFilesRestoredstring[]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

StatusDescription
400Store does not have a platform-managed deployment, the request body is invalid, or expectedSha was sent with source: "workspace"
403Publishing requires the store API key (OAuth tokens are rejected)
409Can'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

GET /api/v1/publish/:publishId

Returns the current status of a publish started via POST /api/v1/publish. Only the store's own publishes are visible.

Path Parameters

ParameterTypeDescription
publishIdstringThe publishId returned by POST /api/v1/publish
curl -H "Authorization: Bearer sk_your_api_key" \
https://your-store.yns.store/api/v1/publish/019642c4-699d-729a-b606-0000000000a1

Response (200)

{
"publishId": "019642c4-699d-729a-b606-0000000000a1",
"status": "building",
"readyState": "BUILDING",
"deploymentId": null,
"url": null,
"commitSha": "191fe446aa98ce1bced97585adbb910d7ebbeebb",
"reason": null
}
FieldTypeDescription
publishIdstringPublish identifier
statusstringWhere the publish is – see below
readyStatestringThe build's own state: QUEUED, BUILDING, INITIALIZING, READY, ERROR or CANCELED. READY means the build finished, not that it is live.
deploymentIdstring | nullDeployment identifier, once the build has one
urlstring | nullDeployment URL, once known
commitShastring | nullCommit being published
reasonstring | nullPlain-language explanation for domain_pending and failed

Statuses

StatusDescription
queuedPublish accepted, waiting for a build to start
buildingThe store is being built
verifyingBuild finished – checking the commit and pointing the domains at it
liveYour domains serve the new build (terminal)
domain_pendingBuilt and deployed, but a domain isn't attached yet – usually a certificate still being issued. Not live; see reason (terminal)
failedNothing new went live; see reason (terminal)

Poll every few seconds until status is live, domain_pending or failed.

Errors

StatusDescription
400Store does not have a platform-managed deployment
404No 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:

{
"id": "dpl_abc123",
"url": "store-abc123.vercel.app",
"readyState": "READY"
}

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.