REST API Reference — AgenticSEO

Base URL & auth

https://hbzbbsodddymrhmreqkd.supabase.co/functions/v1/api/v1

Every request (except /health) requires the same mcp_… bearer token already issued for MCP:

Authorization: Bearer mcp_<your-token>

Endpoints

POST/v1/discovery

Enumerate every reachable page on a site. Body: { url, max_urls? }. Returns { discovery_id, urls[], details[], total, capped, source_counts }. Pass discovery_id to /v1/reports with select='all' | {top_n:N} | {indexes:[...]} to enqueue a subset without re-discovering.

MCP equivalent: discover_site

POST/v1/reports

Enqueue an AgenticSEO analysis. Three input shapes: { url, urls: [...] } | { url?, discovery_id, select } | { url, max_pages } (legacy). Returns { job_id, brand, urls_queued, discovery_id, discovered_total, … }.

MCP equivalent: analyze_site

GET/v1/jobs/{id}

Poll job status. When status='done' the response carries report_id.

MCP equivalent: get_job_status

GET/v1/reports

List recent reports visible to this token. Query: limit, brand, host.

MCP equivalent: list_reports

GET/v1/reports/{id}

Fetch a full report (metadata + per-page outputs).

MCP equivalent: get_report

GET/v1/reports/{id}/llms-txt

Return the report's generated llms.txt as text/plain.

MCP equivalent: get_llms_txt

GET/v1/visibility

Latest AI Visibility score. Agency tokens can pass brand or host to select a client.

MCP equivalent: get_visibility_scores

POST/v1/visibility/run

Force recompute on demand. Body: { company_id | brand | host, window_days? }. Fans out every enabled tracked prompt and computes a fresh rollup. Returns { score_id, computed_at, data_ready }. Recommended cadence: no more than once every 15 min per company. Requires scope analyze.

MCP equivalent: run_prompts_now

GET/v1/visibility/status

Poll after /v1/visibility/run. Query: company_id | brand | host. Returns latest score + in-flight/complete run counts and data_ready flag. Poll every 5s (typical 30–120s, up to ~5 min on large sets).

MCP equivalent: get_run_status

POST/v1/visibility/ideas

Gemini-backed idea generator for the four benchmark metrics (brand_mention, domain_citation, share_of_voice, prompt_win_rate). Body: { company_id | url | host | brand, metrics?: string[], style?: 'finn' | 'neutral' }. Returns 5–7 grounded, prioritised recommendations per metric. Use style='neutral' to strip TGF/Market Engineering framing for white-label re-branding. Safe to call after /v1/visibility whenever a metric is weak.

MCP equivalent: generate_benchmark_ideas

GET/v1/company/resolve

Resolve a company_id from url, host, brand, or company_id. Use as the recovery handle when analyze_ai_visibility returns IDLE_TIMEOUT. Returns { company_id, name, host, matched_by }. 404 client_not_found when unmatched — never falls back to the token's own company on agency tokens.

MCP equivalent: resolve_company

POST/v1/faqs/draft

Draft copy-paste FAQ Q&A pairs for tracked-prompt content gaps. Body: { prompts?, limit?, refresh?, company_id?, brand?, host? }. Cached; only spends AI credits on new prompts or when refresh=true. Requires scope faq:draft.

MCP equivalent: draft_faqs_for_gaps

POST/v1/faqs/publish

Forward cached FAQ drafts (from /v1/faqs/draft or the in-app FAQ generator) to a connected downstream target — MCP server, REST webhook, or CMS. Body: { prompts, target?, company_id?, brand?, host? }. Omit target to auto-pick the first connected one. Quid is available today (beta); more adapters plug in server-side. Requires scope faq:publish.

MCP equivalent: publish_faq_to_target

GET/v1/faqs/targets

List downstream targets available to /v1/faqs/publish (id + label). Read-only.

MCP equivalent: list_publish_targets

GET/v1/health

Unauthenticated health probe. Returns { status: 'ok' }.

MCP equivalent: —

Quick start (curl)

# 1a. Discover the site (recommended)
curl -X POST 'https://hbzbbsodddymrhmreqkd.supabase.co/functions/v1/api/v1/discovery' \
  -H 'Authorization: Bearer mcp_<your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.example.com/","max_urls":500}'

# 1b. Enqueue a subset from that discovery
curl -X POST 'https://hbzbbsodddymrhmreqkd.supabase.co/functions/v1/api/v1/reports' \
  -H 'Authorization: Bearer mcp_<your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"discovery_id":"<id>","select":{"top_n":25},"brand_name":"Example"}'

# 1c. Or use the legacy one-shot shorthand
curl -X POST 'https://hbzbbsodddymrhmreqkd.supabase.co/functions/v1/api/v1/reports' \
  -H 'Authorization: Bearer mcp_<your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.example.com/","brand_name":"Example","max_pages":25}'

# 2. Poll every ~30s
curl -H 'Authorization: Bearer mcp_<your-token>' \
  'https://hbzbbsodddymrhmreqkd.supabase.co/functions/v1/api/v1/jobs/<job_id>'

# 3. Fetch the completed report
curl -H 'Authorization: Bearer mcp_<your-token>' \
  'https://hbzbbsodddymrhmreqkd.supabase.co/functions/v1/api/v1/reports/<report_id>'

Errors

All error responses share this envelope:

{ "error": { "code": "not_found", "message": "Report not found" } }

401 unauthorized — missing, malformed, or revoked bearer token
403 forbidden — token missing a required scope (e.g. analyze)
404 not_found — resource not visible to this token
400 invalid_argument / invalid_json — bad input
429 rate_limited — per-hour cap on the token was hit
500 internal_error — unexpected failure; safe to retry with backoff

Rate limits & audit

REST and MCP share the same per-token per-hour rate limit. Every call is recorded in the audit log with a transport label (mcp or rest) so you can see both channels side by side in Admin > MCP Activity.

Not yet in v1

Webhooks (push delivery) — parked until an integrator requests it
Cursor-based pagination (current list caps at 50 items)
Per-page write endpoints (approve fix, edit metadata)
Self-serve API-key issuance UI (tokens are minted by Admin)

AgenticSEO REST API