Your AI visibility toolkit

Everything you need to add AI visibility to your apps, agents, and workflows

REST API

10 endpoints to manage brands, trigger scans, and pull visibility data into your own apps

GETcitesurf.com/api/v1/brands

MCP Server

11 tools that let AI assistants check and monitor your brand visibility right from the editor

$npx -y @citesurf/mcp

Agent Skill

Give any coding agent instant access to AI visibility checks with a single install command

$npx skills add citesurf/skill

Quick Start

Get up and running in under a minute.

Get your API key

Generate an API key from your dashboard settings. Requires a Plus or Max subscription.

Make your first request

Use your API key to list your brands.

curl https://citesurf.com/api/v1/brands \
  -H "Authorization: Bearer cs_live_your_key_here"

See the response

You'll get back a JSON response with your brand data.

{
  "data": [
    {
      "id": "clx...",
      "name": "Acme Inc",
      "website": "acme.com",
      "visibilityScore": 72,
      "mentionRate": 0.65,
      "scanActive": true
    }
  ]
}

Authentication

All API requests require a valid API key sent as a Bearer token.

How it works

1Generate an API key in your dashboard settings
2Include it in the Authorization header as a Bearer token
3Each key is shown once, store it securely

curl https://citesurf.com/api/v1/account \
  -H "Authorization: Bearer cs_live_abc123..."

API Reference

Base URL: https://citesurf.com/api/v1

OpenAPI Spec

https://citesurf.com/api/v1

Brands

GET/v1/brands

Returns all active (non-archived) brands for your account, including latest scan metrics.

Response

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "website": "string",
      "type": "PERSON | PRODUCT | COMPANY | SHOP",
      "category": "string | null",
      "description": "string | null",
      "language": "string",
      "createdAt": "datetime",
      "visibilityScore": "number",
      "mentionRate": "number",
      "scoreChange": "number",
      "probeCount": "integer",
      "scanActive": "boolean",
      "lastScanAt": "datetime | null"
    }
  ]
}

curl https://citesurf.com/api/v1/brands \
  -H "Authorization: Bearer $API_KEY"

POST/v1/brands

Creates a new brand, analyzes it with AI, and triggers an initial scan. Rate limited to 10 per 24 hours.

Request body

{
  "name": "string",
  "website": "string",
  "language": "en | es | de | fr | pt | it | nl | pl"
}

Response

{
  "data": {
    "id": "string",
    "name": "string"
  }
}

curl -X POST https://citesurf.com/api/v1/brands \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Inc","website":"acme.com","language":"en"}'

GET/v1/brands/:id

Returns full brand details including visibility metrics, competitor analysis, sentiment distribution, platform breakdown, and site audit data.

Parameters

idstringrequiredBrand ID

Response

{
  "data": {
    "id": "string",
    "name": "string",
    "website": "string",
    "type": "PERSON | PRODUCT | COMPANY | SHOP",
    "category": "string | null",
    "description": "string | null",
    "language": "string",
    "createdAt": "datetime",
    "visibilityScore": "number",
    "mentionRate": "number",
    "scoreChange": "number",
    "averagePosition": "number | null",
    "shareOfVoice": "number",
    "caveatRate": "number",
    "avgFirstMentionOffset": "number",
    "sentimentDistribution": {
      "positive": "number",
      "neutral": "number",
      "negative": "number"
    },
    "topCitedDomains": [
      {
        "domain": "string",
        "count": "integer"
      }
    ],
    "competitors": [
      {
        "name": "string",
        "website": "string | null",
        "mentionCount": "integer"
      }
    ],
    "platformBreakdown": [
      {
        "platform": "CHATGPT | CLAUDE | PERPLEXITY | GEMINI",
        "score": "number",
        "mentionRate": "number",
        "probeCount": "integer"
      }
    ],
    "fixedPrompts": [
      "string"
    ],
    "scanActive": "boolean",
    "scanCount": "integer",
    "probeCount": "integer",
    "lastScanAt": "datetime | null"
  }
}

curl https://citesurf.com/api/v1/brands/:id \
  -H "Authorization: Bearer $API_KEY"

DELETE/v1/brands/:id

Deletes the brand and all associated data including probes, insights, and scan history. Stops any active scan schedule.

Parameters

idstringrequiredBrand ID

Response

{
  "data": {
    "success": "true"
  }
}

curl -X DELETE https://citesurf.com/api/v1/brands/:id \
  -H "Authorization: Bearer $API_KEY"

PATCH/v1/brands/:id

