{"openapi":"3.1.0","info":{"title":"LLMentions API","description":"SEO + AEO data layer for agents. MCP endpoint: /mcp","license":{"name":"UNLICENSED","identifier":"UNLICENSED"},"version":"0.1.0"},"paths":{"/healthz":{"get":{"tags":[],"operationId":"healthz","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/v1/account":{"get":{"tags":[],"summary":"Who am I: org, key, mode (live/test), configured engines. The first call an agent should make.","operationId":"account","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/ai/answers":{"post":{"tags":[],"summary":"Ask answer engines now and get normalized answers back (synchronous, ≤ 50 checks).\nCharged per successful answer; `dry_run: true` returns the quote only.","operationId":"ai_answers","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiAnswersInput"}}},"required":true},"responses":{"200":{"description":"Envelope<AiAnswers>, or Envelope<Estimate> for a dry run"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bots/lookup":{"get":{"tags":[],"summary":"Identify which search/AI crawler a User-Agent belongs to (log analytics building block).","operationId":"user_agent_lookup","parameters":[{"name":"ua","in":"query","description":"Raw User-Agent header value.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Envelope<BotInfo | null>"}}}},"/v1/bots/report":{"post":{"tags":[],"summary":"Which search and AI bots visit a site, from its server logs: hits, status codes and top\npaths per bot, and live AI fetches (a user's question made an assistant read the page).\nBots are identified by user agent only. Free.","operationId":"bots_report","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BotsReportInput"}}},"required":true},"responses":{"200":{"description":"Envelope<BotsReport>"}}}},"/v1/engines":{"get":{"tags":[],"summary":"Answer engines and whether each is configured.","operationId":"engines","responses":{"200":{"description":"Envelope<[{engine, description, configured, requires}]>"}}}},"/v1/jobs/{id}":{"get":{"tags":[],"operationId":"get_job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/keys":{"get":{"tags":[],"operationId":"list_keys","responses":{"200":{"description":"Envelope<Vec<KeyInfo>>"}}},"post":{"tags":[],"summary":"Create an API key. The plaintext `key` is returned once — store it.","operationId":"create_key","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKey"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewKey"}}}}}}},"/v1/keys/{id}":{"delete":{"tags":[],"operationId":"revoke_key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/prices":{"get":{"tags":[],"summary":"Public price list (USD). Credits are dollars; reads of stored data are free.","operationId":"prices","responses":{"200":{"description":"Envelope<{currency, free_monthly_usd, items}>"}}}},"/v1/projects":{"get":{"tags":[],"operationId":"list_projects","responses":{"200":{"description":"Envelope<Vec<Project>>"}}},"post":{"tags":[],"operationId":"create_project","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProject"}}},"required":true},"responses":{"201":{"description":"Envelope<Project>"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{project}/analyze":{"post":{"tags":[],"summary":"Label a project's stored answers with the analysis squad (sentiment, framing, claims) and\nreturn perception rates per brand with 95% CIs. $0.002 per answer labelled.","operationId":"analyze_answers","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeBody"}}},"required":true},"responses":{"200":{"description":"Envelope<AnalysisSummary>, or {answers, price_usd} for a dry run"}}}},"/v1/projects/{project}/answers":{"get":{"tags":[],"summary":"Raw sampled answers (newest first) — the evidence behind every number.","operationId":"project_answers","parameters":[{"name":"engine","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"brand","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"missing_target","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":0}},{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Envelope<Vec<Observation>>"}}}},"/v1/projects/{project}/jobs":{"get":{"tags":[],"operationId":"project_jobs","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Envelope<Vec<Job>> newest first"}}}},"/v1/projects/{project}/prompts":{"post":{"tags":[],"summary":"Add or remove tracked prompts for a project (by id, name or domain).","operationId":"track_prompts","parameters":[{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackPrompts"}}},"required":true},"responses":{"200":{"description":"Envelope<Project>"}}}},"/v1/projects/{project}/visibility":{"get":{"tags":[],"summary":"Latest visibility report (with significance-tested change vs the previous run).","operationId":"project_visibility","parameters":[{"name":"all_runs","in":"query","description":"Pool every run instead of latest-vs-previous.","required":false,"schema":{"type":"boolean"}},{"name":"project","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Envelope<VisibilityReport>"}}}},"/v1/prompts/suggest":{"post":{"tags":[],"summary":"Research the questions buyers ask AI assistants in a category (researcher + critic\nsquad). $0.02 per call; `track: true` adds them to the project.","operationId":"suggest_prompts","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestions"}}}}}}},"/v1/signup":{"post":{"tags":[],"summary":"Instant, free signup: creates a workspace and a **test** key (mock engines, never charged).\nLive keys unlock with billing.","operationId":"signup","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signup"}}},"required":true},"responses":{"201":{"description":"Envelope<{org, keys: [NewKey]}>"}}}},"/v1/site/audit":{"post":{"tags":[],"summary":"Audit a site for AI-answer readiness: crawls up to `max_pages` pages as LLMentionsBot\n(polite, robots.txt honoured), checks robots.txt access per AI bot, fetches the homepage as\nAI bots to spot CDN/WAF blocks, and runs page rules (JavaScript-only content, noindex,\nerrors, missing titles, structured data…). $0.0002 per page crawled.","operationId":"site_audit","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteAuditInput"}}},"required":true},"responses":{"200":{"description":"Envelope<{report, price_usd, charged_usd}>"}}}},"/v1/site/audits/{audit}":{"get":{"tags":[],"summary":"A stored audit by id, or a site's latest audit by domain, with `changes` since the\nprevious audit of that site. Free.","operationId":"get_audit","parameters":[{"name":"audit","in":"path","description":"audit_id or domain","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Envelope<SiteAudit>"}}}},"/v1/visibility/runs":{"post":{"tags":[],"summary":"Start a visibility run (202 + job) or get a cost estimate (`dry_run: true`, 200).","operationId":"start_run","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityRunInput"}}},"required":true},"responses":{"200":{"description":"Envelope<Estimate> (dry run)"},"202":{"description":"Envelope<Job> — poll GET /v1/jobs/{id}"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Account":{"type":"object","required":["org","key","mode","projects","engines","balance_usd","webhook_secret","note"],"properties":{"balance_usd":{"type":"number","format":"double","description":"Balance in USD. Test keys never spend it."},"engines":{"type":"array","items":{"type":"string"}},"key":{"type":"string"},"mode":{"type":"string","description":"\"live\" or \"test\"."},"note":{"type":"string"},"org":{"type":"string"},"projects":{"type":"integer","minimum":0},"webhook_secret":{"type":"string","description":"Secret for verifying `LLMentions-Signature` on job webhooks (HMAC-SHA256)."}}},"AiAnswers":{"type":"object","required":["answers","errors","checks","price_usd","charged_usd"],"properties":{"answers":{"type":"array","items":{"type":"object"},"description":"Normalized answers: text, citations (classified), mentions, fan-out queries, source."},"charged_usd":{"type":"number","format":"double","description":"Charged in USD (successful answers only; 0 for test keys)."},"checks":{"type":"integer","format":"int64","minimum":0},"errors":{"type":"array","items":{"type":"string"},"description":"Skipped engines and failed calls (failed calls are never charged)."},"price_usd":{"type":"number","format":"double","description":"Quoted maximum in USD."},"report":{"type":["object","null"],"description":"Mention rates with 95% CIs, when `brand` or `competitors` were given."}}},"AiAnswersInput":{"type":"object","required":["prompts"],"properties":{"brand":{"type":["string","null"],"description":"Optional: your brand. Answers are scanned for it and a mention-rate report is added."},"brand_aliases":{"type":"array","items":{"type":"string"},"description":"Alternate spellings of `brand`."},"competitors":{"type":"array","items":{"type":"string"},"description":"Optional: competitor brand names to detect."},"domain":{"type":["string","null"],"description":"Optional: your bare domain (\"acme.com\"); citations to it are classed \"owned\"."},"dry_run":{"type":"boolean","description":"true = return the price quote only; nothing runs, nothing is charged."},"engines":{"type":"array","items":{"type":"string"},"description":"Engine keys, e.g. [\"chatgpt\",\"perplexity\"]. Omit for every configured engine."},"locale":{"type":["string","null"],"description":"BCP-47 locale, default \"en-US\"."},"prompts":{"type":"array","items":{"type":"string"},"description":"Prompts to ask (each asked fresh on every engine), e.g. [\"best crm for startups\"]."},"samples":{"type":["integer","null"],"format":"int32","description":"Samples per prompt × engine (1–10, default 1). Total checks are capped at 50.","minimum":0},"web_search":{"type":["boolean","null"],"description":"false = parametric probe (search disabled). Default true."}}},"AnalysisSummary":{"type":"object","required":["project","analyzed","labelled_total","brands","claims_about_you","quality","team","errors","price_usd","charged_usd"],"properties":{"analyzed":{"type":"integer","description":"Answers labelled by this call.","minimum":0},"brands":{"type":"array","items":{"$ref":"#/components/schemas/BrandPerception"}},"charged_usd":{"type":"number","format":"double"},"claims_about_you":{"type":"array","items":{"type":"string"},"description":"Distinct factual claims the engines make about your brand (check these for errors)."},"errors":{"type":"array","items":{"type":"string"}},"labelled_total":{"type":"integer","description":"Answers in scope that mention a tracked brand and have labels.","minimum":0},"price_usd":{"type":"number","format":"double"},"project":{"type":"string"},"quality":{"$ref":"#/components/schemas/Quality"},"team":{"type":"string"}}},"AnalyzeBody":{"type":"object","properties":{"all_runs":{"type":"boolean"},"dry_run":{"type":"boolean"},"force":{"type":"boolean"}}},"BotInfo":{"type":"object","required":["token","vendor","class","renders_js"],"properties":{"class":{"type":"string"},"renders_js":{"type":"boolean"},"token":{"type":"string"},"vendor":{"type":"string"}}},"BotsReportInput":{"type":"object","description":"`bots_report` input.","required":["log"],"properties":{"log":{"type":"string","description":"Raw server-log text: nginx/Apache combined lines, or JSON lines (Cloudflare Logpush,\nVercel) with a user-agent field. Up to 20 MB; sample larger logs."}}},"BrandPerception":{"type":"object","required":["brand","you","labelled","positive","negative","recommended","framing"],"properties":{"brand":{"type":"string"},"framing":{"type":"object","description":"Framing counts: recommended, listed, compared, cautioned, mentioned.","additionalProperties":{"type":"integer","format":"int64","minimum":0},"propertyNames":{"type":"string"}},"labelled":{"type":"integer","format":"int64","description":"Answers mentioning this brand that were labelled.","minimum":0},"negative":{"$ref":"#/components/schemas/Rate"},"positive":{"$ref":"#/components/schemas/Rate","description":"Share of those answers that portray the brand positively."},"recommended":{"$ref":"#/components/schemas/Rate","description":"Share where the brand is explicitly recommended (not merely listed)."},"you":{"type":"boolean"}}},"CreateKey":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"test":{"type":"boolean","description":"true = sk_test_ key (mock engines, free). Default false."}}},"CreateProject":{"type":"object","required":["name","domain"],"properties":{"brand_aliases":{"type":"array","items":{"type":"string"}},"competitors":{"type":"array","items":{"type":"string"},"description":"Competitor brand names to track share of voice against."},"domain":{"type":"string","description":"Primary domain without scheme, e.g. \"acme.com\"."},"name":{"type":"string","description":"Brand name as it appears in AI answers, e.g. \"Acme\"."},"prompts":{"type":"array","items":{"type":"string"},"description":"Prompts to track (questions your buyers ask AI assistants)."}}},"Error":{"type":"object","description":"`{ \"error\": { type, message, hint, retry_after } }`","required":["type","message"],"properties":{"hint":{"type":["string","null"],"description":"What the agent should do next."},"message":{"type":"string"},"retry_after":{"type":["integer","null"],"format":"int64","minimum":0},"type":{"$ref":"#/components/schemas/ErrorKind"}}},"ErrorKind":{"type":"string","enum":["invalid_request","auth","forbidden","not_found","budget_exceeded","rate_limited","upstream","internal"]},"Health":{"type":"object","required":["status","version","engines"],"properties":{"engines":{"type":"string","description":"\"live\" (real provider keys) or \"mock\" (LLMENTIONS_MOCK_ENGINES=1)."},"status":{"type":"string"},"version":{"type":"string"}}},"Intent":{"type":"string","enum":["discovery","comparison","alternatives","problem","evaluation"]},"Job":{"type":"object","required":["id","kind","project","status","done","total","price_usd","charged_usd","errors","report","created_at"],"properties":{"charged_usd":{"type":"number","format":"double","description":"Actually charged in USD (successful answers only; 0 for test keys). Final when the job ends."},"created_at":{"type":"string","format":"date-time"},"done":{"type":"integer","format":"int32","minimum":0},"errors":{"type":"array","items":{"type":"string"},"description":"Short per-call errors (first 10)."},"finished_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"string"},"kind":{"type":"string"},"price_usd":{"type":"number","format":"double","description":"Quoted (and held) price in USD — the most this job can charge."},"project":{"type":"string"},"report":{"type":"object"},"status":{"$ref":"#/components/schemas/JobStatus"},"total":{"type":"integer","format":"int32","minimum":0}}},"JobStatus":{"type":"string","enum":["queued","running","succeeded","failed"]},"KeyInfo":{"type":"object","required":["id","name","prefix","test","created_at","revoked"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string"},"last_used_at":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"prefix":{"type":"string","description":"Display prefix, e.g. \"sk_live_a1b2\"."},"revoked":{"type":"boolean"},"test":{"type":"boolean"}}},"Meta":{"type":"object","required":["charged_usd","cached","truncated"],"properties":{"balance_usd":{"type":["number","null"],"format":"double","description":"Workspace balance in USD after this call, when known."},"cached":{"type":"boolean","description":"True when served from the 24h dedup cache."},"charged_usd":{"type":"number","format":"double","description":"USD charged for this call (0 for reads of stored data and for test keys)."},"next_cursor":{"type":["string","null"]},"request_id":{"type":["string","null"]},"truncated":{"type":"boolean","description":"True when the result was cut to fit `response_format=concise` or a page limit."}}},"NewKey":{"allOf":[{"$ref":"#/components/schemas/KeyInfo"},{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"The plaintext key — shown once, store it now."}}}]},"Project":{"type":"object","required":["id","name","domain","brand_aliases","competitors","created_at"],"properties":{"brand_aliases":{"type":"array","items":{"type":"string"},"description":"Alternate spellings of the brand."},"competitors":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"domain":{"type":"string","description":"Primary domain, e.g. \"acme.com\"."},"id":{"type":"string"},"name":{"type":"string","description":"Brand name as it appears in AI answers (also the project name)."},"prompts":{"type":"array","items":{"type":"string"},"description":"Tracked prompts used by default in visibility runs."}}},"Quality":{"type":"object","description":"How much to trust a squad's output: the verifier redid `audited` items and agreed on\n`agreed` of the comparable judgements.","required":["audited","compared","agreed","note"],"properties":{"agreed":{"type":"integer","format":"int32","minimum":0},"agreement":{"type":["number","null"],"format":"double","description":"agreed / compared with a 95% Wilson interval; None when nothing was audited."},"agreement_ci":{"type":["array","null"],"items":{"type":"number","format":"double"}},"audited":{"type":"integer","format":"int32","minimum":0},"compared":{"type":"integer","format":"int32","minimum":0},"note":{"type":"string"}}},"Rate":{"type":"object","required":["count","of","rate","ci"],"properties":{"ci":{"type":"array","items":{"type":"number","format":"double"},"description":"95% Wilson interval."},"count":{"type":"integer","format":"int64","minimum":0},"of":{"type":"integer","format":"int64","minimum":0},"rate":{"type":"number","format":"double"}}},"Signup":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Workspace name, e.g. your company."}}},"SiteAuditInput":{"type":"object","description":"`site_audit` input.","required":["url"],"properties":{"background":{"type":["boolean","null"],"description":"Run in the background and return an `audit_id` to poll with `audit_get`. Defaults to\ntrue above 25 pages (about 1 s per page)."},"bot_view":{"type":["boolean","null"],"description":"Also fetch the homepage with AI-bot user agents to spot CDN/WAF blocking (default true)."},"dry_run":{"type":"boolean","description":"Quote the maximum price without crawling."},"max_pages":{"type":["integer","null"],"format":"int32","description":"Pages to crawl (1–100, default 25). You pay only for pages actually crawled.","minimum":0},"render":{"type":["integer","null"],"format":"int32","description":"Pages to also render with JavaScript (0–10, default 3; homepage and thinnest pages\nfirst) to measure content that only appears after JS runs. $0.002 per rendered page.","minimum":0},"url":{"type":"string","description":"Domain or URL to audit, e.g. \"example.com\" (https:// is assumed)."}}},"SuggestInput":{"type":"object","required":["category"],"properties":{"audience":{"type":["string","null"],"description":"Who buys it, e.g. \"seed-stage B2B SaaS founders\"."},"brand":{"type":["string","null"],"description":"Brand name (required without a project)."},"category":{"type":"string","description":"What the brand sells, e.g. \"SEO API for AI agents\". The single most useful input."},"competitors":{"type":"array","items":{"type":"string"}},"domain":{"type":["string","null"]},"dry_run":{"type":"boolean"},"locale":{"type":["string","null"],"description":"BCP-47 locale, default \"en-US\" (prompts are written in its language)."},"n":{"type":["integer","null"],"description":"How many prompts (1–50, default 15).","minimum":0},"project":{"type":["string","null"],"description":"Optional project (id, name or domain): fills brand, domain and competitors."},"track":{"type":"boolean","description":"Also add the suggestions to the project's tracked prompts."}}},"Suggested":{"type":"object","required":["prompt","intent"],"properties":{"intent":{"$ref":"#/components/schemas/Intent"},"prompt":{"type":"string"},"why":{"type":"string","description":"Why a buyer would ask this (≤ 15 words)."}}},"Suggestions":{"type":"object","required":["prompts","tracked","team","price_usd","charged_usd"],"properties":{"charged_usd":{"type":"number","format":"double"},"price_usd":{"type":"number","format":"double"},"prompts":{"type":"array","items":{"$ref":"#/components/schemas/Suggested"}},"team":{"type":"string"},"tracked":{"type":"boolean","description":"True when the prompts were added to the project's tracked prompts."}}},"TrackPrompts":{"type":"object","properties":{"add":{"type":"array","items":{"type":"string"}},"remove":{"type":"array","items":{"type":"string"}}}},"VisibilityRunInput":{"type":"object","required":["project"],"properties":{"dry_run":{"type":"boolean","description":"true = return the cost estimate only; nothing runs, nothing is charged."},"engines":{"type":"array","items":{"type":"string"},"description":"Engine keys, e.g. [\"chatgpt\",\"perplexity\",\"claude\"]. Omit for all configured engines."},"locale":{"type":["string","null"],"description":"BCP-47 locale, default \"en-US\"."},"project":{"type":"string","description":"Project id, name or domain."},"prompts":{"type":"array","items":{"type":"string"},"description":"Prompts to sample. Omit to use the project's tracked prompts."},"queued":{"type":"boolean","description":"true = use the cheaper standard queue for consumer-UI engines (chatgpt_ui,\ngoogle_ai_mode: $0.003 instead of $0.01). Results take minutes instead of seconds;\nAPI engines are unaffected. Pair with `webhook_url` instead of polling."},"samples":{"type":["integer","null"],"format":"int32","description":"Samples per prompt × engine (1–50, default 5). More samples → tighter intervals.","minimum":0},"web_search":{"type":["boolean","null"],"description":"false = parametric probe (search disabled). Default true."},"webhook_url":{"type":["string","null"],"description":"Optional public https URL: we POST the finished job there, signed with your\nworkspace's webhook_secret (see account_get). Saves polling job_get."}}}}}}