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.

Start at /api/v1/help