BotSee

Hosted OAuth MCP for repeatable AI-visibility research: compare brand and competitor mentions, keywords, cited sources and raw responses across ChatGPT, Claude, Perplexity and Gemini for marketing and agency workflows. Hosted analysis uses paid credits; free directory placement does not mean free product usage. Official image: https://botsee.io/botsee/favicon.svg ; official agency/builder explainer: https://botsee.io/botsee/videos/botsee-agency-376da54b20e43ebf6986966acbd98f9a.mp4?vsn=d . Documentation reviewed; no authenticated runtime test claimed.

View on botsee.io

Hosted MCP Server

npx add-mcp 'https://botsee.io/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

Quick Start (Claude Code Plugin)

Install the BotSee plugin for the fastest setup. Choose the method that matches your platform.

Method 1: Claude Code Plugin (recommended)

/install-plugin https://github.com/RivalSee/botsee

Auto-updates to latest version. All /botsee commands are available immediately.

Method 2: Direct Python CLI (Codex, Cursor, any platform)

git clone https://github.com/RivalSee/botsee-skill.git
python3 /path/to/botsee-skill/skills/botsee/botsee.py [command] [args]

Works on any platform with Python 3. No dependencies beyond stdlib. Update manually with git pull.

Method 3: Codex / OpenAI agents

Add the script path to your agent's tool configuration. The CLI accepts all commands as positional args:

python3 /path/to/botsee-skill/skills/botsee/botsee.py signup --api-key YOUR_KEY
python3 /path/to/botsee-skill/skills/botsee/botsee.py create-site https://example.com
python3 /path/to/botsee-skill/skills/botsee/botsee.py analyze

All output is stdout (human-readable for workflow commands, JSON for CRUD commands). Exit code 1 on errors with messages to stderr.

Commands

/botsee - Status and help
/botsee signup [--email EMAIL] [--name NAME] [--company COMPANY] - Start signup flow (all params optional)
/botsee create-site <domain> [--types N] [--personas P] [--questions Q] - Create site and generate structure
/botsee analyze - Run competitive analysis (~660 credits)
/botsee content - Generate blog post from analysis (estimated ~15 credits)
/botsee config-show - Display current workspace configuration
/botsee status - Show balance and active site

Example Workflow

Here are 6 sequential prompts for the workflow:

Prompt 1: Install & Signup

Install the BotSee Plugin: /install-plugin https://github.com/RivalSee/botsee. Then sign me up for BotSee using my email [email protected] so I can analyze how AI search engines see my product.

Prompt 2: Create Site with Structure

Create a BotSee site for https://myproduct.com with 1 customer type, 2 personas, and 5 questions per persona. Set it up so I can run a competitive analysis.

Prompt 3: Analyze & Show Competitors

Run a competitive analysis and show me the full list of competitors mentioned by AI search engines, including their mention percentages and what contexts they appear in.

Prompt 4: Show Keywords

Show me all the keywords that AI search engines associate with my product category, sorted by frequency.

Prompt 5: Generate Blog Titles

Based on those keywords and competitor insights, give me 5 compelling blog post titles that would help us compete better in AI search results.

Prompt 6: Write Blog Post

Write a full blog post for the first title, including our competitive position, opportunities, threats, and recommended actions based on the analysis data.

The plugin handles authentication, API calls, and result formatting automatically.

All Plugin Commands

Complete reference for all BotSee plugin commands. Shown as `/botsee <command>` (Claude Code plugin). Direct CLI equivalent: `python3 path/to/botsee.py <command>`.

Account & Status

/botsee status              # Show balance, active site, key suffix
/botsee account             # Show email, company, site count
/botsee signup [--email] [--name] [--company] [--api-key KEY]
/botsee update              # Update skill to latest version

Workflow Commands

/botsee create-site <domain> [--types T --personas P --questions Q]
/botsee config-show         # Display workspace configuration
/botsee analyze [site_uuid] # Run competitive analysis
/botsee content             # Generate blog post from latest analysis
/ai-visibility-audit <url>  # Full audit: setup → analyze → gap table → copy changes

Sites Management

/botsee list-sites
/botsee get-site [uuid]
/botsee archive-site <uuid>
/botsee use-site <uuid>     # Switch active site

Customer Types Management

/botsee list-types [--site-uuid UUID]
/botsee get-type <uuid>
/botsee create-type <site_uuid> --name "..." [--description "..."]
/botsee generate-types [--site-uuid UUID --count N]
/botsee update-type <uuid> [--name "..." --description "..."]
/botsee archive-type <uuid>

Personas Management

/botsee list-personas [type_uuid]
/botsee get-persona <uuid>
/botsee create-persona <type_uuid> --name "..." [--icp-persona "..."]
/botsee generate-personas <type_uuid> [--count N]
/botsee update-persona <uuid> [--name "..." --icp-persona "..."]
/botsee archive-persona <uuid>

Questions Management

/botsee list-questions [persona_uuid]
/botsee get-question <uuid>
/botsee create-question <persona_uuid> --text "..."
/botsee generate-questions <persona_uuid> [--count N]
/botsee update-question <uuid> --text "..."
/botsee delete-question <uuid>

Results Viewing

/botsee results-competitors <analysis_uuid>
/botsee results-keywords <analysis_uuid>
/botsee results-sources <analysis_uuid>
/botsee results-responses <analysis_uuid>

AI Visibility Audit

A complete workflow that audits how AI search engines see a site, identifies terminology gaps, and produces surgical landing page copy changes. Available as a skill (/ai-visibility-audit) or as manual steps.

Quick Start

/ai-visibility-audit https://example.com

The skill creates a BotSee site, generates customer types/personas/questions, runs analysis across ChatGPT, Claude, Perplexity, and Gemini, then:

1. Pulls keyword and source opportunities 2. Fetches your live homepage and compares terminology 3. Produces a gap table of missing terms with evidence 4. Proposes surgical copy changes (text only, no layout changes) 5. Compiles, commits, and pushes when approved

Overview

The AI Visibility Audit combines BotSee analysis with homepage comparison to find and close terminology gaps — terms AI engines use that your site doesn't.

Cost: ~~735 credits (~~$7.35) | Time: ~25 minutes

Workflow

Step 1: Create site and generate structure

/botsee create-site https://example.com

Creates a site with 2 customer types, 4 personas, and 20 auto-generated questions (~75 credits).

Step 2: Review and replace questions

Auto-generated questions are often too generic. Replace them with questions matching how real customers ask AI engines.

/botsee list-questions <persona_uuid>
/botsee delete-question <question_uuid>
/botsee create-question <persona_uuid> "What tools help with AI search optimization?"

Step 3: Run analysis

/botsee analyze

Queries ChatGPT, Claude, Perplexity, and Gemini in parallel (~660 credits). Capture the analysis UUID from output.

Step 4: Pull opportunities

/botsee results-keyword-opportunities <analysis_uuid>
/botsee results-source-opportunities <analysis_uuid>

Keyword opportunities — queries where your brand is missing or ranks poorly
Source opportunities — sites AI cites when it doesn't mention you (link-building targets)

Step 5: Compare against live homepage

Fetch the live homepage and compare its language against what AI engines searched for. Look for:

Terms AI uses that the page doesn't (industry acronyms, category names)
Phrases competitors rank for that the site doesn't use
Audience segments not addressed
Missing integration or feature keywords

Produces a gap table:

Missing Term	Evidence
"share of voice"	8 search queries mentioning it
"REST API"	Competitor X ranks for this

Step 6: Make surgical copy changes

Edit only text strings — no layout changes. Target: page title, meta description, hero headline, feature descriptions, section headers, and integration lists.

Step 7: Verify and ship

Compile to check for syntax errors, then commit and push.

Skill Shortcut

