The TofuBofu API

Check a key works

Confirms the key is live and tells you which workspace it belongs to. The first call to make when something is not working.

Request

curl -s https://tofubofu.com/api/v1/ping \
  -H "Authorization: Bearer $TOFUBOFU_KEY"

Response

{
  "ok": true,
  "workspace_id": "1e1cd597c306"
}

Report AI crawler visits from your own logs

The half of AI attribution no analytics tool can reach. GPTBot, ClaudeBot and PerplexityBot do not run JavaScript, so GA4 never sees them and neither does our tag. Post aggregated counts from your server logs. Group by bot, path and day; do not send one call per request. Unrecognised user agents are dropped rather than stored. A crawl means the engine read the page, not that it cited you.

Request

curl -s -X POST https://tofubofu.com/api/v1/crawler-hits \
  -H "Authorization: Bearer $TOFUBOFU_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hits":[{"bot":"PerplexityBot","path":"/pricing","day":"2026-08-14","hits":12}]}'

Response

{
  "ok": true,
  "accepted": 1,
  "dropped": 0
}

What the AI crawlers have read

Totals by bot and by engine, the pages read most, and how many hits came from the crawlers that fetch a page to answer a live question rather than to train. User agents are self-declared and not verified by reverse DNS, and the response says so.

Field	In	What it does
days	query	How far back, 1 to 365. Defaults to 30.

Request

curl -s "https://tofubofu.com/api/v1/crawler-hits?days=30" \
  -H "Authorization: Bearer $TOFUBOFU_KEY"

Response

{
  "days": 30,
  "total_hits": 412,
  "live_fetches": 37,
  "by_bot": [
    {"bot": "PerplexityBot", "hits": 210, "engine": "perplexity",
     "what": "Perplexity, builds its own index"}
  ],
  "by_engine": {"perplexity": 210, "chatgpt": 158},
  "top_pages": [{"path": "/services", "hits": 96}],
  "caveat": "User agents are self-declared and are not verified by reverse DNS..."
}

List your scans

Every scan in the workspace, newest first, across all your brands. Use the report_id from here with the next endpoint.

Request

curl -s https://tofubofu.com/api/v1/reports \
  -H "Authorization: Bearer $TOFUBOFU_KEY"

Response

{
  "reports": [
    {
      "report_id": "3ee94d63",
      "brand_name": "Acme MSP",
      "domain": "acmemsp.com",
      "status": "completed",
      "created_at": "2026-08-11 09:14:02"
    }
  ]
}

Read one scan in full

The complete stored report: every question asked, every engine's answer, the competitors each engine named, the site audit and the recommended fixes. This is the whole object the app renders from, so it is large.

Field	In	What it does
report_id	path	The id from GET /api/v1/reports. Must belong to your workspace.

Request

curl -s https://tofubofu.com/api/v1/reports/3ee94d63 \
  -H "Authorization: Bearer $TOFUBOFU_KEY"

Response

{
  "brand": {"name": "Acme MSP", "domain": "acmemsp.com"},
  "mention_rate": 12.5,
  "share_of_voice": 4.1,
  "query_results": [
    {
      "query": "best managed IT services in Vancouver",
      "intent": "category_bofu",
      "results": {"chatgpt": "absent", "claude": "absent", "perplexity": "brief"}
    }
  ],
  "competitor_threats": [{"name": "Compunet", "mention_count": 9}],
  "action_items": [{"title": "Publish a comparison page against Compunet"}]
}

Truncated. The real response carries the full answer text per engine and every scored question.

The latest scan, compact

A small, stable snapshot of the most recent completed scan for your active brand. Built for dashboards and widgets, so it will not make you parse the full report. The WordPress plugin and the Chrome extension both read this one.

Request

curl -s https://tofubofu.com/api/v1/summary \
  -H "Authorization: Bearer $TOFUBOFU_KEY"

Response

