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/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:

Discovery 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 4 AI models, producing ~500 data points per weekly cycle. Prompts rotate from a pool of 400 per industry category, so over a month you cover the full set. Business plans run daily at ~1,000 data points/scan (7,000+/week). Executive plans produce ~1,600/scan (11,200+/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, Gemini, Perplexity, and Google AI Overview, 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 (GPT-4o) — OpenAI's flagship model with web search, the most widely used AI assistant
Google Gemini — Google's AI with Google Search grounding, deeply integrated into Google's ecosystem
Perplexity — AI-powered search engine with real-time web access, growing rapidly
Google AI Overview — AI-generated summaries shown at the top of Google search results
Claude (add-on) — Anthropic's Claude with web search. Available as a paid add-on on Growth+ plans due to specialized infrastructure requirements.

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 weekly scan runs 100+ prompts across 4 AI models — that's 500+ data points per cycle, with prompts rotating from a pool of 400 per category. Your score is a statistical aggregate, not a snapshot. Multi-model consensus (ChatGPT, Gemini, Perplexity, Google AI Overview) filters out model-specific quirks. Business plans run daily with 1,000+ data points per scan (7,000+/week), and Executive plans produce 1,600+ per scan (11,200+/week) — at that density, noise becomes statistically irrelevant.

Which AI models does Foxish monitor?

Foxish monitors four major AI platforms: ChatGPT (GPT-4o with web search), Google Gemini (with Google Search grounding), Perplexity (with built-in web search), and Google AI Overview. Claude can be added as a paid add-on on Growth plans and above — it requires specialized browser scraping infrastructure which is why it's priced separately.

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: Discovery (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: Starter plans run monthly, Growth and Pro plans run weekly, and 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.