Install the BotSee plugin, then run /ai-visibility-audit to execute this entire workflow automatically. See [Recipes](/recipes#ai-visibility-audit) for a visual walkthrough.

MCP Connector (ChatGPT, Claude)

Use BotSee from ChatGPT, Claude (Cowork, claude.ai, Desktop), or any MCP client. Sign in or sign up on botsee.io when you connect; no API key to copy.

Connect

Server URL:

https://botsee.io/mcp

Claude: Settings → Connectors → Add custom connector → paste the URL.
ChatGPT: Settings → Apps & Connectors → Advanced → enable developer mode, then Create → paste the URL, authentication OAuth.

Your browser opens botsee.io. Sign in with your email code, or create an account, then approve access. The connector gets its own API key (named after the client) for your organization. Revoke it any time on the API Keys page.

Tools

The connector exposes the same capabilities as the plugin: account status and usage, USDC top-up, sites (including brand aliases), customer types, personas, questions, analysis runs, results (competitors, keywords, sources, responses, keyword and source opportunities), recommendations, and blog content generation. An ai_visibility_audit prompt walks through a full audit.

run_analysis returns a free preview (planning credit range and warnings) unless you pass dry_run: false.

Other MCP clients

Clients that support a static bearer token can skip OAuth and send Authorization: Bearer <BotSee API key> to the same URL.

Registry

BotSee is published in the official MCP Registry as io.botsee/botsee, verified against this domain. Clients that search the registry can add it from there instead of pasting the URL.

REST API

BotSee monitors how AI search engines see your products. Query multiple AI models with target questions and analyze which competitors, sources, and keywords appear.

Authentication

All authenticated endpoints require a Bearer token in the Authorization header.

Authorization Header

Use this header on all authenticated API endpoints:

Authorization: Bearer bts_live_your_api_key

Example

curl -X POST https://botsee.io/api/v1/auth/validate \
  -H "Authorization: Bearer $BOTSEE_API_KEY"

Notes

Do not send Authorization for public signup endpoints.
USDC payment headers are documented in Signup and USDC Top-Ups.

Validate API key

POST /api/v1/auth/validate Auth

Validates the API key and returns organization info and credit balance.

Response

{
  "valid": true,
  "api_key": {
    "id": 1,
    "name": "My Key",
    "status": "active",
    "key_prefix": "bts_live_abc1",
    "last_used_at": "2026-02-05T10:00:00Z"
  },
  "organization": {
    "id": 1,
    "name": "Acme Corp",
    "slug": "acme-corp"
  },
  "credits": {
    "balance": 500
  }
}

Example

curl -X POST https://botsee.io/api/v1/auth/validate -H "Authorization: Bearer $BOTSEE_API_KEY"

Get account information

GET /api/v1/account Auth

Returns account details including company name, site count, and owner information.

Response

{
  "company_name": "Acme Corp",
  "owner_email": "[email protected]",
  "owner_name": "Jane Smith",
  "site_count": 5
}

Example

curl https://botsee.io/api/v1/account -H "Authorization: Bearer $BOTSEE_API_KEY"

API Keys

Manage API keys for the organization. Newly created keys are returned only once — store the raw key client-side immediately.

List API keys

GET /api/v1/api-keys Auth

Lists all API keys for the organization (raw key never returned).

Response

{
  "api_keys": [
    {
      "id": "ak_1",
      "name": "Production Key",
      "status": "active",
      "created_at": "2026-01-01T00:00:00Z",
      "key_prefix": "bts_live_a1b2",
      "last_used_at": "2026-04-29T09:00:00Z"
    }
  ]
}

Example

curl https://botsee.io/api/v1/api-keys -H "Authorization: Bearer $BOTSEE_API_KEY"

Create API key

POST /api/v1/api-keys Auth

Creates a new API key. The raw key is returned only once in the response body — store it immediately.

Request Body

Field	Type	Required	Description
`name`	string	optional (API Key)	Human-readable name for the key.

Response

{
  "api_key": {
    "id": "ak_2",
    "name": "Production Key",
    "status": "active",
    "key": "bts_live_abc123...",
    "created_at": "2026-04-29T10:00:00Z",
    "key_prefix": "bts_live_abc1"
  }
}

Example

curl -X POST https://botsee.io/api/v1/api-keys -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"name":"Production Key"}'

Revoke API key

DELETE /api/v1/api-keys/:id Auth

Revokes an API key. You cannot revoke the key being used to make this request — use rotate or another key.

Parameters

Name	In	Type	Required	Description
`id`	path	string	required	API key id

Example

curl -X DELETE https://botsee.io/api/v1/api-keys/AK_ID -H "Authorization: Bearer $BOTSEE_API_KEY"

Rotate API key

POST /api/v1/api-keys/:id/rotate Auth

Atomically creates a new API key with the same name and revokes the old one. Returns the new raw key once.

Parameters

Name	In	Type	Required	Description
`id`	path	string	required	API key id to rotate

Response

{
  "api_key": {
    "id": "ak_3",
    "name": "Production Key",
    "status": "active",
    "key": "bts_live_def456...",
    "created_at": "2026-04-29T11:00:00Z",
    "key_prefix": "bts_live_def4"
  }
}

Example

curl -X POST https://botsee.io/api/v1/api-keys/AK_ID/rotate -H "Authorization: Bearer $BOTSEE_API_KEY"

Reset API key with one-time token

POST /api/v1/api-keys/reset

Exchanges a one-time reset token (from email) for a fresh API key. Public endpoint — no Bearer auth required, the token authenticates the request.

Request Body

Field	Type	Required	Description
`token`	string	required	Single-use reset token from the reset email.

Response

{
  "api_key": {
    "id": "ak_4",
    "name": "API Key",
    "status": "active",
    "key": "bts_live_ghi789...",
    "created_at": "2026-04-29T12:00:00Z",
    "key_prefix": "bts_live_ghi7"
  }
}

Example

curl -X POST https://botsee.io/api/v1/api-keys/reset -H "Content-Type: application/json" -d '{"token":"RESET_TOKEN"}'

Request Body

Field	Type	Required	Description
`company_name`	string	optional	Company name (optional)
`contact_name`	string	optional	Contact person name (optional)
`contact_email`	string	optional	Contact email (optional)
`payment_method`	string	optional (credit_card)	Defaults to 'credit_card'. Use `/api/v1/signup/usdc` for USDC.

Response

{
  "expires_at": "2026-02-06T10:00:00Z",
  "payment_method": "credit_card",
  "setup_token": "abc123...",
  "setup_url": "https://botsee.io/setup/abc123...",
  "status_url": "/api/v1/signup/abc123.../status"
}

Example

curl -X POST https://botsee.io/api/v1/signup -H "Content-Type: application/json" -d '{"company_name":"Acme Corp","contact_name":"Jane","contact_email":"[email protected]","payment_method":"credit_card"}'

Agent Wallet Options for x402

Pinch (hosted agent wallet + payment flow)
Coinbase Developer Platform Agentic Wallet

Use your chosen wallet provider to satisfy the 402 challenge and retry with a payment header.

Request Body

Field	Type	Required	Description
`company_name`	string	optional	Company name (optional)
`contact_name`	string	optional	Contact name (optional)
`contact_email`	string	optional	Contact email (optional for USDC)
`no_email`	boolean	optional (false)	Set to true for autonomous agents that skip email verification

Response

{
  "expires_at": "2026-02-06T10:00:00Z",
  "payment_method": "usdc",
  "setup_token": "abc123...",
  "setup_url": "https://botsee.io/setup/abc123...",
  "status_url": "/api/v1/signup/abc123.../status",
  "pay_usdc_url": "/api/v1/signup/abc123.../pay-usdc",
  "poll_url": "/api/v1/signup/abc123.../status"
}

Example

curl -X POST https://botsee.io/api/v1/signup/usdc -H "Content-Type: application/json" -d '{"company_name":"Acme Corp","contact_name":"Jane","contact_email":"[email protected]"}'

Parameters

Name	In	Type	Required	Description
`token`	path	string	required	Signup token
`payment`	header	string	optional	Omit this header to receive 402 payment-required challenge

Request Body

Field	Type	Required	Description
`amount_cents`	integer	required	Amount in USD cents (250-100000, i.e., $2.50-$1000)

Response

{
  "error": {
    "code": "payment_required",
    "message": "USDC payment required"
  },
  "accepts": [
    {
      "amount": "2500000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      },
      "maxTimeoutSeconds": 300,
      "network": "eip155:8453",
      "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "scheme": "exact"
    }
  ],
  "amount_cents": 250,
  "payment_requirements": [
    {
      "amount": "2500000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      },
      "maxTimeoutSeconds": 300,
      "network": "eip155:8453",
      "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "scheme": "exact"
    }
  ],
  "x402Version": 2
}

Example

curl -i -X POST https://botsee.io/api/v1/signup/TOKEN/pay-usdc -H "Content-Type: application/json" -d '{"amount_cents":250}'

Parameters

Name	In	Type	Required	Description
`token`	path	string	required	Signup token

Response

{
  "status": "completed",
  "api_key": "bts_live_abc1",
  "payment_method": "usdc",
  "company_name": "Acme Corp",
  "contact_email": "[email protected]",
  "docs_url": "https://botsee.io/docs"
}

Example

curl https://botsee.io/api/v1/signup/TOKEN/status

Pricing

Public endpoint exposing per-operation credit pricing. Useful for agents to estimate costs before signup or before committing to an analysis.

Get pricing

GET /api/v1/pricing

Returns the credit cost for each chargeable operation. Analysis costs are estimates; the actual debit is computed after completion from actual LLM usage and platform pricing.

Response

{
  "pricing": {
    "note": "Analysis costs shown are estimates. Final charges are calculated after completion from actual LLM usage and platform pricing.",
    "analysis_estimated_per_query": {
      "default": 6,
      "claude": 16,
      "gemini": 2,
      "grok": 6,
      "openai": 5,
      "openai-search": 7,
      "perplexity": 1
    },
    "analysis_reservation_buffer": 2.0,
    "customer_type_generation_per_type": 5,
    "persona_generation_per_persona": 5,
    "question_generation": 10,
    "site_creation_auto_generate": 5
  }
}

Example

curl https://botsee.io/api/v1/pricing

USDC Top-Ups

Add credits with BASE USDC using x402 challenge flow.

Agent Wallet Options for x402

Pinch (hosted agent wallet + payment flow)
Coinbase Developer Platform Agentic Wallet

For top-ups, request the challenge first, then retry the same endpoint with your payment payload.

# 1) Discovery (no auth required, returns 402 + payment-required)
curl -i -X POST https://botsee.io/api/v1/billing/topups/usdc \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":250}'

# 2) Final paid retry (auth + payment header required)
curl -i -X POST "https://botsee.io/api/v1/billing/topups/usdc?api_key=$BOTSEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "payment-signature: $BASE64_PAYMENT_PAYLOAD" \
  -d '{"amount_cents":250}'

Top up via x402 challenge

POST /api/v1/billing/topups/usdc

Discovery call without payment headers returns 402 and does not require auth. Final paid retry requires API key (Authorization, x-api-key, or api_key query param) and supports both `payment` and `payment-signature` headers. Method-compatible with POST, PUT, PATCH, and DELETE.

Parameters

Name	In	Type	Required	Description
`authorization`	header	string	optional	Required on final paid retry when using Bearer auth. Format: Bearer bts_live_...
`x-api-key`	header	string	optional	Alternative to Authorization on final paid retry
`api_key`	query	string	optional	Alternative auth for facilitator-driven final paid retry
`payment`	header	string	optional	Base64-encoded payment payload. Omit for discovery challenge; include on final paid retry.
`payment-signature`	header	string	optional	Alias for `payment` header

Request Body

Field	Type	Required	Description
`amount_cents`	integer	optional	Amount in USD cents (250-100000, i.e., $2.50-$1000). Optional for discovery-only 402 challenge (defaults to configured discovery amount).

Response

{
  "error": {
    "code": "payment_required",
    "message": "USDC payment required"
  },
  "accepts": [
    {
      "amount": "2500000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      },
      "maxTimeoutSeconds": 300,
      "network": "eip155:8453",
      "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "scheme": "exact"
    }
  ],
  "amount_cents": 250,
  "payment_requirements": [
    {
      "amount": "2500000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      },
      "maxTimeoutSeconds": 300,
      "network": "eip155:8453",
      "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "scheme": "exact"
    }
  ],
  "x402Version": 2
}

Example

curl -i -X POST https://botsee.io/api/v1/billing/topups/usdc -H "Content-Type: application/json" -d '{"amount_cents":250}'

Billing Settings

Read and update billing preferences (monthly spend limit, current-month spend, low-balance threshold). For credit balance and transaction history use /api/v1/usage.

Get billing settings

GET /api/v1/billing/settings Auth

Returns the organization's billing settings and current credit balance.

Response

{
  "balance": 4250,
  "monthly_spend_limit_cents": 10000,
  "low_balance_threshold": 100,
  "current_month_spend_cents": 1500,
  "max_monthly_spend_cents": 50000
}

Example

curl https://botsee.io/api/v1/billing/settings -H "Authorization: Bearer $BOTSEE_API_KEY"

Update billing settings

PATCH /api/v1/billing/settings Auth

Updates the organization's monthly spend limit. Other settings are read-only via this endpoint.

Request Body

Field	Type	Required	Description
`monthly_spend_limit_cents`	integer	optional	Maximum spend per calendar month in cents. Cannot exceed max_monthly_spend_cents.

Response

{
  "balance": 4250,
  "monthly_spend_limit_cents": 20000,
  "low_balance_threshold": 100,
  "current_month_spend_cents": 1500,
  "max_monthly_spend_cents": 50000
}

Example

curl -X PATCH https://botsee.io/api/v1/billing/settings -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"monthly_spend_limit_cents":20000}'

Sites

Sites represent a domain and product you want to monitor across AI search engines.

List sites

GET /api/v1/sites Auth

Returns a paginated list of sites for the organization.

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	optional (50)	Max results (1-100)
`cursor`	query	string	optional	Pagination cursor from previous response
`include_archived`	query	boolean	optional (false)	Include archived sites

Response

{
  "cursor": null,
  "sites": [
    {
      "status": "active",
      "domain": "example.com",
      "uuid": "abc-123",
      "product_name": "My Product",
      "created_at": "2026-02-05T10:00:00Z"
    }
  ]
}

Example

curl https://botsee.io/api/v1/sites -H "Authorization: Bearer $BOTSEE_API_KEY"

Get site

GET /api/v1/sites/:uuid Auth

Returns a site with its customer types and persona counts.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Site UUID

Response

{
  "site": {
    "status": "active",
    "domain": "example.com",
    "aliases": "Acme, Acme Corp",
    "uuid": "abc-123",
    "product_name": "My Product",
    "value_proposition": "We help teams...",
    "created_at": "2026-02-05T10:00:00Z",
    "customer_types": [
      {
        "name": "Enterprise",
        "uuid": "ct-1",
        "persona_count": 3
      }
    ],
    "customer_type_count": 2
  }
}

Example

curl https://botsee.io/api/v1/sites/SITE_UUID -H "Authorization: Bearer $BOTSEE_API_KEY"

Update site

PUT /api/v1/sites/:uuid Auth

Updates a site's editable metadata: product_name, value_proposition, and aliases. All fields are optional; omitted fields are left unchanged and explicit null clears a field. Non-string, non-null values return 400 validation_error. The aliases field is a comma-separated list of alternate brand names BotSee uses to recognize the brand in AI answers. created_via, billing_status, domain, and visibility cannot be changed here. PATCH is accepted as an alias for PUT.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Site UUID

Request Body

Field	Type	Required	Description
`aliases`	string	optional	Comma-separated alternate brand names (e.g. 'Acme, Acme Corp')
`product_name`	string	optional	Product name
`value_proposition`	string	optional	Value proposition

Response

{
  "site": {
    "status": "active",
    "domain": "example.com",
    "aliases": "Acme, Acme Corp",
    "uuid": "abc-123",
    "product_name": "My Product",
    "value_proposition": "We help teams...",
    "created_at": "2026-02-05T10:00:00Z",
    "customer_types": [],
    "customer_type_count": 0
  }
}

Example

curl -X PUT https://botsee.io/api/v1/sites/SITE_UUID -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"aliases":"Acme, Acme Corp"}'

Create site

POST /api/v1/sites ~5 (estimated) if auto-generating Auth

Creates a new site. Auto-generates product_name and value_proposition from URL if not provided (estimated ~5 credits).

Request Body

Field	Type	Required	Description
`url`	string	required	Full URL to analyze (e.g. 'https://example.com/products/foo')
`domain`	string	optional	Domain override (extracted from URL if not provided)
`product_name`	string	optional	Product name (auto-generated from URL if not provided, estimated ~5 credits)
`value_proposition`	string	optional	Value proposition (auto-generated from URL if not provided, estimated ~5 credits)

Response

{
  "meta": {
    "estimated_credits": 5,
    "auto_generated": true
  },
  "site": {
    "status": "active",
    "domain": "example.com",
    "uuid": "abc-123",
    "product_name": "My Product",
    "value_proposition": "We help teams...",
    "created_at": "2026-02-05T10:00:00Z",
    "customer_types": [],
    "customer_type_count": 0
  }
}

Example

curl -X POST https://botsee.io/api/v1/sites -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://example.com"}'

Archive site

DELETE /api/v1/sites/:uuid Auth

Archives a site. Returns 204 No Content on success.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Site UUID

Example

curl -X DELETE https://botsee.io/api/v1/sites/SITE_UUID -H "Authorization: Bearer $BOTSEE_API_KEY"

Customer Types

Customer types represent market segments for a site. Each customer type can have multiple personas.

List customer types

GET /api/v1/sites/:site_uuid/customer-types Auth

Lists all customer types for a site.

Parameters

Name	In	Type	Required	Description
`site_uuid`	path	string	required	Site UUID

Response

{
  "customer_types": [
    {
      "name": "Enterprise IT",
      "description": "Large company IT departments",
      "uuid": "ct-1",
      "created_at": "2026-02-05T10:00:00Z",
      "persona_count": 2
    }
  ]
}

Example

curl https://botsee.io/api/v1/sites/SITE_UUID/customer-types -H "Authorization: Bearer $BOTSEE_API_KEY"

Get customer type

GET /api/v1/customer-types/:uuid Auth

Returns a customer type with its personas.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Customer type UUID

Response

{
  "customer_type": {
    "name": "Enterprise IT",
    "description": "Large company IT departments",
    "uuid": "ct-1",
    "personas": [
      {
        "name": "CTO",
        "uuid": "p-1",
        "question_count": 5
      }
    ],
    "created_at": "2026-02-05T10:00:00Z",
    "persona_count": 2
  }
}

Example

curl https://botsee.io/api/v1/customer-types/CT_UUID -H "Authorization: Bearer $BOTSEE_API_KEY"

Create customer type

POST /api/v1/sites/:site_uuid/customer-types Auth

Creates a customer type manually. Free — billing follows LLM usage (tokens), not record creation.

Parameters

Name	In	Type	Required	Description
`site_uuid`	path	string	required	Site UUID

Request Body

Field	Type	Required	Description
`name`	string	required	Customer type name
`description`	string	optional	Description of this market segment

Response

{
  "customer_type": {
    "name": "Enterprise IT",
    "description": "Large company IT departments",
    "uuid": "ct-1",
    "created_at": "2026-02-05T10:00:00Z",
    "persona_count": 0
  }
}

Example

curl -X POST https://botsee.io/api/v1/sites/SITE_UUID/customer-types -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"name":"Enterprise IT","description":"Large company IT departments"}'

Generate customer types via LLM

POST /api/v1/sites/:site_uuid/customer-types/generate ~5 per type (estimated) Auth

Uses AI to generate customer types based on the site's product and value proposition. Estimated ~5 credits per generated type; the actual charge follows LLM token usage.

Parameters

Name	In	Type	Required	Description
`site_uuid`	path	string	required	Site UUID

Request Body

Field	Type	Required	Description
`count`	integer	optional (3)	Number of customer types to generate

Response

{
  "estimated_credits": 15,
  "customer_types": [
    {
      "name": "Enterprise IT Directors",
      "description": "IT leaders at large companies",
      "uuid": "ct-1",
      "created_at": "2026-02-05T10:00:00Z",
      "persona_count": 0
    }
  ]
}

Example

curl -X POST https://botsee.io/api/v1/sites/SITE_UUID/customer-types/generate -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"count":3}'

Update customer type

PUT /api/v1/customer-types/:uuid Auth

Updates a customer type. Only include fields you want to change.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Customer type UUID

Request Body

Field	Type	Required	Description
`name`	string	optional	Updated customer type name
`description`	string	optional	Updated description

Response

{
  "customer_type": {
    "name": "Updated Name",
    "description": "Updated description",
    "uuid": "ct-1",
    "created_at": "2026-02-05T10:00:00Z",
    "persona_count": 2
  }
}

Example

curl -X PUT https://botsee.io/api/v1/customer-types/CT_UUID -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"name":"New Name","description":"New description"}'

Archive customer type

DELETE /api/v1/customer-types/:uuid Auth

Archives a customer type. Returns 204 No Content on success.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Customer type UUID

Example

curl -X DELETE https://botsee.io/api/v1/customer-types/CT_UUID -H "Authorization: Bearer $BOTSEE_API_KEY"

Personas

Personas represent specific buyer profiles within a customer type. Each persona has questions that get asked to AI models during analysis.

List personas

GET /api/v1/customer-types/:customer_type_uuid/personas Auth

Lists all personas for a customer type.

Parameters

Name	In	Type	Required	Description
`customer_type_uuid`	path	string	required	Customer type UUID

Response

{
  "personas": [
    {
      "name": "CTO",
      "description": "Technical leader managing...",
      "uuid": "p-1",
      "question_count": 5,
      "created_at": "2026-02-05T10:00:00Z"
    }
  ]
}

Example

curl https://botsee.io/api/v1/customer-types/CT_UUID/personas -H "Authorization: Bearer $BOTSEE_API_KEY"

Get persona

GET /api/v1/personas/:uuid Auth

Returns a persona with its questions.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Persona UUID

Response

{
  "persona": {
    "name": "CTO",
    "description": "Technical leader managing...",
    "uuid": "p-1",
    "question_count": 5,
    "created_at": "2026-02-05T10:00:00Z",
    "questions": [
      {
        "priority": "high",
        "category": "problem_solving",
        "question": "What tools help with code review?",
        "uuid": "q-1",
        "is_active": true
      }
    ]
  }
}

Example

curl https://botsee.io/api/v1/personas/PERSONA_UUID -H "Authorization: Bearer $BOTSEE_API_KEY"

Create persona

POST /api/v1/customer-types/:customer_type_uuid/personas Auth

Creates a persona manually. Free — billing follows LLM usage (tokens), not record creation.

Parameters

Name	In	Type	Required	Description
`customer_type_uuid`	path	string	required	Customer type UUID

Request Body

Field	Type	Required	Description
`name`	string	required	Persona name (e.g. 'CTO')
`description`	string	required	Detailed persona description

Response

{
  "persona": {
    "name": "CTO",
    "description": "Technical leader managing...",
    "uuid": "p-1",
    "question_count": 0,
    "created_at": "2026-02-05T10:00:00Z"
  }
}

Example

curl -X POST https://botsee.io/api/v1/customer-types/CT_UUID/personas -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"name":"CTO","description":"Technical leader managing 50+ engineers"}'

Generate personas via LLM

POST /api/v1/customer-types/:customer_type_uuid/personas/generate ~5 per persona (estimated) Auth

Uses AI to generate personas based on the customer type. Estimated ~5 credits per persona; the actual charge follows LLM token usage. Optionally pass `prompt` to steer the LLM toward a specific persona within the customer segment (requires `count: 1`).

Parameters

Name	In	Type	Required	Description
`customer_type_uuid`	path	string	required	Customer type UUID

Request Body

Field	Type	Required	Description
`count`	integer	optional (3)	Number of personas to generate
`prompt`	string	optional	Free-text hint (max 2000 chars) that steers generation toward a specific persona. Only supported with count: 1. When omitted, the generator produces diverse personas across the customer segment.

Response

{
  "personas": [
    {
      "name": "CTO",
      "description": "Technical leader managing...",
      "uuid": "p-1",
      "question_count": 0,
      "created_at": "2026-02-05T10:00:00Z"
    }
  ],
  "estimated_credits": 15
}

Example

curl -X POST https://botsee.io/api/v1/customer-types/CT_UUID/personas/generate -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"count":1,"prompt":"VP of Engineering at a Series B fintech managing a 40-person platform team"}'

Update persona

PUT /api/v1/personas/:uuid Auth

Updates a persona. Only include fields you want to change.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Persona UUID

Request Body

Field	Type	Required	Description
`name`	string	optional	Updated persona name
`description`	string	optional	Updated persona description

Response

{
  "persona": {
    "name": "Updated Name",
    "description": "Updated persona description",
    "uuid": "p-1",
    "question_count": 5,
    "created_at": "2026-02-05T10:00:00Z"
  }
}

Example

curl -X PUT https://botsee.io/api/v1/personas/PERSONA_UUID -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"name":"New Name","description":"New description"}'

Archive persona

DELETE /api/v1/personas/:uuid Auth

Archives a persona. Returns 204 No Content on success.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Persona UUID

Example

curl -X DELETE https://botsee.io/api/v1/personas/PERSONA_UUID -H "Authorization: Bearer $BOTSEE_API_KEY"

Questions

Questions are what get asked to AI search engines during analysis. Each question belongs to a persona and can be manually created or AI-generated.

List questions

GET /api/v1/personas/:persona_uuid/questions Auth

Lists all questions for a persona.

Parameters

Name	In	Type	Required	Description
`persona_uuid`	path	string	required	Persona UUID

Response

{
  "questions": [
    {
      "priority": "high",
      "category": "problem_solving",
      "question": "What tools help with code review?",
      "uuid": "q-1",
      "is_active": true,
      "created_at": "2026-02-05T10:00:00Z"
    }
  ]
}

Example

curl https://botsee.io/api/v1/personas/PERSONA_UUID/questions -H "Authorization: Bearer $BOTSEE_API_KEY"

Create question

POST /api/v1/personas/:persona_uuid/questions Auth

Creates a question manually. Free operation.

Parameters

Name	In	Type	Required	Description
`persona_uuid`	path	string	required	Persona UUID

Request Body

Field	Type	Required	Description
`question`	string	required	The question text to ask AI models
`category`	string	optional (problem_solving)	Question category
`priority`	string	optional (medium)	Priority: low, medium, high

Response

{
  "question": {
    "priority": "medium",
    "category": "problem_solving",
    "question": "What tools help with code review?",
    "uuid": "q-1",
    "is_active": true,
    "created_at": "2026-02-05T10:00:00Z"
  }
}

Example

curl -X POST https://botsee.io/api/v1/personas/PERSONA_UUID/questions -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"question":"What tools help with code review?"}'

Generate questions via LLM

POST /api/v1/personas/:persona_uuid/questions/generate ~10 credits (estimated) Auth

Uses AI to generate questions based on the persona and site context. Estimated ~10 credits; the actual charge follows LLM token usage.

Parameters

Name	In	Type	Required	Description
`persona_uuid`	path	string	required	Persona UUID

Request Body

Field	Type	Required	Description
`count`	integer	optional (5)	Number of questions to generate

Response

{
  "estimated_credits": 10,
  "questions": [
    {
      "priority": "medium",
      "category": "problem_solving",
      "question": "What are the best AI-powered code review tools?",
      "uuid": "q-1",
      "is_active": true,
      "created_at": "2026-02-05T10:00:00Z"
    }
  ]
}

Example

curl -X POST https://botsee.io/api/v1/personas/PERSONA_UUID/questions/generate -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"count":5}'

Update question

PUT /api/v1/questions/:uuid Auth

Updates a question. Only include fields you want to change.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Question UUID

Request Body

Field	Type	Required	Description
`question`	string	optional	Updated question text
`category`	string	optional	Updated category
`priority`	string	optional	Updated priority
`is_active`	boolean	optional	Active/inactive toggle

Response

{
  "question": {
    "priority": "high",
    "category": "problem_solving",
    "question": "Updated question text?",
    "uuid": "q-1",
    "is_active": true,
    "created_at": "2026-02-05T10:00:00Z"
  }
}

Example

curl -X PUT https://botsee.io/api/v1/questions/Q_UUID -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"priority":"high","question":"Updated question?"}'

Delete question

DELETE /api/v1/questions/:uuid Auth

Deletes a question. Returns 204 No Content on success.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Question UUID

Example

curl -X DELETE https://botsee.io/api/v1/questions/Q_UUID -H "Authorization: Bearer $BOTSEE_API_KEY"

Get question results

GET /api/v1/questions/:uuid/results Auth

Returns analysis results for a specific question. Use the `fields` parameter to include additional data (keywords, competitors, sources, responses).

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Question UUID
`fields`	query	string	optional	Comma-separated fields: keywords, competitors, sources, responses. Default: keywords only.

Response

{
  "question": "What tools help with code review?",
  "keywords_by_model": {
    "claude": [
      "code review",
      "static analysis"
    ],
    "openai-search": [
      "code review",
      "pull request"
    ]
  }
}

Example

curl "https://botsee.io/api/v1/questions/Q_UUID/results?fields=keywords,competitors" -H "Authorization: Bearer $BOTSEE_API_KEY"

Analysis

Run analyses that query AI search engines with your questions and collect structured results including competitors, sources, and keywords.

Run analysis

POST /api/v1/analysis Preview the selected scope with dry_run (free); actual usage billed Auth

Includes persona context by default so answers reflect the buyer's needs: one sample per question/model, not an average. Set include_persona to false for a question-only benchmark. Generated personas use buyer language rather than explicit homepage product terminology. dry_run previews counts, known brand warnings, and a planning credit range for free (200, no jobs). Starting returns 202; poll GET /api/v1/analysis/:uuid. Actual usage and retries can exceed the estimate; it is not a spending cap.

Request Body

Field	Type	Required	Description
`site_uuid`	string	required	Site UUID to analyze
`scope`	string	optional (site)	Scope: 'site', 'customer_type', 'persona', or 'questions'
`target_uuids`	array	optional	Required for non-site scope. UUIDs of customer types, personas, or questions.
`models`	array	optional (openai-searchclaudegemini)	AI models: openai-search (ChatGPT with web search), openai (ChatGPT without web search), claude, perplexity, gemini, grok
`include_persona`	boolean	optional (true)	Include persona context with each question; false runs a question-only benchmark
`dry_run`	boolean	optional (false)	Free preview without creating a run, jobs, or charges

Response

{
  "warnings": [
    {
      "code": "single_sample",
      "message": "One answer per question and model; results are a snapshot, not an average or measured range."
    }
  ],
  "measurement": {
    "include_persona": true,
    "samples_per_question_model": 1
  },
  "analysis": {
    "scope": "site",
    "status": "running",
    "started_at": "2026-02-05T10:00:00Z",
    "uuid": "a-1",
    "completed_at": null,
    "response_count": 0,
    "models": [
      "openai-search",
      "claude",
      "gemini"
    ],
    "site_uuid": "s-1",
    "credits_used": 0,
    "recommendations_generated_at": null,
    "recommendations": []
  },
  "estimated_credit_range": {
    "max": 100,
    "min": 63
  },
  "estimated_credits": 100
}

Example

curl -X POST https://botsee.io/api/v1/analysis -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"site_uuid":"SITE_UUID","scope":"site","models":["openai-search","claude","gemini"]}'

List analyses

GET /api/v1/sites/:site_uuid/analysis Auth

Lists analysis runs for a site with optional filters.

Parameters

Name	In	Type	Required	Description
`site_uuid`	path	string	required	Site UUID
`limit`	query	integer	optional (20)	Max results
`cursor`	query	string	optional	Pagination cursor
`persona_uuid`	query	string	optional	Filter by persona
`model`	query	string	optional	Filter by model
`from`	query	string	optional	Start date (ISO 8601)
`to`	query	string	optional	End date (ISO 8601)

Response

{
  "cursor": null,
  "analyses": [
    {
      "scope": "site",
      "status": "completed",
      "started_at": "2026-02-05T10:00:00Z",
      "uuid": "a-1",
      "completed_at": "2026-02-05T10:05:00Z",
      "response_count": 5,
      "models": [
        "openai-search"
      ],
      "site_uuid": "s-1",
      "credits_used": 15,
      "recommendations_generated_at": null,
      "recommendations": []
    }
  ]
}

Example

curl "https://botsee.io/api/v1/sites/SITE_UUID/analysis?limit=10" -H "Authorization: Bearer $BOTSEE_API_KEY"

Get analysis status

GET /api/v1/analysis/:uuid Auth

Returns analysis details including status. Poll this endpoint until status is 'completed' or 'failed'.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Analysis UUID

Response

{
  "analysis": {
    "scope": "site",
    "status": "completed",
    "started_at": "2026-02-05T10:00:00Z",
    "uuid": "a-1",
    "completed_at": "2026-02-05T10:05:00Z",
    "question_count": 5,
    "response_count": 10,
    "models": [
      "openai-search",
      "claude"
    ],
    "target_uuids": null,
    "site_uuid": "s-1",
    "credits_used": 30,
    "error_count": 0,
    "recommendations_generated_at": null,
    "recommendations": []
  }
}

Example

curl https://botsee.io/api/v1/analysis/ANALYSIS_UUID -H "Authorization: Bearer $BOTSEE_API_KEY"

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Analysis UUID

Response

{
  "responses": [
    {
      "status": "success",
      "sources": [
        {
          "title": "Reviews",
          "url": "https://example.com/reviews"
        }
      ],
      "question": "What tools help with code review?",
      "error_message": null,
      "uuid": "r-1",
      "provider": "openai-search",
      "competitors": [
        {
          "url": "https://example.com",
          "rank": 2,
          "company_name": "Example Product",
          "is_own_company": true
        }
      ],
      "question_uuid": "q-1",
      "mentioned": true,
      "created_at": "2026-02-05T10:02:00Z",
      "model": "openai-search",
      "response_text": "There are several excellent code review tools...",
      "search_terms": [
        "code review",
        "pull request tools"
      ]
    }
  ]
}

Example

curl https://botsee.io/api/v1/analysis/ANALYSIS_UUID/responses -H "Authorization: Bearer $BOTSEE_API_KEY"

Get cited sources

GET /api/v1/analysis/:uuid/sources Auth

Returns aggregated sources cited across all responses, with own_company_mentioned and is_own_domain flags. Source opportunities exclude owned domains and subdomains.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Analysis UUID

Response

{
  "sources": [
    {
      "title": "Code Review Guide",
      "url": "https://example.com/review",
      "mention_count": 3,
      "own_company_mentioned": true
    }
  ],
  "total_unique": 15
}

Example

curl https://botsee.io/api/v1/analysis/ANALYSIS_UUID/sources -H "Authorization: Bearer $BOTSEE_API_KEY"

Get competitors mentioned

GET /api/v1/analysis/:uuid/competitors Auth

Returns competitors mentioned in responses, grouped by customer type. Each competitor includes appearance percentage (% of responses mentioning them), mentions count, average ranking, and confidence scores.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Analysis UUID

Response

{
  "by_customer_type": [
    {
      "total_responses": 10,
      "competitors": [
        {
          "name": "Competitor A",
          "url": "https://competitor-a.com",
          "mentions": 8,
          "appearance_percentage": 80.0,
          "avg_rank": 2.5,
          "unique_responses": 8,
          "avg_confidence": 0.85,
          "best_rank": 1
        }
      ],
      "total_unique_competitors": 5,
      "customer_type_name": "Enterprise IT Directors",
      "customer_type_uuid": "abc-123-def"
    }
  ],
  "overall_summary": {
    "own_company_mentioned": true,
    "total_responses_analyzed": 50,
    "total_unique_competitors": 15
  }
}

Example

curl https://botsee.io/api/v1/analysis/ANALYSIS_UUID/competitors -H "Authorization: Bearer $BOTSEE_API_KEY"

Get keywords

GET /api/v1/analysis/:uuid/keywords Auth

Returns aggregated keywords/search terms from all responses.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Analysis UUID

Response

{
  "keywords": [
    {
      "count": 8,
      "term": "code review",
      "models": [
        "openai-search",
        "claude",
        "perplexity"
      ]
    }
  ]
}

Example

curl https://botsee.io/api/v1/analysis/ANALYSIS_UUID/keywords -H "Authorization: Bearer $BOTSEE_API_KEY"

Get keyword opportunities

GET /api/v1/analysis/:uuid/keyword_opportunities Auth

Returns questions where your brand's mention rate is below a threshold. Use this to discover which queries you should target with content. Results include a per-provider breakdown with the search keywords used and your brand's rank position.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Analysis UUID
`threshold`	query	number	optional (1.0)	Mention rate threshold (0.0–1.0). Questions where mention_rate < threshold are returned. Default 1.0 returns any question where brand was missed at least once.
`rank_threshold`	query	integer	optional	Also flag questions where brand appeared at rank worse than this value, even if mention rate meets the threshold.

Response

{
  "opportunities": [
    {
      "question": "What tools help with AI visibility?",
      "total_responses": 3,
      "persona": "Marketing Director",
      "question_uuid": "Q_UUID",
      "persona_uuid": "P_UUID",
      "by_model": [
        {
          "rank": null,
          "provider": "openai-search",
          "mentioned": false,
          "search_keywords": [
            "ai search visibility",
            "brand monitoring"
          ]
        },
        {
          "rank": null,
          "provider": "claude",
          "mentioned": false,
          "search_keywords": [
            "ai seo tools"
          ]
        },
        {
          "rank": 4,
          "provider": "perplexity",
          "mentioned": true,
          "search_keywords": [
            "ai visibility tracking"
          ]
        }
      ],
      "mentioned_count": 0
    }
  ]
}

Example

curl "https://botsee.io/api/v1/analysis/ANALYSIS_UUID/keyword_opportunities?threshold=0.8" -H "Authorization: Bearer $BOTSEE_API_KEY"

Get source opportunities

GET /api/v1/analysis/:uuid/source_opportunities Auth

Returns sources that AI cited in responses where your brand was NOT mentioned. These are high-value targets for outreach or content placement — getting coverage on these sources may improve your AI visibility.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Analysis UUID

Response

{
  "sources": [
    {
      "title": "Best AI Tools 2025",
      "url": "https://techcrunch.com/ai-tools",
      "mentions": 5
    },
    {
      "title": "AI SEO Software",
      "url": "https://g2.com/categories/ai-seo",
      "mentions": 3
    }
  ],
  "total_unique": 2
}

Example

curl https://botsee.io/api/v1/analysis/ANALYSIS_UUID/source_opportunities -H "Authorization: Bearer $BOTSEE_API_KEY"

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Analysis UUID

Response

{
  "homepage": {
    "title": "Example | Team collaboration",
    "url": "https://example.com"
  },
  "missing_terms": [
    {
      "term": "share voice",
      "ai_search_count": 12,
      "example_queries": [
        "share of voice tracking tools",
        "ai share of voice"
      ]
    }
  ],
  "present_terms_count": 97,
  "terms_checked": 142
}

Example

curl https://botsee.io/api/v1/analysis/ANALYSIS_UUID/homepage_gaps -H "Authorization: Bearer $BOTSEE_API_KEY"

Generate recommendations

POST /api/v1/analysis/:uuid/recommendations token-based (first call only) Auth

Generates actionable recommendations from the analysis (cached after first call). Costs credits based on LLM token usage on the first call; subsequent calls return the cached result at no cost.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Analysis UUID

Response

{
  "cached": false,
  "credits_used": 12,
  "recommendations": [
    {
      "priority": "high",
      "action": "Create a comparison guide: 'CRM vs Spreadsheets for Remote Teams'",
      "reasoning": "You have 0% visibility for these queries across all models.",
      "target_keywords": [
        "best CRM for remote teams"
      ]
    },
    {
      "priority": "medium",
      "action": "Pitch TechCrunch on AI-native CRM features",
      "reasoning": "These pages cited competitors but not your brand.",
      "target_urls": [
        "https://techcrunch.com/2025/01/best-crm-tools"
      ]
    }
  ],
  "generated_at": "2026-02-05T10:06:00Z"
}

Example

curl -X POST https://botsee.io/api/v1/analysis/ANALYSIS_UUID/recommendations -H "Authorization: Bearer $BOTSEE_API_KEY"

Content Generation

Generate blog posts from analysis results.

Generate blog post

POST /api/v1/analysis/:analysis_uuid/content ~15 credits (estimated) Auth

Generates a blog post from analysis results for a specific question. Estimated ~15 credits; the actual charge follows LLM token usage.

Parameters

Name	In	Type	Required	Description
`analysis_uuid`	path	string	required	Analysis UUID

Request Body

Field	Type	Required	Description
`question_uuid`	string	required	Question UUID to base the post on
`provider`	string	optional (gemini)	LLM provider: 'gemini' or 'claude'
`keywords`	array	optional	Custom keywords to incorporate

Response

{
  "tokens": {
    "input": 2500,
    "output": 1800,
    "total": 4300
  },
  "content": "# Best Code Review Tools for 2026\n\nIn the fast-evolving world of software development...",
  "provider": "gemini",
  "credits_used": 15,
  "model": "gemini-3.8-flash"
}

Example

curl -X POST https://botsee.io/api/v1/analysis/ANALYSIS_UUID/content -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"question_uuid":"Q_UUID","provider":"gemini"}'

Usage & Credits

Monitor credit balance, transaction history, and usage breakdown by API key.

Get usage summary

GET /api/v1/usage Auth

Returns credit balance, auto-charge settings, and paginated transaction history.

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	optional (50)	Max transactions to return
`cursor`	query	string	optional	Pagination cursor
`from`	query	string	optional	Start date (ISO 8601)
`to`	query	string	optional	End date (ISO 8601)

Response

{
  "balance": 450,
  "cursor": null,
  "transactions": [
    {
      "id": 1,
      "type": "deduction",
      "description": "Analysis run",
      "amount": -15,
      "resource_id": "a-1",
      "resource_type": "analysis",
      "balance_after": 450,
      "api_key_id": 1,
      "created_at": "2026-02-05T10:05:00Z"
    }
  ],
  "monthly_spend_limit_cents": 10000,
  "low_balance_threshold": 500,
  "current_month_spend_cents": 5000,
  "max_monthly_spend_cents": 10000
}

Example

curl https://botsee.io/api/v1/usage -H "Authorization: Bearer $BOTSEE_API_KEY"

Get usage by API key

GET /api/v1/usage/by-key Auth

Returns credit usage breakdown per API key.

Parameters

Name	In	Type	Required	Description
`from`	query	string	optional	Start date (ISO 8601)
`to`	query	string	optional	End date (ISO 8601)

Response

{
  "usage_by_key": [
    {
      "api_key_id": 1,
      "api_key_name": "Production Key",
      "api_key_prefix": "bts_live_abc1",
      "total_credits_used": 250,
      "analysis_count": 5,
      "generation_count": 12
    }
  ]
}

Example

curl https://botsee.io/api/v1/usage/by-key -H "Authorization: Bearer $BOTSEE_API_KEY"

Get usage by site

GET /api/v1/usage/by-site Auth

Returns credit usage grouped by site: per-site totals plus a per-category breakdown.

Parameters

Name	In	Type	Required	Description
`from`	query	string	optional	Start date (ISO 8601)
`to`	query	string	optional	End date (ISO 8601)
`site_uuid`	query	string	optional	Limit to a single site (404 if it does not belong to the org)

Response

{
  "from": "2026-02-01",
  "to": "2026-02-28",
  "sites": [
    {
      "name": "Example",
      "domain": "example.com",
      "site_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "total_credits": 159,
      "breakdown": [
        {
          "category": "analysis",
          "credits": 153
        },
        {
          "category": "content_generation",
          "credits": 6
        }
      ]
    }
  ]
}

Example

curl https://botsee.io/api/v1/usage/by-site -H "Authorization: Bearer $BOTSEE_API_KEY"

Get usage line items

GET /api/v1/usage/line-items Auth

Lists individual paid operations (line items), newest first. One row per site, category, operation, and resource.

Parameters

Name	In	Type	Required	Description
`from`	query	string	optional	Start date (ISO 8601)
`to`	query	string	optional	End date (ISO 8601)
`site_uuid`	query	string	optional	Limit to a single site (404 if it does not belong to the org)
`category`	query	string	optional	Limit to one operation category (e.g. analysis, setup, content_generation)
`limit`	query	integer	optional (200)	Max line items to return

Response

{
  "from": "2026-02-01",
  "to": "2026-02-28",
  "line_items": [
    {
      "name": "Example",
      "domain": "example.com",
      "operation": "seo_question",
      "category": "analysis",
      "credits": 153,
      "site_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "last_charged_at": "2026-02-24T05:55:00Z"
    }
  ]
}

Example

curl https://botsee.io/api/v1/usage/line-items -H "Authorization: Bearer $BOTSEE_API_KEY"

Rate Limits

Every BotSee API request is rate-limited per API key (or per client IP for unauthenticated requests). The current ceiling is 600 requests per minute (10/sec).

Limit

600 requests per minute per API key (or per client IP for
unauthenticated requests). The window slides; there is no daily cap
beyond this rolling per-minute ceiling.

Response Headers

Every response (success or error) includes:

Header	Meaning
`x-ratelimit-limit`	Maximum requests allowed in the window (`600`).
`x-ratelimit-remaining`	Requests remaining in the current window.
`x-ratelimit-reset`	Unix timestamp (seconds) when the window resets.
`retry-after`	Seconds to wait before retrying. Returned only on 429 responses.

When you hit the limit

The server returns 429 Too Many Requests with this body:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Limit: 600 per minute."
  }
}

