Documentation

Everything you need to integrate with Foxish and understand your AI visibility data.

API Reference

REST API endpoints for scores, brands, scans, and mentions

Methodology

How visibility scores work and how we handle AI variability

FAQ

Common questions about models, prompts, scoring, and security

API Reference

The Foxish API lets you programmatically access your visibility data. All endpoints require an API key — generate one in Settings → API Keys.

Authentication

Include your API key in the Authorization header:

curl https://foxish.ai/api/v1/scores \
  -H "Authorization: Bearer YOUR_API_KEY"

Base URL

https://foxish.ai/api/v1

GET/api/v1/scores

Fetch visibility scores for your brands

Parameters

Name	Type	Required	Description
`brand_id`	string	optional	Filter by specific brand
`limit`	number	optional	Max results (default 10, max 100)

Response

{
  "data": [{
    "visibility_score": 42.5,
    "discovery_score": 38,
    "perception_score": 65,
    "ranking_score": 45,
    "sentiment_score": 72,
    "brand_id": "...",
    "period_start": "2026-03-29",
    "created_at": "..."
  }]
}

GET/api/v1/brands

List all brands (your brand + competitors) in your organization

Response

{
  "data": [{
    "id": "...",
    "name": "Acme Corp",
    "domain": "acme.com",
    "is_primary": true,
    "aliases": ["Acme", "AcmeCorp"],
    "created_at": "..."
  }]
}

GET/api/v1/scans

List your scan runs

Parameters

Name	Type	Required	Description
`limit`	number	optional	Max results (default 10, max 100)

Response

{
  "data": [{
    "id": "...",
    "status": "completed",
    "trigger_type": "api",
    "total_prompts": 100,
    "completed_prompts": 100,
    "failed_prompts": 0,
    "started_at": "...",
    "completed_at": "...",
    "created_at": "..."
  }]
}

POST/api/v1/scans

Trigger a new scan for your organization

Response

{
  "data": {
    "id": "...",
    "status": "pending"
  }
}

Returns 409 if a scan is already in progress.

GET/api/v1/prompts

List all prompts configured for your organization

Response

{
  "data": [{
    "id": "...",
    "category": "best_in_category",
    "name": "Best CRM tools",
    "prompt_text": "What are the best CRM tools for...",
    "is_active": true,
    "created_at": "..."
  }]
}

GET/api/v1/products

List tracked SKUs with per-SKU AI-visibility aggregates. Supports incremental polling via updated_since.

Parameters

Name	Type	Required	Description
`updated_since`	ISO 8601	optional	Only return SKUs whose updated_at is newer
`limit`	number	optional	Max results (default 100, max 500)
`offset`	number	optional	Pagination offset

Response

{
  "data": [{
    "id": "...",
    "sku": "PWD-HND-165",
    "name": "Powder Hound 165",
    "aliases": ["PH-165"],
    "url": "https://...",
    "category_slug": "snowboards",
    "updated_at": "...",
    "mention_rate": 42,
    "mention_rate_reliable": true,
    "total_results": 120,
    "mentioned_results": 50,
    "last_mention_at": "...",
    "scores_by_model": {
      "chatgpt": { "visibility": 55, "mention_count": 12 },
      "gemini-pro": { "visibility": 30, "mention_count": 6 }
    }
  }],
  "total": 40, "limit": 100, "offset": 0
}

GET/api/v1/products/{sku}

Single-SKU deep dive — per-model, per-prompt, competitor, and weekly trend data.

Parameters

Name	Type	Required	Description
`sku`	string	required	Merchant SKU (URL-decoded, case-sensitive)

Response

{
  "id": "...", "sku": "...", "name": "...",
  "mention_rate": 42, "scores_by_model": { ... },
  "per_prompt": [{ "prompt_id": "...", "prompt_text": "...", "mentioned": true, "position": 3 }],
  "competitors": [{ "brand_name": "Burton", "mention_count": 18 }],
  "trend": [{ "week_start": "2026-08-25", "mention_rate": 40, "total_results": 60 }]
}

Returns 404 if the SKU does not exist on your org.

GET/api/v1/products/{sku}/mentions

Weekly mention-rate timeline for a single SKU.

Parameters

Name	Type	Required	Description
`weeks`	number	optional	Weeks of history (default 12, max 52)

Response

{
  "sku": "PWD-HND-165", "product_id": "...",
  "points": [{ "week_start": "2026-08-25", "mention_rate": 40, "total_results": 60, "mentioned_results": 24 }]
}

POST/api/v1/products

