REST API

The Pagesmith REST API provides programmatic access to manage your sites. Use it to build integrations, automate deployments, or connect external CMS tools.

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer ps_live_your_key_here

Get your API key from API Keys settings. Keys have three scopes: read, write, and deploy.

Base URL

https://pagesmith.ai/api/external

Rate Limits

• Read operations: 60 requests per minute
• Write operations: 10 requests per minute

When rate limited, the response includes a Retry-After header with seconds to wait.

Endpoints

Projects

List Projects

GET /projects

Returns all projects for the authenticated account.

{
  "projects": [
    {
      "id": "uuid",
      "name": "My Site",
      "preview_url": "https://abc123-preview.pagesmith.app",
      "published_url": "https://example.com",
      "domains": ["example.com"],
      "ssr": false,
      "published_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-04-20T14:30:00Z",
      "created_at": "2026-01-10T09:00:00Z"
    }
  ]
}

Files

Pull Files

GET /projects/:id/files

Returns the file tree. Add ?content=true to include file contents (for bulk download).

GET /projects/:id/files?path=src/pages/index.astro

Returns a single file’s content.

Push Files

POST /projects/:id/files

{
  "files": [
    { "path": "src/pages/about.astro", "content": "---\nimport BaseLayout..." }
  ],
  "deletions": ["src/pages/old-page.astro"],
  "message": "add about page"
}

Triggers a build workflow: validates code, commits, builds preview, and auto-fixes errors. Returns a message_id for polling.

Limits: 50 files per push, 500KB per file, 5MB total payload.

Allowed paths: src/, public/, astro.config.*, package.json, tsconfig.json, tailwind.config.*

Costs 2 credits.

Poll Status

GET /projects/:id/prompt/:messageId

Poll for the result of a push, prompt, or content operation.

{
  "status": "completed",
  "response": "Pushed 3 files. Preview updated.",
  "preview_url": "https://abc123-preview.pagesmith.app"
}

Status values: processing, completed, failed.

Deploy and Publish

Deploy (Rebuild Preview)

POST /projects/:id/deploy

Rebuilds the preview without changing files.

Publish to Production

POST /projects/:id/publish

Optional body:

{
  "domain": "example.com"
}

AI Editing

Send Prompt

POST /projects/:id/prompt

{
  "prompt": "Add a contact page with a form"
}

Returns a message_id for polling. Uses the same AI and credit system as the web editor.

Content (CMS)

List Collections

GET /projects/:id/content

List Posts

GET /projects/:id/content/:collection

Get Post

GET /projects/:id/content/:collection/:slug

Create Post

POST /projects/:id/content/:collection

{
  "slug": "my-post",
  "frontmatter": {
    "title": "My Post",
    "description": "A blog post",
    "pubDate": "2026-04-21"
  },
  "body": "# Hello\n\nPost content here."
}

Update Post

PUT /projects/:id/content/:collection/:slug

{
  "frontmatter": { "title": "Updated Title" },
  "body": "Updated content."
}

Delete Post

DELETE /projects/:id/content/:collection/:slug

Domains

List Domains

GET /projects/:id/domains

Connect Domain

POST /projects/:id/domains

{
  "domain": "example.com",
  "dns_method": "nameserver"
}

dns_method is either "nameserver" (Pagesmith manages DNS) or "cname" (you manage DNS).

Domain Actions

POST /projects/:id/domains/:domainId

{
  "action": "verify"
}

Actions: verify, set-primary, refresh-ssl.

Remove Domain

DELETE /projects/:id/domains/:domainId

Secrets

List Secrets

GET /projects/:id/secrets

Returns integration types and secret names (never values).

Set Secrets

POST /projects/:id/secrets

{
  "integration_type": "mailchimp",
  "environment": "preview",
  "secrets": {
    "API_KEY": "mc_abc123"
  }
}

Error Responses

All errors follow this format:

{
  "error": "Description of the error"
}