Recommended back-off for agents

1. Honour retry-after when present — wait that many seconds before retrying. 2. If retry-after is absent on a transient error, use exponential back-off starting at 1s, doubling each retry, capped at 60s. 3. Watch x-ratelimit-remaining on every response. When it drops below a small floor (e.g. 50), pause non-essential work until the window resets. 4. For predictable budgets, call GET /api/v1/rate-limits to read state without consuming a slot beyond the call itself.

Bucket key

Authenticated requests bucket by API key (the SHA-256 prefix of the bearer token). Unauthenticated requests bucket by client IP. The rate-limit plug runs before authentication so brute-force attempts are throttled regardless of key validity.

Get rate-limit budget

GET /api/v1/rate-limits Auth

Returns the caller's current rate-limit state without consuming additional budget. Useful for agents that want to back off proactively before hitting 429.

Response

{
  "count": 1,
  "limit": 600,
  "remaining": 599,
  "reset_at": "2026-04-29T12:01:00Z",
  "window_seconds": 60
}

Example

curl https://botsee.io/api/v1/rate-limits -H "Authorization: Bearer $BOTSEE_API_KEY"

Webhooks

Delivery Envelope

Every webhook POST carries a JSON body shaped like:

{
  "event": "analysis.completed",
  "timestamp": "2026-04-29T12:00:00Z",
  "data": { /* event-specific payload */ }
}