Update brand type, category, description, or fixed monitoring prompts. All fields are optional — only provided fields are updated. Changes take effect on the next scan.

Parameters

idstringrequiredBrand ID

Request body

{
  "type": "PERSON | PRODUCT | COMPANY | SHOP",
  "category": "string",
  "description": "string",
  "prompts": [
    "string"
  ]
}

Response

{
  "data": {
    "id": "string",
    "name": "string",
    "website": "string",
    "type": "PERSON | PRODUCT | COMPANY | SHOP",
    "category": "string",
    "description": "string",
    "language": "string",
    "prompts": [
      "string"
    ],
    "updatedAt": "datetime"
  }
}

curl -X PATCH https://citesurf.com/api/v1/brands/:id \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"PERSON","category":"string","description":"string","prompts":["string"]}'

GET/v1/brands/:id/insights

Returns AI-generated insights for the brand. Insights include visibility recommendations, sentiment analysis, competitive positioning, and opportunities.

Parameters

idstringrequiredBrand ID

statusstring (pending | completed)Filter insights by completion status.

offsetintegerNumber of items to skip for pagination.Default: 0min: 0

pageSizeintegerNumber of insights per page.Default: 20min: 1max: 50

Response

{
  "data": {
    "insights": [
      {
        "id": "string",
        "brandId": "string",
        "type": "VISIBILITY | SENTIMENT | POSITIONING | COMPETITION | OPPORTUNITY",
        "priority": "HIGH | MEDIUM | LOW",
        "title": "string",
        "description": "string",
        "completedAt": "datetime | null",
        "createdAt": "datetime"
      }
    ],
    "hasMore": "boolean",
    "offset": "integer",
    "counts": {
      "all": "integer",
      "pending": "integer",
      "completed": "integer"
    }
  }
}

curl https://citesurf.com/api/v1/brands/:id/insights?status=pending&offset=0&pageSize=20 \
  -H "Authorization: Bearer $API_KEY"

PATCH/v1/brands/:id/insights/:insightId

Marks an insight as completed (with before/after validation metrics) or dismisses it (deletes it). Already-completed insights are returned as-is.

Parameters

idstringrequiredBrand ID

insightIdstringrequiredInsight ID

Request body

{
  "action": "dismiss | complete"
}

Response

{
  "data": {
    "success": "boolean",
    "insight": {
      "id": "string",
      "brandId": "string",
      "type": "VISIBILITY | SENTIMENT | POSITIONING | COMPETITION | OPPORTUNITY",
      "priority": "HIGH | MEDIUM | LOW",
      "title": "string",
      "description": "string",
      "completedAt": "datetime | null",
      "createdAt": "datetime"
    },
    "validation": {
      "before": {
        "visibilityScore": "number",
        "mentionRate": "number",
        "averagePosition": "number | null",
        "averageSentiment": "number | null",
        "totalScans": "integer"
      },
      "after": {
        "visibilityScore": "number",
        "mentionRate": "number",
        "averagePosition": "number | null",
        "averageSentiment": "number | null",
        "totalScans": "integer"
      },
      "improvement": {
        "visibilityChange": "number",
        "positionChange": "number",
        "sentimentChange": "number",
        "mentionRateChange": "number"
      },
      "effective": "boolean",
      "message": "string"
    }
  }
}

curl -X PATCH https://citesurf.com/api/v1/brands/:id/insights/:insightId \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"dismiss"}'

GET/v1/brands/:id/site-audit

Returns technical SEO audit results including robots.txt AI crawler access, llms.txt, Schema.org JSON-LD, XML sitemap, and Open Graph checks. Returns null if no audit has been run (e.g., social-only brands).

Parameters

idstringrequiredBrand ID

Response

{
  "data": {}
}

curl https://citesurf.com/api/v1/brands/:id/site-audit \
  -H "Authorization: Bearer $API_KEY"

GET/v1/brands/:id/personas

Returns custom audience personas with their associated prompts and per-platform scan results. Pagination controls the scan history depth per prompt.

Parameters

idstringrequiredBrand ID

offsetintegerNumber of items to skip for pagination.Default: 0min: 0

pageSizeintegerNumber of scan results per prompt (controls scan history depth).Default: 2min: 1max: 50

Response

{
  "data": {
    "personas": [
      {
        "id": "string",
        "name": "string",
        "description": "string | null",
        "prompts": [
          {}
        ]
      }
    ],
    "hasMore": "boolean",
    "offset": "integer",
    "pageSize": "integer"
  }
}

curl https://citesurf.com/api/v1/brands/:id/personas?offset=0&pageSize=2 \
  -H "Authorization: Bearer $API_KEY"

