The Agent API surface, mapped

Start at /api/v1/help

Every serious agent integration should begin the same way: ask the product how it works.

curl -H "Authorization: Bearer fx_…" \
https://your-site.com/api/v1/help

That response is the map — scopes, endpoints, SEO field names, and the mental model. If your agent scrapes /admin HTML instead, you’re fighting the product.

The surface (intentionally boring)

Area | Endpoints | Scope
Orient | GET /help, GET /site | content:read
Pages | list / get / put / delete | content:read / write
Posts | Markdown CRUD + seo{} | content:read / write
Snippets | [[shortcode]] fragments | content:read / write
Media | list / upload / delete | media:write for mutations
Settings | section get / merge-update | settings:write
SEO | sitewide robots, sitemap, schema | settings:write
Cache | POST /cache/flush | settings:write
Packages | GET /export/site, POST /import/site | backup:read / settings:write
Podcast | episodes CRUD | podcast:write

DreamHost-friendly alt headers exist (X-Forma-Token) because real hosting is messy. Auth is Bearer-first; tokens are stored hashed.

Content rules agents must respect

Pages can be HTML/Twig or Markdown. Optional carries slug + SEO; you can also pass seo:{} on PUT.

Posts are Markdown. Public only when published_at <= now. Draft = omit date or clear it.

Snippets are the nav/footer/chrome layer — edit once, reuse everywhere with [[shortcode]].

Don’t delete system pages: home, _404, _403, _500.

SEO is first-class, not a plugin afterthought

Per document and sitewide, the same field vocabulary:

seo_title, seo_description, og_title, og_description, og_image / featured_image, canonical, robots, twitter_card, schema_type

Agents can rewrite a homepage hero and the Open Graph card in one request. That’s the point.

MCP is just a polite wrapper

Cursor MCP tools (formax_help, formax_update_page, formax_update_seo, …) call this same API. Prefer MCP when it’s connected; fall back to curl when it isn’t. Same scopes. Same audit trail.

What the leash keeps out

A content token is not SSH.

No editing PHP / admin / lib on the server

No shell

No “god mode” beyond the scopes you minted

HTTPS required for non-local when security.agent_https_only is on

Give agents the keys to the site, not the machine. Rotate when a token lands in a chat log. Keep a site package handy — agents move fast; so do mistakes.

A good first session

GET /help and GET /site

List pages + posts

Fix one SEO description

Publish one Markdown post with featured_image

GET /export/site before any big rewrite

If your agent can do those five things cleanly, you have a real CMS integration — not a demo.