Bulk-import SKUs. Upserts on (organization_id, sku). Rejects rows whose category_slug isn't in your allocations.

Parameters

Name	Type	Required	Description
`products`	array	required	Array of { sku, name, aliases?, url?, description?, category_slug? }

Response

{
  "inserted": 12, "updated": 3, "skipped": 0,
  "errors": [
    { "error": "invalid_category_slug", "sku": "XYZ-42", "category_slug": "bad-slug" }
  ]
}

If the plan cap is exceeded, extra rows are dropped and errors[] includes { error: 'plan_limit_reached', cap, requested, inserted }.

POST/api/v1/products/import/amazon

Import SKUs directly from an Amazon Seller Central 'All Listings Report' .txt payload.

Parameters

Name	Type	Required	Description
`report`	string	required	Tab-separated report contents (verbatim)

Response

{ "inserted": 42, "updated": 8, "skipped": 0, "errors": [] }

POST/api/v1/orgs

Provision a new Foxish org for a partner-managed merchant. Operator-key only.

Parameters

Name	Type	Required	Description
`name`	string	required	Merchant / brand name
`canonical_category`	string	required	Must exist in global_categories
`business_type`	"ecom"	required	Only 'ecom' is supported through this endpoint
`plan_tier`	string	required	growth \| pro \| business \| executive
`domain`	string	optional	Brand website
`amazon_seller_id`	string	optional	Persisted on organization.metadata for partner lookup

Response

{
  "organization_id": "...", "slug": "...",
  "api_key": "bk_...",   // returned once — persist immediately
  "benchmark_status": "queued"
}

403 if the caller's key isn't marked role='operator'.

GET/api/v1/webhooks

List webhook subscriptions for the caller's org.

Response

{
  "data": [{
    "id": "...", "url": "https://...", "events": ["sku.mention_rate_dropped"],
    "is_active": true, "created_at": "...", "updated_at": "..."
  }]
}

POST/api/v1/webhooks

Create a webhook subscription. Response includes a 'secret' returned once — verify HMAC on incoming deliveries with it.

Parameters

Name	Type	Required	Description
`url`	string	required	HTTPS endpoint to POST payloads to
`events`	string[]	required	One or more of: sku.mention_rate_dropped, sku.mention_rate_gained, sku.first_mention, brand.mention_rate_dropped, brand.mention_rate_gained, scan.completed

Response

{
  "id": "...", "url": "...", "events": [...],
  "secret": "hex-string",   // shown once — store to verify X-Foxish-Signature
  "is_active": true, "created_at": "...", "updated_at": "..."
}

DELETE/api/v1/webhooks/{id}

Remove a webhook subscription.

Response

{ "deleted": true }

POST/api/v1/webhooks/{id}/test

Fire a synthetic delivery so you can validate the receiver + signature verification without waiting for a real event.

Response

{ "delivery_id": "...", "event": "sku.mention_rate_dropped", "status": "dispatched" }

GET/api/v1/mentions

Fetch brand mentions extracted from AI responses

Parameters

Name	Type	Required	Description
`scan_run_id`	string	optional	Filter by specific scan run
`brand_id`	string	optional	Filter by specific brand
`limit`	number	optional	Max results (default 50, max 500)

Response

{
  "data": [{
    "id": "...",
    "brand_id": "...",
    "mentioned": true,
    "mention_text": "Acme Corp is a leading...",
    "position": 2,
    "sentiment": "positive",
    "sentiment_score": 0.85,
    "is_recommended": true,
    "context_summary": "...",
    "created_at": "..."
  }]
}

Methodology

How Foxish measures your brand's presence across AI platforms.

How Scoring Works

Your visibility score (0-100) is a weighted composite of five sub-scores:

Visibility Score — How often AI mentions your brand when users ask general category questions (e.g., “What are the best CRM tools?”)
Perception Score — The sentiment tone when your brand is mentioned (positive, neutral, or negative)
Ranking Score — Where you appear in recommendation lists (1st vs 5th vs not listed)
Category Score — Performance in industry-specific prompts tailored to your market
Sentiment Score — Overall tone analysis across all mentions

Each score is calculated across all prompts and all AI models in your latest scan, then normalized to a 0-100 scale.

Handling AI Variability

AI models are non-deterministic — ask ChatGPT the same question twice and you may get different recommendations. Foxish doesn't rely on any single response. Here's how we handle it:

