Publish API

REST API endpoints for triggering and monitoring store deployments.

Trigger a production deployment of your store programmatically – the API equivalent of the admin Publish button. Only stores with platform-managed deployments can use these endpoints.

Trigger Publish

POST /api/v1/publish

Starts a production build and deployment of the store's main branch. Returns 202 immediately with a publishId – poll GET /api/v1/publish/{publishId} to track progress.

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

Response (202)

{
  "publishId": "0199f0a1-7c3e-7a21-9f2d-6b1f0c4a8e55",
  "status": "queued",
  "deploymentId": "dpl_abc123",
  "deploymentUrl": "store-abc123.vercel.app",
  "inspectorUrl": "https://vercel.com/...",
  "savedChanges": true
}

Poll with publishId. A publish is followed by its own identifier whichever machine builds the store, so deploymentId, deploymentUrl and inspectorUrl are informational only and can be null until the build has a deployment.

Errors

Get Publish Status

GET /api/v1/publish/:publishId

Returns the current state of a publish started via POST /api/v1/publish. Only publishes belonging to the authenticated store are visible.

Path Parameters

curl -H "Authorization: Bearer sk_your_api_key" \
  https://your-store.yns.store/api/v1/publish/0199f0a1-7c3e-7a21-9f2d-6b1f0c4a8e55

Response (200)

{
  "publishId": "0199f0a1-7c3e-7a21-9f2d-6b1f0c4a8e55",
  "status": "building",
  "readyState": "BUILDING",
  "deploymentId": "dpl_abc123",
  "url": "store-abc123.vercel.app",
  "commitSha": "3f1c9a0d8b7e6f5a4c3b2a1908f7e6d5c4b3a291",
  "reason": null
}

Publish Statuses

Poll until status is terminal. A readyState of READY only means the build finished; live is the one status that means the publish is serving.

Errors

Get Deployment Status (legacy)

GET /api/v1/publish/:deploymentIdOrUrl

The same path also accepts a Vercel deployment id (dpl_...) or hostname, for callers written before publish ids existed. It answers with the deployment alone, which says nothing about whether domains were promoted – prefer polling by publishId.

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

Response (200)

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

Ready States

Errors