API

Three on-ramps. One scored report.

Ounie accounts hit the REST endpoint with a bearer token. AI assistants connect over a native MCP server and get a tool surface. One-off scripts skip the account and pay per probe via x402 in USDC. All three run the same audit and return the same shape: a 0–100 visibility score, the probe × model matrix, share of voice, the technical GEO checklist, and prioritized recommendations.

POST/api/audit

auth: Bearer or cookie

Run a GEO audit

Synchronous (~30–60s). Crawls the page, probes the AI model panel with buyer-intent prompts, scores everything, and returns the full report. Reserves credits up front and settles on completed probes.

Request

{
  "url": "https://acme.com",
  "brand": "Acme",                    // the name to detect in AI answers
  "topic": "project management software",
  "probe_count": 6,                   // 3–20, default 6
  "prompts": [ ... ],                 // optional custom buyer prompts (one probe each)
  "competitors": ["Asana", "Linear"]  // optional, tracked for share of voice
}

Response

{
  "ok": true,
  "audit_id": "a1b2c3d4-...",
  "credits_reserved": 24,
  "credits_spent": 24,
  "score": 72,
  "report": { /* full report — see the schema panel */ }
}

GET/api/jobs/{id}

auth: Bearer or cookie

Fetch an audit

Returns a stored audit row and its full report by id, including the probe × model matrix, share of voice, technical checks, and recommendations.

Response

{
  "audit": {
    "id": "a1b2c3d4-...", "url": "https://acme.com", "brand": "Acme",
    "status": "succeeded", "score": 72,
    "report": { ... }, "credits_spent": 24, ...
  }
}

GET/api/jobs/{id}/export?format=csv|json

auth: Bearer or cookie

Export the matrix

Streams the probe × model matrix. CSV is spreadsheet-ready; JSON returns the full normalized report.

POST/api/x402/audit

auth: none · x402

Pay-per-call (agents)

No account, no API key. Returns 402 with payment terms; sign and retry with the X-Payment header ($0.048 per probe, USDC on Base). Synchronous — returns the full report.

Request

{
  "url": "https://acme.com",
  "brand": "Acme",
  "topic": "project management software",
  "probe_count": 6
}

Response

// 402 Payment Required (initial)
{ "x402Version": 1, "accepts": [{ "scheme":"exact", "network":"eip155:8453", "maxAmountRequired": "288000", ... }] }

// 200 OK (after a settled X-Payment header)
{ "ok": true, "score": 72, "report": { ... }, "payment": { "tx_hash": "0x..." } }

HTTP/api/mcp

MCP · Streamable HTTP + SSE

Model Context Protocol server

Drop the GEO Radar tool surface into any MCP host — Cursor, Claude desktop, ChatGPT custom GPTs, the Ounie AI Team, or the AI SDK. Seven tools: run_geo_audit, get_audit, export_audit, list_audits, get_credit_balance, get_pricing, whoami. Auth: a Bearer API key minted at /dashboard/api-keys, your ounie.com master key (ounie_live_…), or the key on ?api_key= for hosts that can't set headers. Calls draw your Ounie credits; reserve-before-run refuses with a 402 and a top-up link when the balance is short, so an agent can never overdraw.

Request

// .cursor/mcp.json (Cursor / any Streamable HTTP host)
{
  "mcpServers": {
    "geo-radar": {
      "url": "https://geo.ounie.com/api/mcp",
      "headers": { "Authorization": "Bearer geo_live_..." }
    }
  }
}

// Or the header-less connect string:
//   https://geo.ounie.com/api/mcp?api_key=geo_live_...

Response

// Tool call: run_geo_audit
{
  "url": "https://acme.com",
  "brand": "Acme",
  "topic": "project management software",
  "probe_count": 6
}
→ { "ok": true, "audit_id": "...", "credits_spent": 24, "score": 72,
    "share_of_voice": [...], "failing_checks": [...], "recommendations": [...] }

MCP tools

Everything an agent needs to audit and report.

run_geo_auditRun an audit (url, brand, topic, probe_count, prompts, competitors). Charged per completed probe.

get_auditFetch a stored audit's full report by id.

export_auditExport the probe × model matrix as summary, csv, or json.

list_auditsList recent audits on the account.

get_credit_balanceSpendable Ounie credits + approximate probes remaining.

get_pricingCredit and x402 pricing. No auth required.

whoamiThe authenticated key's owner metadata.

// One request. Synchronous — the full report comes back.
const res = await fetch("https://geo.ounie.com/api/audit", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ${GEO_API_KEY}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://acme.com",
    brand: "Acme",
    topic: "project management software",
    probe_count: 6,
    competitors: ["Asana", "Linear"],
  }),
});

const { score, credits_spent, report } = await res.json();
// → score: 0–100, report.probes[] = the probe × model matrix

Report schema

What every audit returns.

{
  "url": "https://acme.com",
  "brand": "Acme",
  "topic": "project management software",
  "panel": ["GPT-4o mini", "Gemini", "Claude"],
  "score": 72,               // 0–100 blended visibility
  "awarenessScore": 0.83,    // do models name you (0–1)
  "probes": [{
    "prompt": "best pm tool for agencies?",
    "mentionRate": 0.67,
    "bestRank": 2,
    "results": [
      { "model": "GPT-4o mini", "mentioned": true,
        "rank": 2, "competitors": ["Asana"] }
    ]
  }],
  "shareOfVoice": [
    { "name": "Acme", "mentions": 4, "isYou": true }
  ],
  "technical": {
    "score": 0.6,
    "checks": [{ "id": "schema", "label": "schema.org",
                 "pass": false, "detail": "..." }]
  },
  "recommendations": ["Add an FAQPage block ...", "..."],
  "generatedAt": "2026-07-13T..."
}

Notes

· Pricing: 4 credits per probe (default 6 = 24 cr ≈ $0.24)
· Probes per audit: 3–20
· x402: $0.048 per probe, USDC on Base (eip155:8453)
· Concurrency: up to 5 running audits per account