Manage without the UI.

The Agent API exposes your site at /_studio/api/agent/v1. Stateless, JSON-based, scoped by role. Create pages, upload assets, trigger publishes, read submissions — all via HTTP.

Bearer token auth

API keys with a vxs_ prefix, 64 hex characters. SHA-256 hashed — never stored in plain text. Generate, label, and revoke keys from the Studio.

Role-based access

Three roles in the Studio — Agent, Editor, Viewer — each with a distinct scope ceiling and rate limit. Keys inherit their role's permissions. No over-provisioning.

OpenAPI schema

A public GET /schema endpoint returns the OpenAPI 3.0.3 specification. Import it into Postman, agent frameworks, or code generators. No authentication required.

The request flow.

An agent authenticates with a Bearer token, the API validates scopes, and the request reaches your site's engine. Structured JSON in, structured JSON out.

AI Agent "Create a new page"

Auth + Scopes Bearer token, CORS

Router Matches endpoint

Your Site Executes request

agent → your site (REST)

POST /_studio/api/agent/v1/pages
// Authorization: Bearer vxs_a8f3k2m1...

{
  "slug": "spring-menu",
  "title": "Spring Menu 2026",
  "content": "<?php $page = ['title' => 'Spring Menu 2026']; ?>..."
}

// → 201 Created
{
  "data": {
    "page": {
      "slug": "spring-menu",
      "title": "Spring Menu 2026",
      "file_path": "spring-menu.php"
    }
  }
}

What's available.

Eight endpoint groups covering the full content lifecycle. All responses are JSON with consistent error shapes.

1

Pages

GET POST PUT DELETE /pages — list, create, read, update, and delete pages. Automatic slug normalization, navigation sync, and internal link rewriting.

2

Assets

GET POST /assets — list uploaded assets by category (images, css, js, files) and upload new ones via multipart form data. Category allowlist enforced.

3

Compile

POST /compile — trigger Tailwind CSS recompilation after page changes. The server compiles synchronously and returns the result. No Node.js needed.

4

Publish

POST /publish — trigger the full publish pipeline: compile CSS, copy preview files to production, generate sitemap and robots.txt.

5

Settings

GET PUT /settings — read and update site settings. Write access restricted to Owner keys. Whitelist-controlled — only approved keys can be set.

6

Submissions

GET /submissions — list form and action submissions with pagination, filtering, and merged sorting. Read-only access across all roles.

7

Tools

GET /tools and POST /tools/invoke — list available MCP/Action tools and invoke them programmatically. Same validation as the built-in MCP server.

8

Schema

GET /schema — public OpenAPI 3.0.3 specification. No auth required. Agents discover the full contract before authenticating.

Least privilege
by default.

Each API key is bound to a role. The role determines which scopes the key can access and its rate limit. You can't escalate a Viewer key to write pages.

The Agent role covers full automation: pages, assets, compile, publish, submissions, and tools. It intentionally excludes settings:write — an agent should not be able to disable the API or change allowed origins.

Per-key rate limiting is enforced server-side. Agent keys get 300 requests per hour. Every denied request is logged with IP and user agent.

Scope	Agent	Editor	Viewer
pages:read	✓	✓	✓
pages:write	✓	✓	—
publish	✓	—	—
assets	✓	✓	read
tools	✓	✓	—
Rate limit	300/hr	500/hr	200/hr

What this opens up.

An AI agent generates seasonal landing pages and publishes them — without opening the Studio. A Zapier workflow creates a page when a CRM deal closes. A Make scenario uploads images from a content bank.

A CI/CD pipeline reads pages from staging, diffs content, and pushes updates to production. A monitoring script reads submissions every hour and forwards new ones to Slack.

Standard REST. Standard Bearer auth. Any HTTP-capable tool works.

8 endpoint groups

Pages, assets, compile, publish, settings, submissions, tools, schema

3 roles

Agent, Editor, Viewer — each with distinct scope ceilings and rate limits

100%

Reuses the same page and publish services as the Studio UI

Runs on your server.

The Agent API is not a cloud service. It is part of your VoxelSite installation. Your server, your data, your logs. Nothing leaves your hosting.

External integrations AI agents, Zapier, Make, n8n, custom scripts

Agent API router Auth, CORS, rate limits, scope enforcement

VoxelSite engine PageService, PublishService, Tailwind compiler

SQLite storage Local · Portable · Your server

Agent API vs MCP.

VoxelSite exposes two machine-readable interfaces. They serve different purposes.

	Agent API	MCP Endpoint
Purpose	Manage the site (pages, settings, publish)	Query the site (business info, menus, forms)
Auth	Bearer token (API key)	None (public)
Audience	Site owner's tools & automations	Any AI agent on the internet
Write access	Yes	Limited (form submissions)
Schema	OpenAPI 3.0	MCP tool definitions

The MCP endpoint serves public data (with limited write access for form submissions). The Agent API is a private management surface behind authentication.

Questions.

What can the Agent API do today?

Create, read, update, and delete pages. Upload and list assets. Trigger Tailwind CSS recompilation. Publish to production. Read and update site settings. List form and action submissions. List and invoke MCP tools programmatically. Access the OpenAPI schema — all via standard REST with Bearer auth.

How is it different from MCP?

The MCP endpoint is public and read-only — it lets any AI agent discover your site's content, menus, and forms. The Agent API is private: it requires authentication, and it can write data. Think of MCP as the "read" interface for the world and the Agent API as the "manage" interface for the site owner.

Does it work on Nginx?

Yes. Routing works automatically via the Studio router fallback — no Nginx rewrite rule is required. The only Nginx-specific requirement is adding fastcgi_param HTTP_AUTHORIZATION $http_authorization; inside your PHP location block, so Nginx forwards the Bearer token to PHP. See Nginx Configuration for the exact setup.

Is the API public or private?

Private. The Agent API is disabled by default and requires explicit activation in Settings → API Access. Every request must include a valid Bearer token. The only public endpoint is GET /schema, which returns the OpenAPI specification so agents can discover available endpoints before authenticating.

Included with VoxelSite

Your site,
programmable.

The Agent API ships with every VoxelSite license. Enable it in Settings, generate a key, start integrating. Currently in beta — see the docs for details.

Get VoxelSite Read the docs

Self-hosted · Full source code · No monthly fees

REST for agents. A Studio for humans.

Your sitehas an API.