Pages API

Jason Lee Jason Lee
4 min read

The Pages API allows you to create and update content programmatically. Use it to publish blog posts, documentation, or any other content to your Sitepaste site.

Endpoint

POST /api/v1/public/pages

Authentication: Bearer token (required)

Rate limit: 60 requests per minute

Create or update a page

This endpoint creates a new page or updates an existing page if a page with the same slug already exists.

Request

Headers:

Authorization: Bearer sp_your_token_here
Content-Type: application/json

Body parameters:

ParameterTypeRequiredDescription
titlestringYesPage title (max 200 characters)
contentstringYesPage content in Markdown format
slugstringNoURL-friendly identifier (auto-generated from title if omitted)
contentTypestringNoEither "blog" or "docs" (defaults to "blog")
draftbooleanNoIf true, page is saved as draft (defaults to false - published)
tagsarrayNoArray of tag strings (max 10 tags, each max 50 characters)
publishedAtstringNoISO 8601 timestamp (not currently used in UI)

Example request

curl -X POST https://sitepaste.com/api/v1/public/pages \
  -H "Authorization: Bearer sp_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started with the API",
    "content": "# Getting Started\n\nThis guide will help you...",
    "contentType": "docs",
    "slug": "getting-started",
    "draft": false,
    "tags": ["tutorial", "api", "getting-started"]
  }'

Response

Status: 200 OK

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "slug": "getting-started",
  "title": "Getting Started with the API",
  "draft": false,
  "contentType": "docs",
  "createdAt": "2025-10-31T12:00:00Z",
  "updatedAt": "2025-10-31T12:00:00Z"
}

Note: The full page content is not returned in the response. Only metadata is included.

Field details

Title

  • Required: Yes
  • Max length: 200 characters
  • Usage: Displayed as the page heading and used to generate the slug if not provided
{
  "title": "My Amazing Blog Post"
}

Content

  • Required: Yes
  • Format: Markdown
  • Max length: 1,000,000 characters (1MB)
  • Usage: The main body of your page, rendered as HTML on your site
{
  "content": "# Hello World\n\nThis is my **first** post via API!\n\n## Features\n\n- Easy to use\n- Markdown support\n- Fast deployment"
}

Slug

  • Required: No (auto-generated from title)
  • Format: Lowercase alphanumeric characters and hyphens only
  • Max length: 100 characters
  • Usage: URL path for the page (e.g., https://yourusername.sitepaste.com/getting-started)

Auto-generation rules:

  • Converts title to lowercase
  • Replaces spaces with hyphens
  • Removes special characters
  • If slug exists, appends -1, -2, etc.
{
  "slug": "custom-url-slug"
}

Examples:

  • Title: “Hello World” → Slug: hello-world
  • Title: “My Post!!!” → Slug: my-post
  • Title: “API Guide (2024)” → Slug: api-guide-2024

Content type

  • Required: No
  • Default: "blog"
  • Options: "blog" or "docs"
  • Usage: Determines how the page is categorized and displayed
{
  "contentType": "docs"
}

Draft

  • Required: No
  • Default: false (published)
  • Usage: If true, page is saved but not visible on your public site
{
  "draft": true
}

Use cases for drafts:

  • Work-in-progress content
  • Scheduled publishing workflows
  • Review processes

Tags

  • Required: No
  • Format: Array of strings
  • Limits: Max 10 tags, each max 50 characters
  • Usage: Categorize and organize your content
{
  "tags": ["tutorial", "api", "beginner-friendly"]
}

Update behavior

The endpoint uses upsert logic - if a page with the same slug exists, it updates that page; otherwise, it creates a new one.

To update an existing page:

  1. Use the same slug as the existing page
  2. All fields will be updated with the new values
  3. Tags are completely replaced (not merged)

Example:

# First request - creates a page
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", "slug": "my-post", "content": "Version 1"}'

# Second request - updates the same page
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 Updated Post", "slug": "my-post", "content": "Version 2"}'

The second request updates the existing page at my-post rather than creating a new one.

Error responses

Missing required field

Status: 400 Bad Request

{
  "error": "title is required"
}

Invalid content type

Status: 400 Bad Request

{
  "error": "contentType must be either 'blog' or 'docs'"
}

Invalid slug

Status: 400 Bad Request

{
  "error": "slug can only contain lowercase letters, numbers, and hyphens"
}

Content too long

Status: 400 Bad Request

{
  "error": "content exceeds maximum length of 1000000 characters"
}

Too many tags

Status: 400 Bad Request

{
  "error": "maximum 10 tags allowed"
}

Rate limit exceeded

Status: 429 Too Many Requests

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

Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 60

See Rate Limiting for details.

Complete example

Here’s a complete example showing how to create a documentation page with all fields:

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": "API Authentication Guide",
    "slug": "api-authentication",
    "content": "# API Authentication Guide\n\n## Overview\n\nThis guide covers everything you need to know about authenticating with our API.\n\n## Getting Started\n\n1. Create an API token\n2. Include it in requests\n3. Start building!\n\n## Example\n\n```bash\ncurl -H \"Authorization: Bearer sp_token\" https://api.example.com\n```\n\n## Security\n\nAlways keep your tokens secret and rotate them regularly.",
    "contentType": "docs",
    "draft": false,
    "tags": ["authentication", "security", "getting-started"]
  }'

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "slug": "api-authentication",
  "title": "API Authentication Guide",
  "draft": false,
  "contentType": "docs",
  "createdAt": "2025-10-31T14:30:00Z",
  "updatedAt": "2025-10-31T14:30:00Z"
}

Next steps

After creating pages:

  • Trigger a build to deploy your changes
  • Check rate limits to optimize your workflow
  • Visit your site at https://yourusername.sitepaste.com/api-authentication