Statistical volume — On Pro, every scan runs 100+ prompts across 5 AI sources, producing ~500 data points per daily scan (3,500+ a week). Prompts rotate from a pool of 400 per industry category, so over a month you cover the full set. Business plans run ~1,250 data points per daily scan (8,750+ a week). Executive plans produce ~2,000 per scan (14,000+ a week) — at that density, individual variance is statistically irrelevant.
Trend over time — Scores are tracked over weeks and months. A single anomalous response doesn't move your score — sustained changes in AI perception do.
Multi-model consensus — By comparing results across ChatGPT, Google AI Overview, Gemini, Copilot, and Perplexity, we identify genuine trends vs model-specific quirks.
Per-model breakdown — Your dashboard shows scores by model so you can see if one platform treats your brand differently.

AI Models Monitored

ChatGPT — OpenAI's AI assistant with web search, with 1B+ weekly users
Google AI Overview — AI-generated summaries shown at the top of Google search results, the most-seen AI surface (Free and Starter)
Google Gemini — Google's AI with Google Search grounding (Growth and above)
Microsoft Copilot — Microsoft's assistant grounded in Bing, with product carousels (Growth and above)
Perplexity — AI-powered search engine with real-time web access (Pro and above)
Claude — Anthropic's assistant with web search, an optional paid add-on on top of any plan from Growth up

FAQ

Common questions about Foxish.

How does Foxish handle AI response variability?

AI models are non-deterministic — the same prompt can produce different responses. Foxish doesn't rely on any single response. On Pro, every daily scan runs 100+ prompts across 5 AI sources — that's 500+ data points per scan, with prompts rotating from a pool of 400 per category. Your score is a statistical aggregate, not a snapshot. Multi-source consensus (ChatGPT, Google AI Overviews, Gemini, Copilot, Perplexity) filters out model-specific quirks. Business plans scan 250 prompts across the same five sources; Executive plans push volume further — at that density, individual variance becomes statistically irrelevant.

Which AI models does Foxish monitor?

Foxish monitors five AI platforms: ChatGPT (with web search), Google AI Overview, Google Gemini, Microsoft Copilot (grounded in Bing, with product carousels), and Perplexity. Coverage tiers up with your plan — Free and Starter cover ChatGPT and Google AI Overview, Growth adds Gemini and Copilot, Pro and above add Perplexity. Claude (Haiku) is an optional paid add-on from Growth up.

Which AI crawlers does the audit check?

Foxish audits your robots.txt against all seven major AI crawlers: GPTBot (OpenAI training), OAI-SearchBot (ChatGPT Search live retrieval), ClaudeBot (Anthropic), Google-Extended (Google Gemini), PerplexityBot (Perplexity), Applebot-Extended (Apple Intelligence), and CCBot (Common Crawl). Each is checked and weighted separately, and the report calls out any blocked bots as CRITICAL fixes — because if a vendor's crawler can't access your site, that vendor's AI models will never index it, and every other AEO improvement is wasted.

What is llms.txt and does Foxish support it?

llms.txt is an emerging convention (like robots.txt but for LLMs) where sites publish a machine-readable markdown summary of their key pages at /llms.txt. LLMs read the file to understand your site directly instead of guessing from crawled content. Adoption is early, so publishing one is a competitive edge. Foxish detects whether your site has an llms.txt during every scan, and offers a built-in generator (Website Intelligence → Generate llms.txt) that turns your scanned pages into a valid llms.txt you can drop into your web root in minutes.

What are search prompts vs custom prompts?

Search prompts are industry-curated prompts shared across all users in your category (e.g., "best CRM for small business"). Foxish maintains 400+ prompts per industry category, run automatically on your scan schedule. Custom prompts are ones you write yourself to track specific questions relevant to your brand. The number of custom prompts depends on your plan tier.

How is the visibility score calculated?

Your visibility score (0-100) is a composite of five sub-scores: Visibility (how often AI mentions you unprompted), Perception (sentiment when mentioned), Ranking (your position in recommendation lists), Category (performance in industry-specific prompts), and Sentiment (overall tone). Each sub-score is weighted and normalized across all prompts and models in your latest scan.

How often are scans run?

Scan frequency depends on your plan: Free and Starter plans run weekly; Growth, Pro, Business, and Executive plans run daily. Search prompts (industry benchmarks) follow this same schedule. Custom prompts are scanned on the same cycle. You can also trigger manual scans from the dashboard or via the API.

Is my data secure?

Yes. All data is stored in Supabase with row-level security (RLS) — each organization can only access its own data. API access is authenticated with unique API keys that you generate from your dashboard. All connections use HTTPS. We never share your data with other users or third parties.

Can't find what you're looking for? Contact us and we'll help.