Connect your app to AgenticSEO

What AgenticSEO is

AgenticSEO measures and fixes how a website shows up in AI answers (ChatGPT, Gemini, Google AI Overviews) as well as in classical search. It crawls a site, scores it, works out which questions buyers actually ask, checks whether the answer engines name the brand, and produces the exact copy and markup needed to close the gaps.

Everything the product does in its own interface is also callable from outside it. There are two ways in, with the same functions, the same key, the same permissions, the same rate limit and the same audit log behind both.

Two ways to call it

Keep the key on the server

// Server-side only. In a Lovable app this is an edge function.
// The key lives in a secret named AGENTICSEO_KEY and never reaches the browser.
const KEY = Deno.env.get('AGENTICSEO_KEY')!;
const BASE = 'https://hbzbbsodddymrhmreqkd.supabase.co/functions/v1/api/v1';

const res = await fetch(`${BASE}/visibility?company_id=${companyId}`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
const data = await res.json();

What your key allows

A read-only key carries the read and analyze permissions and no publishing permissions. Calls outside that set come back as 403 with a machine-readable code rather than a silent partial result.

First audit, step by step

1. POST /v1/discovery with the root URL. You get back every reachable page, so nothing is spent crawling pages nobody wants.
2. POST /v1/reports with the discovery id and the pages to audit. This returns a job id; it does not block.
3. GET /v1/jobs/<id> every 30 seconds until status is "done". A small site takes a minute or two; several hundred pages take longer.
4. GET /v1/reports/<report_id> for the finished report, and /v1/reports/<report_id>/llms-txt for the generated file.
5. POST /v1/visibility/analyze with just a URL to seed questions, competitors and a first AI-visibility score in one call.
6. GET /v1/visibility and GET /v1/visibility/trend to render the score and its movement over time.

Every function we support

Each function is callable as an MCP tool or as a plain web request. Anything marked write is excluded from a read-only key.

Things worth embedding in an app

Hand this to your AI builder

The brief restates everything on this page in a form written for a coding assistant: endpoints, the key rule, the full catalog with permissions, the audit sequence, and a list of features it can build. Paste it into Lovable, Claude or Cursor and ask what it can add.

# AgenticSEO integration brief (paste this into your AI builder)

You are helping me connect my application to AgenticSEO, an AI-visibility and SEO service. Read this brief, then tell me what I can usefully build with it and offer to implement one of the ideas.

## What the service does
AgenticSEO measures and fixes how a website shows up in AI answers (ChatGPT, Gemini, Google AI Overviews) as well as in classical search. It crawls a site, scores it, works out which questions buyers actually ask, checks whether the answer engines name the brand, and produces the exact copy and markup needed to close the gaps.

Everything the product does in its own interface is also callable from outside it. There are two ways in, with the same functions, the same key, the same permissions, the same rate limit and the same audit log behind both.

## Two ways to call it
### MCP server (for AI assistants and agents)
`https://hbzbbsodddymrhmreqkd.supabase.co/functions/v1/mcp`
JSON-RPC 2.0 over HTTP. Point Claude Desktop, Claude Code, Cursor or any MCP-capable agent at this URL with the bearer key and the whole function catalog becomes available as tools. Every POST must send Accept: application/json, text/event-stream or the server answers 406.

### REST API (for ordinary application code)
`https://hbzbbsodddymrhmreqkd.supabase.co/functions/v1/api/v1/...`
Plain HTTPS with JSON bodies. This is the right choice when the calls are made by your own application rather than by an assistant. Authenticate with Authorization: Bearer <your key>. GET /v1/health needs no key and is a good first call.

## Non-negotiable security rule
Your key must never reach the browser. A React front end that calls AgenticSEO directly ships the key to every visitor. Put the key in a server-side secret, add one small server function (an edge function in a Lovable app) that calls AgenticSEO, and have your pages call that function instead. The key is a password: server-side only, never in front-end code and never committed to a repository.

Example server-side call:

```ts
// Server-side only. In a Lovable app this is an edge function.
// The key lives in a secret named AGENTICSEO_KEY and never reaches the browser.
const KEY = Deno.env.get('AGENTICSEO_KEY')!;
const BASE = 'https://hbzbbsodddymrhmreqkd.supabase.co/functions/v1/api/v1';

const res = await fetch(`${BASE}/visibility?company_id=${companyId}`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
const data = await res.json();
```

## What my key allows
A read-only key carries the read and analyze permissions and no publishing permissions. Calls outside that set come back as 403 with a machine-readable code rather than a silent partial result.

- Allowed: Run a site audit and read the finished report, including the generated llms.txt.
- Allowed: Read AI-visibility scores, share of voice, per-engine breakdown and the trend over time.
- Allowed: Read the tracked questions, their run history and the best-matching page for each.
- Allowed: Read content gaps, drafted gap pages, competitors and the competitor scoreboard.
- Allowed: Read citation sources, cited authors, product/SKU visibility and Google Search Console performance.
- Not allowed: Publish anything to a website, or push answers to a connected publishing target.
- Not allowed: Confirm coined category terms, run the fix files, or resolve gaps on the customer’s behalf.
- Not allowed: See any company other than the ones the key is bound to.

## Standard sequence for a first audit
1. POST /v1/discovery with the root URL. You get back every reachable page, so nothing is spent crawling pages nobody wants.
2. POST /v1/reports with the discovery id and the pages to audit. This returns a job id; it does not block.
3. GET /v1/jobs/<id> every 30 seconds until status is "done". A small site takes a minute or two; several hundred pages take longer.
4. GET /v1/reports/<report_id> for the finished report, and /v1/reports/<report_id>/llms-txt for the generated file.
5. POST /v1/visibility/analyze with just a URL to seed questions, competitors and a first AI-visibility score in one call.
6. GET /v1/visibility and GET /v1/visibility/trend to render the score and its movement over time.

## Operational limits
- Rate limit: 100 requests per hour per key by default. Exceeding it returns 429 with the limit and reset time.
- Errors always use { "error": { "code": "...", "message": "..." } } with a matching HTTP status. Over MCP the same failure arrives as JSON-RPC error -32000.
- Audits are asynchronous. Start, poll, then read — never hold a request open waiting for one.
- Fresh AI-visibility numbers are worth asking for at most once every 15 minutes per company; scores barely move inside that window.

## Full function catalog

### Site discovery & analysis
Enumerate a site, enqueue an analysis over a chosen subset, poll the job, and read the finished report. This is the core "one-time audit" flow that produces every AgenticSEO output (Layers 1–6).

| MCP tool | REST endpoint | Permission | What it does |
| --- | --- | --- | --- |
| `discover_site` | `POST /v1/discovery` | read | Enumerate every reachable page on a site before spending an analyze. |
| `analyze_site` | `POST /v1/reports` | analyze | Enqueue an AgenticSEO analysis over a discovered subset. |
| `get_job_status` | `GET /v1/jobs/{id}` | read | Poll job status; response carries report_id when done. |
| `get_report` | `GET /v1/reports/{id}` | read | Fetch a full report (metadata + per-page outputs across all 6 layers, plus Annex A when enabled). |
| `list_reports` | `GET /v1/reports` | read | List recent reports visible to this token. |
| `get_llms_txt` | `GET /v1/reports/{id}/llms-txt` | read | Return the site-wide llms.txt for a completed report. |

### AI Visibility (prompts, citations, competitors)
Measure whether real assistants (ChatGPT, Gemini, Perplexity, Claude) cite your customer for the prompts their buyers actually type. Cold-start from a URL, or read rolled-up scores + trends once monitoring is on.

| MCP tool | REST endpoint | Permission | What it does |
| --- | --- | --- | --- |
| `analyze_ai_visibility` | `POST /v1/visibility/analyze` | analyze | Cold-start: URL → prompt set → per-prompt rank + share-of-voice in one call. |
| `get_visibility_scores` | `GET /v1/visibility` | read | Latest AI Visibility rollup + diagnostics block. |
| `enable_visibility_monitoring` | `POST /v1/visibility/monitor` | analyze | Turn on scheduled recomputes for a company. |
| `get_visibility_trend` | `GET /v1/visibility/trend` | read | Time-series scores + deltas + new/lost competitors. |
| `list_prompts` | `GET /v1/prompts` | read | Tracking prompts + latest run per prompt. |
| `get_prompt_history` | `GET /v1/prompts/{id}/history` | read | Per-prompt run history for charting change over time. |
| `run_prompts_now` | `POST /v1/visibility/run` | analyze | Headless re-score: fan out every enabled tracked prompt and compute a fresh visibility_scores row. |
| `get_run_status` | `GET /v1/visibility/status` | none | Poll latest score, enabled prompts, complete runs (30d), and in-flight runs. |
| `get_competitor_breakdown` | `GET /v1/benchmarks/breakdown` | read | Per-brand rollup: cited_count, voice_share, avg_position, is_user_brand. |
| `suggest_benchmark_prompts` | `POST /v1/benchmarks/suggest-prompts` | analyze | AI-generated new tracked prompts targeting competitor-dominated territory. |

### AI crawler access
Standalone Layer 3 audit — cheap, no prior report or discovery needed.

| MCP tool | REST endpoint | Permission | What it does |
| --- | --- | --- | --- |
| `get_ai_crawler_access` | `GET /v1/crawler-access?url=<site-url>` | read | /robots.txt allow/deny for every tracked AI crawler + copy-paste fix snippet. |

### FAQ drafting & publishing
Convert every tracked content gap (a prompt no page on the site answers) into copy-paste FAQ Q&A pairs, then optionally forward those cached drafts to a connected downstream target (Quid today; webhook / WordPress / HubSpot adapters slot in server-side).

| MCP tool | REST endpoint | Permission | What it does |
| --- | --- | --- | --- |
| `draft_faqs_for_gaps` | `POST /v1/faqs/draft` | faq:draft | Draft copy-paste FAQ Q&A pairs for tracked-prompt content gaps. |
| `publish_faq_to_target` | `POST /v1/faqs/publish` | faq:publish (write) | Forward cached FAQ drafts to a connected downstream target. |
| `resolve_gaps` | `POST /v1/gaps/resolve` | faq:publish (write) | Record that content gaps are handled on your side (completes workflow step 4). |
| `list_publish_targets` | `GET /v1/faqs/targets` | none | List downstream targets available to publish_faq_to_target. |

### Competitor set management
Inspect and curate the competitor set that powers Citation Presence and share-of-voice comparisons. analyze_ai_visibility seeds an initial auto-discovered list; these tools let a partner UI (Quid, etc.) show it, add missing competitors, and prune ones the user rejects — without touching AgenticSEO's own UI.

| MCP tool | REST endpoint | Permission | What it does |
| --- | --- | --- | --- |
| `list_competitors` | `GET /v1/competitors` | none | List tracked competitors (source = auto / manual). |
| `discover_competitors` | `POST /v1/competitors/discover` | competitors:write (write) | Re-run auto-discovery. Preview by default; persist=true writes new suggestions. |
| `add_competitors` | `POST /v1/competitors` | competitors:write (write) | Add manual competitors (source = "manual", never auto-swept). |
| `remove_competitors` | `POST /v1/competitors/remove` | competitors:write (write) | Soft-delete competitors by id or name. |

### Gap pages (persisted briefs → live URLs)
The Prompt Audit report drafts brand-new pages for tracked prompts that no existing page on the site answers. Those briefs are now persisted in `public.gap_pages` and can be flipped to "published" — at which point they render at https://agenticseo.live/g/<slug>, appear in the sitemap on the next build, and become readable by every AI crawler. This group is the partner-facing surface for listing, reading, publishing, and unpublishing them without touching the AgenticSEO UI.

| MCP tool | REST endpoint | Permission | What it does |
| --- | --- | --- | --- |
| `list_gap_pages` | `GET /v1/gap-pages` | gap_pages:read | List drafted + published gap pages for a company. |
| `get_gap_page` | `GET /v1/gap-pages/{id_or_slug}` | gap_pages:read | Fetch one gap page (all 6-layer fields + outline + rationale). |
| `publish_gap_pages` | `POST /v1/gap-pages/publish` | gap_pages:publish (write) | Flip drafted gap pages to published (live at /g/<slug>). |
| `unpublish_gap_page` | `POST /v1/gap-pages/unpublish` | gap_pages:publish (write) | Return a published gap page to draft status. |

### Google Search performance (Search Console)
Real, measured Google Search data for a company — clicks, impressions, CTR, impression-weighted average position, a daily trend, and the top 25 queries and pages ranked by impressions. Sourced live from Google Search Console via the connected Google account for that client, so these are actuals, not a vendor estimate. This is the classical-search counterpart to get_visibility_scores (Share of AI Voice): pair them to show a customer both halves of discoverability in one view. Included on every tier and metered at zero credits, because Search Console is a free first-party connection.

| MCP tool | REST endpoint | Permission | What it does |
| --- | --- | --- | --- |
| `get_gsc_performance` | `GET /v1/gsc/performance` | none | Clicks, impressions, CTR, average position + top queries/pages. |
| `list_gsc_properties` | `GET /v1/gsc/properties` | none | Verified properties covering this company’s site + the bound one. |
| `select_gsc_property` | `POST /v1/gsc/property` | analyze | Bind one property to the company for all later reads. |

### Prompt-to-page mapping, engines & PR narrative
The mirror image of gap pages: which existing page best answers each tracked question, which answer engines a company can be measured across, and which publishers and authors the engines actually cite when they describe the brand. All read-only.

| MCP tool | REST endpoint | Permission | What it does |
| --- | --- | --- | --- |
| `get_analyze_visibility_status` | `GET /v1/visibility/status` | read | Poll an async analyze_ai_visibility job until it finishes. |
| `list_prompt_page_mappings` | `GET /v1/prompts/pages` | read | For every tracked question, the best existing page that answers it plus a relevance score. |
| `get_prompt_page_mapping` | `GET /v1/prompts/:id/pages` | read | Best and second-best page for a single tracked question. |
| `list_engines` | `GET /v1/engines` | none | Answer engines this company can be measured across, and which its plan includes. |
| `list_citation_sources` | `GET /v1/pr/sources` | none | Publishers and domains the engines cite about this brand and category. |
| `list_cited_authors` | `GET /v1/pr/authors` | none | Journalists and analysts whose bylined articles the engines cite. |
| `get_narrative_analysis` | `GET /v1/pr/narrative` | none | Trailing-window narrative view with reinforce and respond action lists. |

### Attribution, workspaces, workflow & idea generation
Tie visibility work to real traffic, segment an OEM footprint into workspaces, check how fresh a client's data is, and generate grounded recommendations for a weak benchmark metric.

| MCP tool | REST endpoint | Permission | What it does |
| --- | --- | --- | --- |
| `sync_ai_referrals` | `POST /v1/attribution/sync` | analyze | Pull AI-referred sessions from Google Analytics 4. |
| `get_ai_referral_summary` | `GET /v1/attribution/summary` | none | Before-and-after AI referral traffic around a pivot date. |
| `list_workspaces` | `GET /v1/workspaces` | workspaces:read | OEM only — list workspaces under the calling partner token. |
| `create_workspace` | `POST /v1/workspaces` | workspaces:write | OEM only — create a workspace. |
| `assign_company_to_workspace` | `POST /v1/workspaces/assign` | workspaces:write | OEM only — map a company into one of the partner's workspaces. |
| `resolve_company` | `GET /v1/company/resolve` | read | Resolve a company visible to this token by url, host, brand name or id. |
| `get_workflow_status` | `GET /v1/workflow/status` | read | Freshness snapshot for a client, with a green/amber/red staleness verdict. |
| `generate_benchmark_ideas` | `POST /v1/visibility/ideas` | none | Grounded recommendations for a weak benchmark metric. |

### Commerce — product / SKU visibility
Classic AI visibility answers "do the engines know this brand?". Commerce answers the harder retail question: for each individual product, does ChatGPT / Gemini / Perplexity mention it, does it actually recommend it, where does it place it in a list, and which competitor products get named instead. The flow is: sync a catalog once (Shopify, WooCommerce, a Google Merchant / RSS feed, CSV, or a raw products[] payload), then scan on a schedule and read the rollup. Scans deliberately score a ROTATING, priority-weighted sample of the catalog rather than every SKU every cycle — thousands of engine calls per cycle would be unaffordable and the answers barely move day to day. High-priority SKUs are revisited often, the long tail is covered less frequently, so seeing fewer data points for a tail SKU is normal and not an error to retry around. Driving commerce headlessly over MCP / REST requires the Enterprise plan or an OEM agreement with commerce access switched on (in-app SKU monitoring is available on Pro and Agency). Unentitled calls return 403 plan_required; an agreed monthly SKU-check ceiling returns 429 commerce_cap_reached.

| MCP tool | REST endpoint | Permission | What it does |
| --- | --- | --- | --- |
| `sync_product_catalog` | `POST /v1/commerce/catalog/sync` | analyze | Import or refresh a product catalog so its SKUs can be monitored. |
| `list_products` | `GET /v1/commerce/products` | read | List monitored SKUs, highest priority first, with their last scan result. |
| `scan_product_visibility` | `POST /v1/commerce/scan` | analyze | Score this cycle’s rotating SKU sample across the answer engines. |
| `get_product_visibility` | `GET /v1/commerce/visibility` | read | Commerce rollup + the invisible-SKU work queue. |

### Health
Unauthenticated probes for uptime checks.

| MCP tool | REST endpoint | Permission | What it does |
| --- | --- | --- | --- |
| `—` | `GET /v1/health` | none | Returns { status: "ok" }. |

## Things worth embedding in an app
- **AI visibility score panel** — Show a customer their brand mention rate, citation rate and share of voice, with the trend line. Reads GET /v1/visibility and GET /v1/visibility/trend.
- **Audit-on-demand button** — Let a user type a URL and get a full AEO/SEO report. Discovery, then analyze, then poll, then render the report.
- **"Questions buyers ask" widget** — List the tracked questions with whether the engines name the brand in each answer. Reads GET /v1/prompts.
- **Gap worklist** — Show the questions where the brand is absent, and the best existing page for each, as a prioritised to-do list. Reads GET /v1/prompts/pages and the gap-page endpoints.
- **Competitor scoreboard** — Rank the brand against the competitors the engines actually cite. Reads GET /v1/competitors and GET /v1/benchmarks/breakdown.
- **Crawler access check** — A one-call diagnostic showing which AI crawlers a site allows or blocks. Reads GET /v1/crawler-access.
- **Search Console side-by-side** — Put real Google clicks and impressions next to the AI-answer numbers. Reads GET /v1/gsc/performance.

## What to do now
Summarise for me, in plain language, what this service can add to my app. Then propose the smallest useful first feature, and when I agree: create the server-side secret for the key, add one server function that proxies to the REST endpoints listed above, and build the UI that reads from it. Never place the key in front-end code.

Limits, errors and cadence

• Rate limit: 100 requests per hour per key by default. Exceeding it returns 429 with the limit and reset time.
• Errors always use { "error": { "code": "...", "message": "..." } } with a matching HTTP status. Over MCP the same failure arrives as JSON-RPC error -32000.
• Audits are asynchronous. Start, poll, then read — never hold a request open waiting for one.
• Fresh AI-visibility numbers are worth asking for at most once every 15 minutes per company; scores barely move inside that window.

Need a key, extra permissions or a higher rate limit? Email support@tractiongappartners.com.