Overview

The SpiderPublish REST API is the foundation everything else is built on — the dashboard, the CLI, the MCP tools, and the editor extension are all clients of these same endpoints. Anything they can do, you can do directly over HTTP.

Base URL

https://spideriq.ai/api/v1

All paths in this reference are relative to that base. For example, GET /content/pages is https://spideriq.ai/api/v1/content/pages.

Two kinds of endpoints

  • Public read endpoints — under /content/.... No authentication. They serve your published content and are scoped to a site by the request's host (the X-Content-Domain header the renderer sends). These power the live site, sitemaps, and AI-crawler surfaces.

  • Dashboard endpoints — under /dashboard/content/.... These create and change content. They require a bearer token and are scoped to your workspace and project.

Dashboard endpoints are also available in a project-scoped form:

/api/v1/dashboard/content/{resource}                       # workspace default project
/api/v1/dashboard/projects/{project_id}/content/{resource} # explicit project

Both are served by the same handlers. Use the project-scoped form when a workspace runs more than one site.

Authentication

Dashboard endpoints take a bearer token built from your client id, API key, and API secret:

Authorization: Bearer <client_id>:<api_key>:<api_secret>

See Authentication for how to obtain one. Public endpoints need no auth.

The dry-run / confirm flow

Destructive endpoints (publish, unpublish, delete, deploy, apply-theme, and similar) support a safe two-step flow, controlled by two query parameters:

  • dry_run=true — returns a preview plus a single-use confirm_token. Nothing changes.

  • confirm_token=<token> — re-send the request with the token to actually apply the change.

# Step 1 — preview
curl -X POST "https://spideriq.ai/api/v1/dashboard/content/pages/PAGE_ID/publish?dry_run=true" \
  -H "Authorization: Bearer $TOKEN"
# → { "dry_run": true, "confirm_token": "cft_…", "preview": { … } }

# Step 2 — confirm
curl -X POST "https://spideriq.ai/api/v1/dashboard/content/pages/PAGE_ID/publish?confirm_token=cft_…" \
  -H "Authorization: Bearer $TOKEN"

A token is single-use, time-limited, and bound to the exact change it previewed — if the content shifts underneath it, the confirm is refused. See Safe Publishing for the full model.

Response formats

Most read endpoints can return YAML or Markdown as well as JSON, which is more compact for AI agents. Add ?format=yaml or ?format=md:

curl "https://spideriq.ai/api/v1/content/posts?format=yaml"

Errors

Errors return a JSON body with a clear shape, for example:

{
  "error": {
    "code": "not_found",
    "message": "Page not found",
    "suggested_action": "List pages with GET /content/pages to find a valid slug"
  }
}

Status codes follow REST conventions: 200 OK, 201 created, 202 accepted (async build), 204 deleted, 401/403 auth, 404 not found, 409/410/423 for confirm-token conflicts and locks, 422 validation.

A self-describing reference for agents

GET /content/help returns a compact, machine-readable description of every content type, block type, Liquid filter, and common recipe — designed for an AI agent to load once and then build correctly. See Public & SEO Surfaces.

In this section