Developer guides

API and MCP

Connect an AI assistant or your own code to your Torchrunner workspace, take leads from your website, and send Playbook data to any address.

What it is for

Torchrunner has three ways in and out for code:

  • The MCP server, for AI assistants and agents: read and work your workspace under your own seat's rights.
  • Public endpoints, for your website: send leads and form answers in, read your published content and changelog out.
  • Webhooks from Playbooks, out: a Playbook step sends a record or a body you write to an address you give it.

The MCP server

The address is https://app.torchrunner.ai/api/mcp. It speaks the Model Context Protocol over HTTP, with a bearer token in the Authorization header.

Connect an assistant that supports MCP sign-in

Add the address in your assistant's connector settings. A request with no token gets 401, and its WWW-Authenticate header points to the sign-in details, so an assistant that supports MCP sign-in finds them on its own. You sign in to Torchrunner in the browser, approve the connection, and the assistant gets its own token.

Make a token by hand

For an agent or a script that cannot sign in on its own:

  1. Open Settings > Integrations, then Connect, and find MCP tokens under Advanced.
  2. Name the token. Set an expiry if you want one, and pick an agent if it should read only that agent's part of your brain.
  3. Copy it. It starts with tr_pat_ and is shown once; Torchrunner keeps only a fingerprint of it.
  4. Send it as Authorization: Bearer tr_pat_....

Revoke a token on the same screen. It stops working on its next request.

Settings > API keys is a different thing: that is where you paste your own AI provider's key for Archie, not a key for this API.

What a token can do

A token gets the customer tool set, limited again by your seat: it sees what you can see and does what you can do. The tools cover:

  • Your brain: read, search and write memories, and see what links to what.
  • CRM and records: search and read leads, contacts, companies and your own record types; create and update them, move a lead's stage, log activity, link records.
  • Tasks, notes and Areas: read and write tasks, capture and update notes, file work into Areas, read dashboards.
  • Sequences: list, enroll, pause, resume and stop.
  • Prospects: search and save prospects, enrich a contact.
  • Client books: read your clients' connected books.
  • Ask Archie: hand Archie a question to work on.

A viewer's token can read but not write.

What waits for a person

Some tools make a proposal instead of acting:

  • Writes to a client's books are proposed, and an owner or admin approves them in Torchrunner.
  • Filing work into an Area and Area review actions are proposed, and a person approves them.

Limits and errors

  • 60 requests a minute from one address. Past that the server answers 429 with a Retry-After header.
  • A missing, expired or revoked token gets 401.
  • Tool answers follow JSON-RPC 2.0: a success has result, a failure has error with a code and a message.

Public endpoints for your website

These need no token. Call them from your own site.

Your form's id

Make or open a form in Marketing > Capture forms. Its id is the last part of its hosted address, https://app.torchrunner.ai/form/<id>.

Send a lead

POST https://app.torchrunner.ai/api/public/leads with JSON:

  • form_id: your form's id.
  • fields: the answers, keyed by field id or label.
  • utm: optional, your campaign tags.

It answers { "ok": true, "message": "...", "redirect_url": "..." }.

Draw and submit a form

  • GET https://app.torchrunner.ai/api/public/forms/<id> returns { "ok": true, "form": { "id", "name", "fields", "settings" } } for an active form, so your site can draw it.
  • POST to the same address with the answers as plain JSON fields, keyed by field id or label (no wrapper). It answers ok, message, redirect_url, and lead_id when a lead was made.

Lead and form submissions allow 5 from one address in any 5 minutes. Keep the hidden website_url field empty: it is the trap for bots. A filled one gets the normal thank-you answer and is not stored.

Read your published content and changelog

  • GET https://app.torchrunner.ai/api/public/content?org=<your workspace handle> returns { "ok": true, "items", "total" }: your published pieces. Add collection, type, limit (20 by default, 100 at most) and offset to page. Ask for status=scheduled to see what is coming.
  • GET https://app.torchrunner.ai/api/public/changelog?org=<your workspace handle> returns { "ok": true, "items" }: the published entries you marked public, newest first, 50 by default and 100 at most.

Both allow 60 requests a minute from one address, and their answers can be cached for 60 seconds.

Booking

To take bookings on your site, link to your booking page or embed it. Its own endpoints serve the page and are not documented here yet.

Webhooks from Playbooks

A Send webhook step in a Playbook calls an HTTPS address you give it. The address must be public, and redirects are not followed, so enter the final one.

  • Method: POST, PUT, PATCH, GET or DELETE. GET and DELETE send no body.
  • Body: the whole record that started the run, the fields you pick, or a body you write as JSON, form or text, with merge fields filled in when the step runs.
  • Headers: add your own, such as an Authorization header your receiver checks. Header values are kept encrypted and opened only to send.
  • Answer: reply with a 2xx within 10 seconds. A redirect or any other status fails the step, and the run's log shows it. A complete JSON answer under 64 KB is handed to the next steps.

A Playbook made at or after 05:00 UTC on November 4, 2026 needs an approval step right before each step that leaves Torchrunner (a webhook, an email, a text, a browser step, a connected CRM action), on every path into it. A person says yes to what will go out before it goes.

Good to know

  • The public endpoints do not share one error shape. Check the HTTP status, then the answer's error.
  • Torchrunner never trains AI models on what you send through any of these.