Reference

Two Fires Engine API

Bearer auth with your API key. Every POST returns 202 with a run_id; poll GET /v1/runs/{id} or pass a callback_url. Every response carries X-TwoFires-Credits-Remaining.

Machine-readable: OpenAPI 3.1 · MCP manifest

Errors

Always the same shape. Never a stack trace.

{ "error": { "code": "insufficient_credits", "message": "An audit run costs AUD 29.", "topup_url": "https://engine.two-fires.com/pricing" } }

Status	Code	Meaning
400	`invalid_request`	A required field is missing or malformed.
401	`missing_api_key` / `invalid_api_key`	No key, or not a live one.
402	`insufficient_credits`	Carries `topup_url`.
404	`not_found`	No such run on this account.
429	`rate_limited`	10 POSTs per minute per key. `Retry-After` is set.

MCP

Streamable HTTP at https://engine.two-fires.com/mcp. Tools: customer_insight, messaging_audit, competitor_category, ai_visibility_check, get_run, list_runs, account_status. Each returns structured content and a markdown summary, so schema-aware and plain-text agents both get value.

"two-fires": {
  "url": "https://engine.two-fires.com/mcp",
  "headers": { "Authorization": "Bearer tfe_live_..." }
}

Endpoints

post/v1/insight

Researches what buyers in a market actually say: their pain points, the questions they ask before buying, and the words they use. Evidence-labelled and confidence-labelled.

Costs AUD 49 in credits.

Field	Type	What it is
`product` required	string	What you sell.
`market` required	string	The market or category you sell into.
`region` required	string	Where your customers are.
`customer` required	string	Who the customer is, in a sentence or two.
`website`	string	Your website, if you have one.
`competitors`	string
`testimonials`	string
`offer`	string
`callback_url`	string	POSTed when the run finishes.

curl -X POST https://engine.two-fires.com/v1/insight \
  -H "Authorization: Bearer tfe_live_..." \
  -H "Content-Type: application/json" \
  -d '{"product":"Physiotherapy and clinical exercise for post-surgical recovery","market":"Allied health, private physiotherapy clinics","region":"Dee Why, Northern Beaches, Sydney","customer":"Adults 40 to 70 recovering from knee or shoulder surgery, referred by a surgeon or GP","website":"https://www.two-fires.com/samples/demo/"}'

post/v1/audit

Audits a homepage against what customers actually care about: value proposition clarity, whether it speaks the customer's language, proof, differentiation, and the next step it offers.

Costs AUD 29 in credits.

Field	Type	What it is
`site_url` required	string	The page to audit.
`extra_assets`	string	Any other copy to consider: ads, a deck, an email.
`insight_run_id`	string	A finished /v1/insight run to audit against. Without one, a Customer Insight is run first and both are charged.
`callback_url`	string

curl -X POST https://engine.two-fires.com/v1/audit \
  -H "Authorization: Bearer tfe_live_..." \
  -H "Content-Type: application/json" \
  -d '{"site_url":"https://www.two-fires.com/samples/demo/"}'

post/v1/category

Maps what everyone in a category is claiming, where the claims collapse into sameness, and which position is actually open.

Costs AUD 79 in credits.

Field	Type	What it is
`product` required	string
`market` required	string
`region` required	string
`website` required	string
`competitors`	string
`substitutes`	string
`callback_url`	string

curl -X POST https://engine.two-fires.com/v1/category \
  -H "Authorization: Bearer tfe_live_..." \
  -H "Content-Type: application/json" \
  -d '{"product":"Physiotherapy and clinical exercise for post-surgical recovery","market":"Private physiotherapy clinics","region":"Northern Beaches, Sydney","website":"https://www.two-fires.com/samples/demo/"}'

post/v1/visibility

Asks AI assistants the questions a customer would ask when looking for a provider in a category and region, then reports who gets named, how often no one is named at all, and how concentrated the naming is. 92 questions by default.

Costs AUD 39 in credits.

Field	Type	What it is
`category` required	string	The category a customer would search in.
`region` required	string
`brand`	string	A business name to count mentions of.
`questions`	array	Ask these verbatim instead of the default set.
`callback_url`	string

curl -X POST https://engine.two-fires.com/v1/visibility \
  -H "Authorization: Bearer tfe_live_..." \
  -H "Content-Type: application/json" \
  -d '{"category":"physiotherapy","region":"Northern Beaches, Sydney","brand":"Northline Physio"}'

get/v1/runs/{id}

Status, and when the run is done the structured result and a pdf_url.

curl https://engine.two-fires.com/v1/runs/<run_id> \
  -H "Authorization: Bearer tfe_live_..."

get/v1/runs

This account's runs, newest first.

curl https://engine.two-fires.com/v1/runs \
  -H "Authorization: Bearer tfe_live_..."

get/v1/account

Plan, credits remaining, and usage to date.

curl https://engine.two-fires.com/v1/account \
  -H "Authorization: Bearer tfe_live_..."

post/v1/checkout

Creates a Stripe Checkout session for a credit pack, a plan, or the Marketing Diagnosis.

Field	Type	What it is
`pack`	number	One of 100, 250, 500.
`plan`	string	One of builder, studio.
`product`	string	Set to "diagnosis" to buy the full Marketing Diagnosis.
`email`	string
`website`	string

curl -X POST https://engine.two-fires.com/v1/checkout \
  -H "Authorization: Bearer tfe_live_..." \
  -H "Content-Type: application/json" \
  -d '{"pack":100}'

post/v1/signup

Emails a magic link. Clicking it creates a keyless, zero-credit account and sends you to pricing. A key is minted only after a payment.

Field	Type	What it is
`email` required	string

curl -X POST https://engine.two-fires.com/v1/signup \
  -H "Authorization: Bearer tfe_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'