Developer surface
Programmatic access to Iterant through a public REST API and a hosted MCP server that share one tenancy model.
An itr_ API key minted in the dashboard authenticates the whole surface:
nine read endpoints, the agent task routes, and the MCP server. Interactive
MCP clients can sign in with OAuth instead of a key. Publishing is not
exposed anywhere. Names and payload shapes may still change.
Iterant's developer surface exposes the objects the dashboard works with (brands, pages, opportunities, page reports, AI visibility, internal linking) to code and to agents, and lets both put Terra to work. There are two front doors onto one contract.
REST or MCP
The REST API is for software you write. Scripts, CI jobs, an internal dashboard, a sync from your CRM. It speaks JSON over HTTPS and is versioned.
The MCP server is for agents. Connect it to Claude Code, Claude Desktop, Cursor, or VS Code and the agent gets a small set of typed tools: read the state of a brand, look at what a page is doing, read the opportunity queue, read AI visibility, and start an agent task.
Both surfaces run one contract, with the same scoping, the same errors, the same caps, and the same payloads. Nine tools map onto the nine read endpoints, and two more map onto the task routes.
| REST API | MCP server | |
|---|---|---|
| Consumer | Your code | An agent in your editor or chat client |
| Shape | Nine reads + three task routes | Eleven tools, one call per outcome |
| Auth | itr_ API key | OAuth 2.1 sign-in, or an itr_ API key |
| Wire casing | camelCase JSON | snake_case arguments, camelCase results |
| Identifiers | brandSlug, urlPath, an opportunity ref | brand_slug, url_path, an opportunity ref |
Casing differs between the two. A tool argument is snake_case, the convention MCP clients expect, while a tool result is the byte-identical REST payload, camelCase keys and all.
Enum values keep their shape on both surfaces. build_page, failed_generation, and google_ai_mode are the same strings everywhere, so a value you read out of one response is a value you can send back in the next request.
Tenancy: organization, then brand
Every call is scoped twice. Your credential belongs to an organization, and almost every object belongs to a brand inside that organization. Iterant re-resolves both on every request.
A brand that belongs to another organization and a brand that does not exist return the same 404, with the same message. Read a 404 as "not yours, or not there", then check the slug.
One key reaches the same brands over MCP as over REST. Revoke it and both stop working on the next request. See MCP server.
Authentication in one paragraph
You mint an API key in the dashboard at Settings → Developers. It looks like itr_… and it is shown once. You send it as Authorization: Bearer itr_…. A key is either pinned to a single brand or scoped to the whole organization. Every brand-scoped route names its brand in the URL path (/brands/{brandSlug}/…), so there is no header to pick a brand with; X-Brand-ID only ever restricts a brand-pinned key. The key authenticates the public API and the MCP server, and nothing else. It will not open a dashboard route.
MCP also accepts an OAuth 2.1 sign-in, so a person authenticates through their client rather than pasting a key; see MCP server for the flow. Keys remain the way in for REST and for headless MCP callers.
See API keys for the full picture.
Read the numbers honestly
Both surfaces carry two properties of the data that matter more than the transport does:
- Every metric block has a
state:ok,no_data,unconfigured, orerror. Metrics arenullwhenever the state is notok. Rendering anullmetric as zero is wrong. - Signals-derived figures are sampling-weighted estimates, flagged
estimated: true. Sessions, page anatomy, and conversions whereisExactis false are approximations.
Putting Terra to work
The one write on this surface is an agent task: a single autonomous Terra turn, asked for by a machine. It takes one of two commands, a free-form instruction or a build of one page opportunity, and gives you back one handle to poll.
A build is a real agent run against a real repository. Creation answers 202 with a handle instead of blocking, a task takes about five minutes and costs money, and one runs per brand at a time, because the agent holds an exclusive lease on the brand's workspace. That is also why there is no batch endpoint: N pages is N tasks in sequence.
Agent tasks. Both commands, the poll-then-submit pattern, callbacks, and the errors.
Not built
- Publishing. Putting a page on a live customer-facing domain is a step a person takes in the dashboard. No endpoint and no tool does it, and none is planned for this phase.
- Batch creation. One task per call, as above.
- Writing back to the queue. Dismissing, scheduling, or re-opening an opportunity.
- Idempotency keys and rate limiting. Both planned, neither built.
What is not exposed
- Raw lead data. Form submissions carry names, emails, and phone numbers. Signals come back as rollups and conversion aggregates only.
- Authoring internals. Terra's workspace tools for editing content, staging variants, saving, previewing, and provisioning repositories run inside a leased sandbox and have no meaning outside it.
- Configuration writes. Brand, domain, and proxy settings; visibility prompt management; anything touching billing.
- Destructive deletes. They do not exist here, and are not planned.
Next
API keys. Minting a key, brand-pinned versus org-scoped, and revocation.
REST API. Base URL, conventions, the error envelope, and the endpoint list.
Agent tasks. Starting a Terra turn from your own code, and polling it.
MCP server. The endpoint, transport, auth, and per-client install steps.
MCP tools. What each tool does, what it takes, and what it returns.
Last updated on