GET/v1/brands/:id/report

Returns the latest AI visibility report data for a brand

Parameters

idstringrequiredBrand ID

Response

{
  "data": {
    "brandName": "string",
    "website": "string | null",
    "description": "string | null",
    "language": "string | null",
    "summary": {
      "visibilityScore": "number",
      "scoreChange": "number",
      "mentionRate": "number",
      "averagePosition": "number | null",
      "shareOfVoice": "number",
      "caveatRate": "number",
      "totalScans": "integer",
      "avgFirstMentionOffset": "number"
    },
    "platformScores": {
      "CHATGPT": "number",
      "CLAUDE": "number",
      "GEMINI": "number",
      "PERPLEXITY": "number"
    },
    "prompts": [
      {
        "text": "string",
        "category": "string",
        "personaName": "string | null",
        "mentionRate": "number",
        "mentions": "integer",
        "totalResponses": "integer",
        "platformResults": {}
      }
    ],
    "sentimentDistribution": {
      "positive": "integer",
      "neutral": "integer",
      "negative": "integer"
    },
    "contextDistribution": {
      "RECOMMENDATION": "integer",
      "COMPARISON": "integer",
      "WARNING": "integer",
      "NEUTRAL": "integer"
    },
    "competitors": [
      {
        "name": "string",
        "mentionCount": "integer"
      }
    ],
    "citedDomains": [
      {
        "domain": "string",
        "count": "integer"
      }
    ],
    "trends": [
      {
        "date": "string",
        "visibilityScore": "number",
        "mentionRate": "number",
        "platformScores": {
          "CHATGPT": {},
          "CLAUDE": {},
          "GEMINI": {},
          "PERPLEXITY": {}
        }
      }
    ],
    "siteAudit": {},
    "auditIssues": [
      {
        "type": "string",
        "priority": "HIGH | MEDIUM | LOW"
      }
    ],
    "insights": [
      {
        "type": "string",
        "priority": "string",
        "title": "string",
        "description": "string",
        "action": "string"
      }
    ]
  }
}

curl https://citesurf.com/api/v1/brands/:id/report \
  -H "Authorization: Bearer $API_KEY"

Scans

GET/v1/brands/:id/scans

Returns a paginated list of scans for the brand, ordered by most recent first. Each scan includes aggregate metrics.

Parameters

idstringrequiredBrand ID

offsetintegerNumber of items to skip for pagination.Default: 0min: 0

pageSizeintegerNumber of scans per page.Default: 20min: 1max: 100

Response

{
  "data": {
    "scans": [
      {
        "id": "string",
        "createdAt": "datetime",
        "visibilityScore": "integer",
        "mentionRate": "integer",
        "averagePosition": "number | null",
        "platformScores": {},
        "sentimentDistribution": {},
        "topCompetitors": {},
        "topCitedDomains": {},
        "probeCount": "integer",
        "shareOfVoice": "integer",
        "caveatRate": "integer",
        "avgFirstMentionOffset": "integer"
      }
    ],
    "hasMore": "boolean",
    "offset": "integer",
    "pageSize": "integer",
    "total": "integer"
  }
}

curl https://citesurf.com/api/v1/brands/:id/scans?offset=0&pageSize=20 \
  -H "Authorization: Bearer $API_KEY"

GET/v1/brands/:id/scans/:scanId

Returns full scan detail including aggregate metrics, all probes with per-platform results, and the site audit if it was run during this scan.

Parameters

idstringrequiredBrand ID

scanIdstringrequiredScan ID

Response

{
  "data": {}
}

curl https://citesurf.com/api/v1/brands/:id/scans/:scanId \
  -H "Authorization: Bearer $API_KEY"

GET/v1/brands/:id/prompts

Returns prompt-level scan results grouped by prompt text. Each prompt includes per-platform responses, mention data, sentiment analysis, and competitor context. Supports filtering by platform and pagination of scan history per prompt.

Parameters

idstringrequiredBrand ID

platformstring (CHATGPT | CLAUDE | PERPLEXITY | GEMINI)Filter results to a specific AI platform (case-insensitive).

offsetintegerNumber of items to skip for pagination.Default: 0min: 0

pageSizeintegerNumber of scan results per prompt (controls scan history depth).Default: 10min: 1max: 100

Response

