Operator API

The Operator API lets a script or an AI assistant work with your site: read its content, configuration and database structure, and propose changes for a person to approve. It arrived in 1.11.0, and it's off until you turn it on.

What it can and can't do #

• Read pages, blog posts, menus, media, templates, the site's status and its settings (never a secret), and the database tables tilspire's read policy allows — some of them only as a count.
• Create, update and delete: propose a new item, an edit or a deletion. A proposal is a draft: nothing reaches your site until a person approves it in the Review queue, and approving saves it through the same code the admin panel uses. A deletion keeps a revision and can be restored once.
• Since 1.15.0 it can propose pages, Blog posts, menus, redirects, images, settings, theme options and design, translations, forum moderation (hide, show, lock, pin or move) and ticket replies, each under its own gates and grants. Tickets have their own switch, and a ticket is read without the client's name, email or tracking ID.
• Since 1.16.0 it can also propose Layouts — a new one with its groups and fields, a change to one, or deleting one — and changes to an existing field. A page draft may name a Layout that is still waiting, so an agent can propose both in one sitting; the page can be approved once the Layout is. A field that already holds content can only become plain text, and a Layout or field still in use can’t be deleted this way.
• It can never issue credentials or grant itself anything, and it never publishes on its own unless a person turns on self-approval for that credential (below).

Turning it on #

1. As an administrator, open System ▸ Operator API and, under Gates, turn the API on and switch on what you want to offer: Create, Read, Update and Delete for each resource, side by side. While it's off, /api isn't claimed at all.
2. Turn on two-factor sign-in for your account if you haven't: issuing a credential requires it.
3. Under Credentials, issue one. Name it, choose when it expires — 90 days by default, a year at most — and, if you like, limit it to the addresses it may connect from. Copy it straight away: it's shown only once.
4. Choose what that credential may do. Since 1.16.0 each credential lists jobs — such as Write and edit pages, Shape Layouts and fields, Translate pages and menus or Read the site status — and one switch gives it everything that job needs. A job offers only what your own account may use, and modules can add jobs of their own. For a single grant, the Grants tab still shows the full Create, Read, Update and Delete table; users, roles and the activity log are only ever granted there.

Proving it's you #

Changes on this page ask for your password and a code from your authenticator app. Issuing, rolling or extending a credential asks every time. For everything else — grants, gates, names, addresses, revoking — one proof covers the next 15 minutes. The page shows until when, and End now closes the window early.

Looking after a credential #

• Extend adds 30, 90, 180 or 365 days to a live credential's expiry, never past a year from today. The page offers only the lengths that fit and shows the new date before you confirm.
• Roll replaces a credential with a new secret, keeping its name, its addresses and its grants. The old secret stops working at once, and any proposals it still has waiting are withdrawn — the page tells you how many first. Use it when a secret may have leaked. An expired credential can be rolled; a revoked one can't.
• A credential marked Account changed belongs to an account whose password or two-factor sign-in has changed since it was issued, so it no longer works. Roll it to carry on, or revoke it.

How a credential is limited #

• It acts as the account that issued it, and never does more than that account could. If the account is disabled, moved to another role, or turns two-factor sign-in off, the credential stops working.
• It expires, and it can be revoked at any time.
• Each credential has its own grants, and each resource has a switch for the whole site, so you can withdraw something from every credential at once.
• It may make 600 requests every 10 minutes.

Connecting #

Send the credential in the X-Api-Token header, never in a URL:

curl -H "X-Api-Token: $TSPO_TOKEN" https://example.com/api/v1/

That first request lists what the credential may use right now. The full contract is an OpenAPI document at /api/v1/openapi, and AI assistants that speak the Model Context Protocol connect to /api/v1/mcp. The Connect card on the Operator API page shows both addresses for your site, with a ready-made command for Claude Code.

Reviewing proposals #

Proposals wait in the Review queue. Anyone allowed to edit that content sees what would change, field by field, can preview a page, post or menu on the real site, and approves or rejects it, with a note if they like, or up to 50 at once. If the page changes after a proposal was written, the proposal can't be approved, so it never overwrites newer work. HTML in a proposal is always filtered, as it is for an editor without raw-HTML rights.

Self-approval #

Off by default. The account that owns a credential can let it publish its own new and edited pages, Blog posts and new images without the Review queue, for 1 hour, 8 hours, 24 hours or 7 days, never longer. It needs a tight list of addresses the credential connects from, and your password and code every time.

• Deletions, settings, menus, Layouts and fields, forum moderation and tickets always wait for a person.
• At most 60 items an hour are self-approved; beyond that they wait in the queue.
• Everything self-approved is listed in the Review queue's Self-approved view, where a person can undo it, and the activity log names the credential.
• It ends early when the owner turns it off, the credential is revoked, its addresses change or it is granted more, and when the owner's account is disabled or moved to another role.

Limits worth knowing #

• An image is proposed by file name, up to 8 MB per request.
• A page title holds up to 30 characters.
• A credential may have 50 proposals waiting at a time.