Builds API

Jason Lee Jason Lee
4 min read

The Builds API allows you to trigger deployments of your site programmatically. After creating or updating pages via the API, trigger a build to publish your changes.

Endpoint

POST /api/v1/public/builds

Authentication: Bearer token (required)

Rate Limit: 20 requests per hour (per business account)

Trigger a build

Queues a build job to regenerate and deploy your site with the latest content changes.

Request

Headers:

Authorization: Bearer sp_your_token_here

Body: None (no request body required)

Example request

curl -X POST https://sitepaste.com/api/v1/public/builds \
  -H "Authorization: Bearer sp_your_token_here"

Response

Status: 202 Accepted

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

Response fields:

FieldTypeDescription
statusstringBuild status (always "queued" when triggered)
deployUrlstringURL where your site will be deployed
messagestringHuman-readable confirmation message

Build process

When you trigger a build:

  1. Job Queued: Build job is added to the queue (you receive the 202 Accepted response)
  2. Processing: Site generator processes your pages and authors
  3. Static files generated: HTML, CSS, and assets are created
  4. Deployment: Files are deployed to your site URL
  5. Live: Changes are visible at your deploy URL

Typical build time: 1-30 seconds depending on site size

When to trigger builds

  • After batch content updates: Create multiple pages, then trigger one build
  • On a schedule: Use cron jobs to publish scheduled content
  • In CI/CD pipelines: Deploy docs when code is merged
  • After configuration changes: Rebuild when site settings are updated
  • After every single page: Use batch operations instead (respect rate limits)
  • For previews: Use draft mode and manual preview builds from the dashboard
  • Excessively frequent: Builds are rate limited to prevent abuse

Rate limiting

Builds are expensive operations that consume server resources. They are strictly rate limited:

  • Limit: 20 builds per hour
  • Scope: Per business account (shared across all tokens)
  • Reset: Sliding 60-minute window

Rate limit headers are included in the response:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19

See Rate limiting for details.

Error responses

Rate limit exceeded

Status: 429 Too Many Requests

{
  "error": "rate limit exceeded",
  "message": "too many requests, please try again later"
}

Headers:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
Retry-After: 3600

Solution: Wait for the time specified in Retry-After (seconds) before triggering another build.

Unauthorized

Status: 401 Unauthorized

{
  "error": "invalid or revoked token"
}

Causes:

  • Missing or invalid bearer token
  • Token has been revoked
  • Pro plan subscription expired

Workflow examples

Example 1: Create and deploy content

TOKEN="sp_your_token_here"
API_BASE="https://sitepaste.com/api/v1"

# Create multiple pages
curl -X POST "$API_BASE/public/pages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Introduction",
    "content": "# Welcome\n\nGet started here...",
    "contentType": "docs"
  }'

curl -X POST "$API_BASE/public/pages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Installation",
    "content": "# Installation\n\nFollow these steps...",
    "contentType": "docs"
  }'

curl -X POST "$API_BASE/public/pages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Reference",
    "content": "# API Reference\n\nComplete endpoint docs...",
    "contentType": "docs"
  }'

# Trigger a single build to deploy all changes
curl -X POST "$API_BASE/public/builds" \
  -H "Authorization: Bearer $TOKEN"

Example 2: CI/CD pipeline integration

# .github/workflows/deploy-docs.yml
name: Deploy Documentation

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Convert docs to API format
        run: |
          # Your script to convert markdown to API requests
          ./scripts/generate-api-payload.sh

      - name: Upload to Sitepaste
        env:
          SITEPASTE_TOKEN: ${{ secrets.SITEPASTE_TOKEN }}
        run: |
          # Upload all docs
          for file in docs/*.md; do
            ./scripts/upload-page.sh "$file"
          done

      - name: Trigger Build
        env:
          SITEPASTE_TOKEN: ${{ secrets.SITEPASTE_TOKEN }}
        run: |
          curl -X POST https://sitepaste.com/api/v1/public/builds \
            -H "Authorization: Bearer $SITEPASTE_TOKEN"

Example 3: Scheduled publishing with cron

#!/bin/bash
# publish-scheduled.sh
# Run this with cron: 0 9 * * * /path/to/publish-scheduled.sh

TOKEN="sp_your_token_here"
API_BASE="https://sitepaste.com/api/v1"

# Update draft posts to published
# (You would maintain a local list of posts to publish)

curl -X POST "$API_BASE/public/pages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "scheduled-post",
    "title": "This Post Goes Live at 9 AM",
    "content": "# Hello!\n\nThis was scheduled.",
    "draft": false
  }'

# Trigger build to publish
curl -X POST "$API_BASE/public/builds" \
  -H "Authorization: Bearer $TOKEN"

Monitoring build status

Currently, the API returns 202 Accepted immediately when a build is queued. The build happens asynchronously.

To check if your build completed:

  • Visit your deploy URL and verify the changes are live
  • Check the dashboard’s “Builds” section for build history
  • Monitor the updated_at timestamp of your build

Note: A dedicated build status endpoint may be added in the future.

Best practices

  1. Batch your updates - Create/update multiple pages, then trigger one build
  2. Check rate limits - Monitor X-RateLimit-Remaining header
  3. Handle errors gracefully - Implement retry logic with exponential backoff
  4. Use webhooks (future) - Subscribe to build completion events when available
  5. Test in development - Verify your workflow before running in production

Next steps