{
  "data": {
    "prompts": [
      {
        "id": "string",
        "text": "string",
        "isFixed": "boolean",
        "persona": {
          "name": {}
        },
        "scans": [
          {}
        ],
        "stats": {
          "totalScans": {},
          "mentionRate": {},
          "avgPosition": {},
          "platformBreakdown": {}
        },
        "totalResults": "integer",
        "hasMore": "boolean"
      }
    ],
    "count": "integer",
    "platformFilter": "string",
    "hasMore": "boolean",
    "offset": "integer",
    "pageSize": "integer"
  }
}

curl https://citesurf.com/api/v1/brands/:id/prompts?platform=CHATGPT&offset=0&pageSize=10 \
  -H "Authorization: Bearer $API_KEY"

GET/v1/brands/:id/trends

Returns time-series visibility data for the brand over the specified range. Each data point includes visibility score, mention rate, average position, and per-platform scores.

Parameters

idstringrequiredBrand ID

rangeinteger (7 | 30 | 90)Number of days to look back. Invalid values default to 30.Default: 30

Response

{
  "data": {
    "range": "integer",
    "trends": [
      {
        "date": "string",
        "visibilityScore": "number",
        "mentionRate": "number",
        "averagePosition": "number | null",
        "CHATGPT": "number",
        "CLAUDE": "number",
        "PERPLEXITY": "number",
        "GEMINI": "number"
      }
    ]
  }
}

curl https://citesurf.com/api/v1/brands/:id/trends?range=30 \
  -H "Authorization: Bearer $API_KEY"

POST/v1/brands/:id/scan

Triggers an asynchronous full 4-platform scan for the brand. Costs 1 credit. The scan runs in the background via QStash. Poll the scans endpoint for results. Credits are refunded if the trigger fails.

Parameters

idstringrequiredBrand ID

Response

{
  "data": {
    "brandId": "string",
    "creditsUsed": "1",
    "creditsRemaining": "integer",
    "status": "triggered"
  }
}

curl -X POST https://citesurf.com/api/v1/brands/:id/scan \
  -H "Authorization: Bearer $API_KEY"

Account

GET/v1/account

Returns your plan, payment status, brand count, brand limit, and credit balance.

Response

{
  "data": {
    "plan": "TRIAL | PLUS | MAX",
    "paymentStatus": "NONE | ACTIVE | FAILED | CANCELLED",
    "brandCount": "integer",
    "brandLimit": "integer",
    "creditBalance": "integer"
  }
}

curl https://citesurf.com/api/v1/account \
  -H "Authorization: Bearer $API_KEY"

Error Codes

AUTH_REQUIRED401API key is missing or invalid

FORBIDDEN403You don't have access to this resource

INSUFFICIENT_CREDITS402Not enough credits to perform this action

NOT_FOUND404The requested resource was not found

VALIDATION_FAILED400Request body or parameters are invalid

SERVER_ERROR500An unexpected server error occurred

List endpoints support offset and pageSize query parameters. Responses include a hasMore field indicating if more results exist.

Brands support 8 languages: en, es, de, fr, pt, it, nl, pl. Set the language field when creating a brand to get localized AI prompts.

MCP Server

Use Citesurf directly from your AI coding tools.

The Citesurf MCP server exposes all API functionality as tools for AI assistants. Install via npm and configure your editor.

Installation

npm install -g @citesurf/mcp

Configuration

{
  "mcpServers": {
    "citesurf": {
      "command": "npx",
      "args": ["-y", "@citesurf/mcp"],
      "env": {
        "CITESURF_API_KEY": "cs_live_your_key_here"
      }
    }
  }
}

npm GitHub

Available Tools

Brands

list_brandsList all monitored brands

get_brandGet brand details

create_brandCreate a new brand

delete_brandDelete a brand

get_promptsGet AI probe results

get_personasGet persona audience probe results

get_insightsGet recommendations

update_insightComplete or dismiss an insight

get_site_auditGet site audit results

Scans

list_scansList scans with paginated results

get_scanGet scan detail with probes and site audit

get_trendsGet visibility trend data over time

trigger_scanTrigger a scan (1 credit)

Account

get_accountGet account info

Agent Skill

AI visibility built into your coding workflow.

The Citesurf skill lets AI coding agents check and monitor your brand's AI visibility without leaving the editor.

Installation

npx skills add citesurf/skill

skills.sh

When it triggers

Check my brand's AI visibility

Run a scan for acme.com

How is my brand doing on ChatGPT?

What should I fix to improve AI mentions?

Capabilities

Check if AI platforms mention your brand
Monitor visibility scores across ChatGPT, Claude, Gemini, and Perplexity
Get actionable recommendations to improve AI presence
Run on-demand scans from your editor
Access full scan history and insights

Ready to build?

Get started with your API key and start monitoring AI visibility programmatically.