{
  "status": "completed",
  "report_id": "3ee94d63",
  "brand": "Acme MSP",
  "domain": "acmemsp.com",
  "visibility_index": 12.5,
  "mention_rate_pct": 12.5,
  "share_of_voice_pct": 4.1,
  "sentiment_score": 78,
  "top_competitors": [{"name": "Compunet", "mentions": 9}],
  "top_fixes": ["Publish a comparison page against Compunet"],
  "report_url": "https://tofubofu.com/report/3ee94d63"
}

Before your first completed scan this returns {"status": "none"} with HTTP 200, not an error.

Your generated llms.txt

The llms.txt file we build for your site from the crawl in your latest scan, in llmstxt.org format, as text/plain. Serve it at your own web root. This is the one thing the WordPress publisher cannot do for you, which is why the plugin fetches it here.

Request

curl -s https://tofubofu.com/api/v1/llms-txt \
  -H "Authorization: Bearer $TOFUBOFU_KEY"

Response (text/plain)

# Acme MSP

> Managed IT services for clinics and law firms across British Columbia.

## Services
- [Managed IT](https://acmemsp.com/managed-it): 24/7 monitoring and helpdesk
- [Cybersecurity](https://acmemsp.com/security): SOC 2 readiness and EDR

Start a scan

Runs a scan on your own plan, against a brand that already exists in your workspace. With an empty body it re-scans your active brand, which is what an automation usually wants. It returns immediately with a report_id; the scan itself takes a few minutes.

Field	In	What it does
domain	body	Target an existing brand by domain. Optional.
brand_id	body	Target an existing brand by id. Optional.
brand_name	body	Override the brand name on the scan. Optional.
industry	body	Update the brand's industry before scanning. Optional.
description	body	Update the brand's description. Optional.
geo_scope	body	Where do you sell? Getting this wrong skews the whole report: a national firm scored on one city's questions looks invisible, and a local one scored nationally looks unwinnable. One of: global (Anywhere); national (Across one country); national_local (National, with a local angle); local (My own city or region). Shapes every buying question. This is the single highest-leverage answer here. Omit it rather than guessing: an omitted answer is recorded as unknown, a guessed one is indistinguishable from a real answer.
locations	body	Which places? The country you sell across, or the cities you are bound to. Shapes which geography goes into a localized buying question. Omit it rather than guessing: an omitted answer is recorded as unknown, a guessed one is indistinguishable from a real answer.
competitors	body	Who would a buyer otherwise pick? Companies the user says a buyer would pick instead of them. We track whoever the engines name either way, so this is the user's own view rather than the whole comparison set. Shapes the comparison set, the mismatch between who you name and who the engines do, and which of those two a given finding is about. Omit it rather than guessing: an omitted answer is recorded as unknown, a guessed one is indistinguishable from a real answer.
buyer_questions	body	Questions your buyers ask. Questions this company's buyers actually ask. They are put to the engines verbatim and tracked scan over scan, which is what makes a trend line mean anything. Shapes the questions themselves, pinned ahead of the generated ones. Omit it rather than guessing: an omitted answer is recorded as unknown, a guessed one is indistinguishable from a real answer.
capacity	body	Who will do the fixes? We size and sequence the plan to match. A solo founder does not get a list built for a five-person team. One of: solo (Just me); one_marketer (One marketer); small_team (A small team, 2 to 4); full_team (A full team, 5 or more). Shapes the fix plan, which is generated in the tail after the engines answer. Omit it rather than guessing: an omitted answer is recorded as unknown, a guessed one is indistinguishable from a real answer.

Request

curl -s -X POST https://tofubofu.com/api/v1/scans \
  -H "Authorization: Bearer $TOFUBOFU_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acmemsp.com"}'

Response

{
  "report_id": "9f2c81ab",
  "brand_id": "b41d0c",
  "status": "running",
  "report_url": "https://tofubofu.com/report/9f2c81ab",
  "scans_remaining": 3
}

The API never creates a brand. Add a brand in the app first, then automate its re-scans from here. This is deliberate: creating one per domain would hand a caller a fresh scan quota on every loop.