REST API overview

What this is

The Transformento REST API — the HTTP surface the MCP server is built on. It covers page management, publishing, live voice sessions, project configuration, authentication, and templates.

Base URL: https://api.transformento.com

The MCP server wraps these same operations. If you’re using Claude, Cursor, or another MCP client, you don’t need to call the REST API directly. Use it when integrating from a custom server, webhook, or CI pipeline.

How it works

Authentication

Two methods:

OAuth Bearer token — for user accounts. Obtained via the OAuth flow; send as Authorization: Bearer <token>. See Authentication reference.
Service API key — for headless callers. Set x-project-id and x-api-key headers. Generate keys in project settings.

Response format

Successful responses return JSON. Errors return { "error": "..." }:

Status	Meaning
`400`	Invalid request — missing or malformed arguments
`401`	Authentication required
`403`	Insufficient role, module disabled, or trial expired
`404`	Resource not found
`413`	Payload too large (1 MB general; 10 MB image upload)
`429`	Rate limit exceeded
`500`	Internal error

Rate limits

Per-IP, 60-second sliding window:

Endpoint	Limit
`POST /mcp`	60 requests/min
`/oauth/*`	30 requests/min
Auth failures (401 responses)	10/min before 429 kicks in

Endpoint groups

OAuth and authentication

/.well-known/oauth-authorization-server, /oauth/register, /oauth/authorize, /oauth/token

Projects

GET/POST /api/projects, GET/PATCH/DELETE /api/projects/:id, members, domains, modules, settings

Pages (knowledge)

Create, edit (/docs/edit/open, /edit/save, /edit/discard), list, publish flow, visibility

Custom pages

POST /api/projects/:id/docs/edit/upload-custom-page — for HTML/Astro custom page bodies

Publishing

POST /api/projects/:id/publish, POST .../publish/confirm, GET .../publish/history

Publishing is a two-step flow: dry-run builds a manifest + confirmation token; confirm promotes and deploys. See Publish reference.

Live voice

POST /api/live/session, /session/resume, /tools/execute, /twilio/voice

/api/projects/:id/sidebar-groups, /api/projects/:id/header-nav-items

Templates

/api/templates/doc, /api/templates/project, /api/projects/:id/templates

Ingestion (Chrome Extension)

/api/projects/:id/ingest/* — capture, extract, and save pages from the Chrome extension

API keys

/api/projects/:id/keys

Account

/api/accounts/me, /api/account/connectors/claude/*

When to use it

Use case	Recommended path
AI assistant managing content	MCP server — the tools abstract the API and handle auth
Server-side integration, CI/CD	REST API — more control, no MCP client dependency
Webhook receiver	REST API

Example

Fetch project details with a Bearer token:

curl https://api.transformento.com/api/projects/YOUR_PROJECT_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Call the MCP endpoint with a service key:

curl -X POST https://api.transformento.com/mcp \
  -H "Content-Type: application/json" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -H "x-api-key: YOUR_SERVICE_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get-project-state","arguments":{"project_id":"YOUR_PROJECT_ID"}}}'

Common errors

Error	Cause	Fix
`401 Unauthorized`	Missing or expired token	Re-authenticate or regenerate the API key
`403 Trial expired`	The project’s trial period ended	Upgrade the plan to restore access
`403 Insufficient permission`	Caller’s role is below the endpoint’s requirement	Check your role and ensure you’re calling with the right credentials
`413 Payload Too Large`	Request body exceeds the limit	Reduce payload size or use the chunked image upload endpoint
`429 Too Many Requests`	Rate limit hit	Back off and retry after the `Retry-After` header value

Authentication reference — tokens, API keys, role mapping
Publish reference — two-step draft-to-live flow
MCP server — the same operations via MCP tools