And these headers:

Header	Meaning
`x-botsee-signature`	`sha256=<hex>` HMAC of `"<x-botsee-timestamp>.<json_body>"` using your webhook secret.
`x-botsee-timestamp`	Unix timestamp (seconds) when the server signed the payload.
`user-agent`	`BotSee-Webhook/1.0`.

Always reject deliveries with timestamps older than ~5 minutes to defeat replay.

Signature Verification

Node

const crypto = require('crypto');

function verify(rawBody, signatureHeader, timestamp, secret) {
  const sig = signatureHeader.replace(/^sha256=/, '');
  const expected = crypto
    .createHmac('sha256', secret)
    .update(\`${timestamp}.${rawBody}\`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(sig, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Python

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, timestamp: str, secret: str) -> bool:
    sig = signature_header.removeprefix("sha256=")
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{raw_body.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(sig, expected)

Elixir

def verify(raw_body, "sha256=" <> sig, timestamp, secret) do
  expected =
    :crypto.mac(:hmac, :sha256, secret, "#{timestamp}.#{raw_body}")
    |> Base.encode16(case: :lower)

  Plug.Crypto.secure_compare(sig, expected)
end

Events

The full machine-readable catalog (with JSON Schemas per event) is at GET /api/v1/webhooks/events.

Event	When it fires
`analysis.completed`	Analysis run finished successfully.
`analysis.failed`	Analysis run failed.
`webhook.test`	Test-only event, fired by `POST /api/v1/webhooks/:uuid/test`. Safe to subscribe to without expecting traffic.

Sample payload — `analysis.completed`

{
  "event": "analysis.completed",
  "timestamp": "2026-04-29T12:00:00Z",
  "data": {
    "analysis_uuid": "a-1",
    "site_uuid": "s-1",
    "scope": "site",
    "status": "completed",
    "models": ["openai-search", "claude"],
    "credits_used": 30,
    "response_count": 10,
    "started_at": "2026-04-29T11:55:00Z",
    "completed_at": "2026-04-29T12:00:00Z"
  }
}

Sample payload — `analysis.failed`

{
  "event": "analysis.failed",
  "timestamp": "2026-04-29T12:00:00Z",
  "data": {
    "analysis_uuid": "a-1",
    "site_uuid": "s-1",
    "status": "failed",
    "error": "openai rate limit exceeded after 3 retries",
    "started_at": "2026-04-29T11:55:00Z",
    "failed_at": "2026-04-29T12:00:00Z"
  }
}

Retry Policy & Auto-Disable

3 delivery attempts with exponential back-off (~5s, ~30s, ~2min).
Webhook is auto-disabled after 10 consecutive failures (status flips
to disabled); no further deliveries are attempted.
Re-enable by deleting and re-creating the webhook.
Each successful delivery resets failure_count to 0 and updates
last_triggered_at.

Event Filtering

Event filtering is exact-match: subscribers only receive the event types they explicitly registered for. Adding a new event type to the catalog does not change traffic for existing webhooks.

List webhook event catalog

GET /api/v1/webhooks/events Auth

Returns the catalog of event types this API can emit, with JSON Schemas per event. Use this to self-discover available events programmatically without parsing the full OpenAPI doc.

Response

{
  "events": [
    {
      "description": "Fires when an analysis run finishes successfully.",
      "event": "analysis.completed",
      "payload_schema": {
        "type": "object",
        "properties": {}
      }
    }
  ]
}

Example

curl https://botsee.io/api/v1/webhooks/events -H "Authorization: Bearer $BOTSEE_API_KEY"

List webhooks

GET /api/v1/webhooks Auth

Lists all registered webhooks for the organization.

Response

{
  "webhooks": [
    {
      "status": "active",
      "events": [
        "analysis.completed",
        "analysis.failed"
      ],
      "url": "https://example.com/webhook",
      "uuid": "wh-1",
      "created_at": "2026-02-05T10:00:00Z",
      "failure_count": 0,
      "last_triggered_at": null
    }
  ]
}

Example

curl https://botsee.io/api/v1/webhooks -H "Authorization: Bearer $BOTSEE_API_KEY"

Create webhook

POST /api/v1/webhooks Auth

Registers a webhook URL. Returns the webhook with its signing secret (shown only once).

Request Body

Field	Type	Required	Description
`url`	string	required	HTTPS URL to receive webhook payloads
`events`	array	optional (analysis.completedanalysis.failed)	Events to subscribe to. Call GET /api/v1/webhooks/events for the canonical catalog of currently-emitted event types and their payload schemas.

Response

{
  "webhook": {
    "status": "active",
    "events": [
      "analysis.completed"
    ],
    "secret": "whsec_abc123...",
    "url": "https://example.com/webhook",
    "uuid": "wh-1",
    "created_at": "2026-02-05T10:00:00Z",
    "failure_count": 0,
    "last_triggered_at": null
  }
}

Example

curl -X POST https://botsee.io/api/v1/webhooks -H "Authorization: Bearer $BOTSEE_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://example.com/webhook","events":["analysis.completed"]}'

Send synthetic test event

POST /api/v1/webhooks/:uuid/test Auth

Fires a synthetic webhook.test event to the registered URL via the standard delivery worker. Useful for end-to-end testing of signature verification on the subscriber side. Returns 202 with the enqueued Oban job id.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Webhook UUID

Response

{
  "event": "webhook.test",
  "job_id": 12345
}

Example

curl -X POST https://botsee.io/api/v1/webhooks/WH_UUID/test -H "Authorization: Bearer $BOTSEE_API_KEY"

Delete webhook

DELETE /api/v1/webhooks/:uuid Auth

Deletes a webhook. Returns 204 No Content on success.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	required	Webhook UUID

Example

curl -X DELETE https://botsee.io/api/v1/webhooks/WH_UUID -H "Authorization: Bearer $BOTSEE_API_KEY"

Error Handling

All errors follow a consistent JSON format.

Error Response Format

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description"
  }
}

For validation errors, a details field contains per-field errors:

{
  "error": {
    "code": "validation_error",
    "details": {
      "domain": ["can't be blank"],
      "product_name": ["is too short"]
    }
  }
}

Pagination

List endpoints use cursor-based pagination. Pass the cursor from the response to get the next page:

# First page
curl "https://botsee.io/api/v1/sites?limit=10" -H "Authorization: Bearer $BOTSEE_API_KEY"

# Next page (use cursor from response)
curl "https://botsee.io/api/v1/sites?limit=10&cursor=CURSOR_VALUE" -H "Authorization: Bearer $BOTSEE_API_KEY"

When cursor is null in the response, there are no more pages.