Builds

After creating or updating pages, trigger a build to publish your changes. You can trigger a build as part of a POST /pages request using "build": true, or separately with the builds endpoint.

POST /builds

Queue a site build.

Request

curl -X POST https://sitepaste.com/api/v1/public/builds \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId": "optional-site-uuid"}'

The request body is optional. If omitted, the build targets your default site.

Field	Type	Description
siteId	string	Target site UUID. Falls back to your default site if omitted.

Response: 202 Accepted

{
  "status": "queued",
  "deployUrl": "https://yourusername.sitepaste.com",
  "message": "build queued successfully"
}

Build quotas

Builds are subject to monthly quotas based on your plan:

Plan	Monthly builds
Free	3
Simple	100
Pro	1,000

There is a 30-second cooldown between builds.

Quota exceeded: 402 Payment required

{
  "error": "build quota exceeded",
  "message": "Monthly build limit of 1000 reached. Upgrade your plan or wait for the next billing cycle."
}

Cooldown active: 429 Too many requests

{
  "error": "build cooldown active",
  "message": "Please wait 20 seconds before triggering another build."
}

GET /builds/latest

Get the status of the most recent build for a site. Useful for polling build completion after triggering a deploy.

Request

curl https://sitepaste.com/api/v1/public/builds/latest \
  -H "Authorization: Bearer $TOKEN"

Query parameters:

Parameter	Description
siteId	Target site UUID. Falls back to your default site if omitted.

Response: 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "triggeredBy": "api",
  "durationMs": 4523,
  "startedAt": "2026-02-08T12:00:01Z",
  "completedAt": "2026-02-08T12:00:05Z",
  "createdAt": "2026-02-08T12:00:00Z"
}

The status field is one of queued, running, success, or failed.

Returns 404 if no builds exist for the site.

Polling for completion

After triggering a build, poll this endpoint until status is success or failed:

while true; do
  STATUS=$(curl -s https://sitepaste.com/api/v1/public/builds/latest \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  echo "Build status: $STATUS"
  if [ "$STATUS" = "success" ] || [ "$STATUS" = "failed" ]; then
    break
  fi
  sleep 2
done

Build via POST /pages

You can also trigger a build as part of a page request by setting "build": true in the payload:

{
  "pages": [{"slug": "my-page", "draft": false}],
  "build": true
}

The build is queued after all page operations commit. If the build fails (quota exceeded, cooldown active), the pages are still saved and the build error is included in the response:

{
  "pages": [...],
  "build": {
    "error": "build quota exceeded",
    "message": "Monthly build limit of 1000 reached."
  }
}