Use the REST API

Everything an AI agent can do through the MCP server, a script can do through the REST API: every MCP tool calls the REST API underneath. The REST API reference lists each call next to the MCP tool that uses it. It is generated from the tools, so the two always match.

The base address is https://app.typeroll.com on Typeroll Cloud. A self-hosted portal uses its own host. Send the credential as a bearer token and JSON bodies with Content-Type: application/json.

Choose a credential

Credential	Where to create it	Reaches
Personal API token	Account → AI connections → Personal API token	Every organization and site you can reach, with your role
Organization API key	Organization settings → API keys	One organization, as an administrator
Site API key	Site settings → API keys	One site, with the permission chosen for the key

A personal API token follows your access: if you lose access to an organization, the token loses it too. When you create one, you can limit it to some of your organizations, make it read only, or let it expire after 30, 90 or 365 days. Without an expiry it lasts until you revoke it in Account → AI connections, which also shows when each token was last used. Typeroll shows a token only once, so store it in a password manager or secret store. Writes made with a personal token are recorded with your user id.

For unattended automation in one organization, prefer an organization API key: it is tied to that organization by the key itself, needs no extra header and outlives staff changes.

Availability: personal API tokens and the generated reference come with Core 0.2.151.

Work with several organizations

You have two options:

• One organization API key per organization. Each key reaches only its organization, so no header is needed. Store one key per organization and pick the key that matches the organization you call.
• One personal API token for all of them. Name the organization in every request with the Typeroll-Organization header, as below.

With a personal API token:

1. List your organizations and your role in each:

   curl -H "Authorization: Bearer $TYPEROLL_TOKEN" \
     https://app.typeroll.com/api/v1/organizations

2. List the sites you can reach. Each site includes its organization_id:

   curl -H "Authorization: Bearer $TYPEROLL_TOKEN" \
     https://app.typeroll.com/api/v1/sites

3. Name the organization in every other request with the Typeroll-Organization header:

   curl -H "Authorization: Bearer $TYPEROLL_TOKEN" \
     -H "Typeroll-Organization: example-org" \
     https://app.typeroll.com/api/v1/sites/example-site/pages

A site id is unique within an organization, not across organizations, so the header decides which site you reach. Organization routes, such as /api/v1/publishing/builds, need the owner or administrator role in the organization you name.

An organization or site API key belongs to one organization. You can send the same header with it as a safety check: if the key belongs to another organization, the request is refused with 409 and changes nothing.

Permissions

Each call in the reference states the least permission it needs: read, write or admin. A personal token uses your role in the organization, or the permission a site was shared with you. A site API key uses the permission chosen when it was created.

Errors

Errors return a JSON body with error and, where useful, code. Common answers:

• 401: the credential is missing, invalid or revoked.
• 403: the credential cannot do this, for example a read key that writes.
• 404: the site or object is not available to this credential.
• 409: the request conflicts with the current state, for example a changed revision or a Typeroll-Organization mismatch. Read again and retry.
• 429: too many requests. Wait and retry.

Versions

Site calls act on the live version main unless you add ?version=<branch-id>. An unknown version is refused with 404; it is never answered about main.