Guide

editor-ui API and MCP for scripts

Everything the editor panel does goes through an API that a script or an AI assistant can use too: REST routes under /editor/api/ and an MCP endpoint at /editor/mcp, both behind an auth token. Both call the same operations with the same permission checks, so an assistant can do exactly what its token allows and is refused exactly where a person would be. The full contract is openapi.yaml; the reference with every field is the README's API section. designer-ui has the same shape for settings and theme files (DESIGNER).

Signing in as a machine

A script uses an auth service token (ssgsvc_…), never a person's password. Create a service account and a token in the accounts panel (Service accounts, needs auth:admin) or through the admin API (SERVICE-TOKENS). Give its role only what the job needs:

  • editor-ui:read alone makes it read-only.
  • Writing needs editor-ui:publish, which is sensitive: the token carries it only when an owner ticked allowSensitive when creating it. Add editor-ui:media for images and editor-ui:delete for deletions.

The service token is exchanged for an access token valid for 10 minutes, sent as Authorization: Bearer. Exchange again when it expires:

1ACCESS=$(curl -sf -X POST -H "authorization: Bearer $SSG_SERVICE_TOKEN" \
2  https://example.com/api/auth/token | jq -r .accessToken)

A request with a Bearer token needs no CSRF evidence. A request made with a person's session cookie must come from the site's own pages.

REST in four calls

 1H="authorization: Bearer $ACCESS"
 2# 1. the articles (50 a page by default, limit up to 100; nextCursor for the next page)
 3curl -s -H "$H" 'https://example.com/editor/api/content?q=bread'
 4# 2. one article, with its version; the path is URL-encoded as one segment
 5curl -s -H "$H" https://example.com/editor/api/content/content%2Fblog%2Fposts%2Fbread-notes.md
 6# 3. publish: one commit with every file in "changes"
 7curl -s -H "$H" -H 'content-type: application/json' \
 8  https://example.com/editor/api/changes -d '{
 9  "message": "Bread notes: add the starter",
10  "changes": [
11    {"op": "put", "path": "content/blog/posts/bread-notes.md",
12     "version": "<version from step 2>", "fields": {"title": "Notes on bread and time"}}
13  ]}'
14# 4. the article's history
15curl -s -H "$H" https://example.com/editor/api/revisions/content%2Fblog%2Fposts%2Fbread-notes.md

A change is put (whole text, or a form edit with fields, frontmatterRaw and body), move (from, to) or delete. version is the version you read; null means "this file must not exist yet". An image is {"op": "put", "path": …, "version": null, "base64": …} in the same changes; GET api/media/new-path?name=&type=&hash= gives the canonical path it must have.

Success is 201 {commitId, url, branch, files}. If the article changed since you read it, nothing is written and the answer carries both texts:

1{"error": "conflict", "detail": "…",
2 "files": [{"path": "content/blog/posts/bread-notes.md",
3            "yours": "…", "theirs": "…", "theirVersion": "…"}]}

Publish again over theirVersion once you have combined them. Every error is {"error": "<snake_case>", "detail"?}; the codes are in EDITOR-OPERATIONS.

MCP

POST https://example.com/editor/mcp speaks MCP over HTTP: the current revision 2026-07-28 and the initialize-based 2025-11-25, 2025-06-18 and 2025-03-26. It is stateless: one JSON-RPC message per POST, one JSON answer, no session. tools/list shows only the tools the token's permissions allow.

Tool What it does Needs
content_list, content_read list and read articles read
content_create, content_update new article; edit or rename (to) publish
content_delete delete an article publish + delete
media_list the media library read
media_upload add an image from content_base64 publish + media
media_delete delete an image publish + delete
revisions_list, revision_read an article's history, an old version read
widgets_list components, shortcodes and blocks an article can hold read
help instructions and the caller's tools read

Every write takes a message and is one commit; several files go in one call as changes[], not one call per file. An update or delete needs the version from content_read, and a conflict is the same 409 as on REST, returned as a tool result with isError: true.

1curl -s https://example.com/editor/mcp \
2  -H "authorization: Bearer $ACCESS" -H 'content-type: application/json' \
3  -H 'accept: application/json, text/event-stream' \
4  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"content_list","arguments":{"q":"bread"}}}'

A client configuration in the common mcpServers shape:

1{
2  "mcpServers": {
3    "site-editor": {
4      "type": "http",
5      "url": "https://example.com/editor/mcp",
6      "headers": { "Authorization": "Bearer <access token from POST /api/auth/token>" }
7    }
8  }
9}

The access token in such a file stops working after 10 minutes. A client that can run a command to build its headers should run the exchange above each time; otherwise paste a fresh token when the server starts refusing. OAuth sign-in for MCP clients is not built in this version.

Next to ssg mcp

ssg mcp (MCP) is the local development server: it works on your checkout, writes files and leaves the commit to you. The editor's endpoint works on the repository through GitHub and makes one commit per call. The tool names and arguments are the same where the operation is the same, so one prompt works in both places; the differences (versions, changes[], no content_edit, no download by URL in media_upload) are in one table in the README.

Content is data, not instructions. The tool descriptions tell the assistant so, but a model can still be talked into acting on text it reads in an article. Give an assistant's token only the permissions you would give a person who might be fooled, and prefer editor-ui:read until you need more.