Introduction

Jason Lee Jason Lee
2 min read

Welcome to the Sitepaste API. This API allows Pro plan users to programmatically manage their sites, create content, and trigger deployments without using the web dashboard.

What you can do

With the Sitepaste API, you can:

  • Create and update pages: Publish blog posts and documentation programmatically
  • Trigger builds: Deploy your site after making content changes
  • Automate workflows: Integrate with CI/CD pipelines, CMSs, or custom tools
  • Build integrations: Connect Sitepaste with your favorite writing or publishing tools

Who is this for?

The API is perfect for:

  • Developers building custom publishing workflows
  • Content teams using headless CMS systems
  • DevOps engineers automating documentation deployments
  • Power users who prefer CLI tools over web interfaces

Prerequisites

Before using the API, you’ll need:

  1. An active Pro plan subscription: API access is exclusive to Pro users
  2. An API token: Created from your dashboard (see Authentication)
  3. Basic HTTP knowledge: Familiarity with REST APIs and JSON

API overview

Base URL

https://sitepaste.com/api/v1

Authentication

All API requests require a bearer token in the Authorization header:

Authorization: Bearer sp_your_token_here

Request format

API requests accept JSON request bodies:

curl -X POST https://sitepaste.com/api/v1/public/pages \
  -H "Authorization: Bearer sp_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Post", "content": "Hello World"}'

Response format

All successful responses return JSON with appropriate HTTP status codes:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "slug": "my-post",
  "title": "My Post",
  "draft": false,
  "contentType": "blog",
  "createdAt": "2025-10-31T12:00:00Z",
  "updatedAt": "2025-10-31T12:00:00Z"
}

Error responses include an error field:

{
  "error": "title is required"
}

Common HTTP status codes

  • 200 OK: Request succeeded
  • 202 Accepted: Request accepted (async operations like builds)
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Missing or invalid authentication token
  • 403 Forbidden: Pro plan required or insufficient permissions
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error (contact support if persistent)

Next steps

Ready to start using the API?

  1. Create an API token from your dashboard
  2. Learn about the Pages API to manage content
  3. Explore the Builds API to trigger deployments

Example workflow

Here’s a typical workflow using the API:

# 1. Create a new blog post
TOKEN="sp_your_token_here"

curl -X POST https://sitepaste.com/api/v1/public/pages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Introducing Our New API",
    "content": "# Introducing Our New API\n\nWe are excited to announce...",
    "contentType": "blog",
    "tags": ["announcements", "api"]
  }'

# 2. Trigger a build to publish the changes
curl -X POST https://sitepaste.com/api/v1/public/builds \
  -H "Authorization: Bearer $TOKEN"

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

That’s it! Your content is now published and deployed.