B
BotSee API

Quick Start (Claude Code Skill)

Install the BotSee skill for the fastest setup. Works with Claude Code and other AI assistants.

Paste this into your AI Prompt

Install the BotSee Skill at github.com/RivalSee/botsee-skill.
Then run /botsee signup.

If you cannot install the skill, use the BotSee API (botsee.io/docs)
to analyze how AI search engines see [YOUR_PRODUCT]. Set up monitoring
across ChatGPT, Claude, Perplexity, and Gemini. Track competitors,
cited sources, and keywords. Report back with AI visibility.

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 (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 Skill from github.com/RivalSee/botsee-skill. 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 skill handles authentication, API calls, and result formatting automatically.

All Skill Commands

Complete reference for all BotSee skill commands.

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

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>

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"

Signup

Agent-initiated signup flows: credit card, USDC, and x402 challenge.

Signup Credit Card

POST /api/v1/signup

Creates a credit-card signup token. USDC signups must use `/api/v1/signup/usdc`.

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

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

Create USDC signup token

POST /api/v1/signup/usdc

Creates a USDC signup token. Use `no_email: true` for autonomous agent flows (no setup_url returned).

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]"}'

Sign up via x402 challenge

POST /api/v1/signup/:token/pay-usdc

Call without `payment` header to get a 402 challenge and `payment-required` details. Use Pinch or Coinbase CDP Agentic Wallet to generate the payment header and retry.

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": "USDC",
        "version": "2"
      },
      "maxTimeoutSeconds": 300,
      "network": "eip155:8453",
      "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "scheme": "exact"
    }
  ],
  "amount_cents": 250,
  "payment_requirements": [
    {
      "amount": "2500000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USDC",
        "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}'

Check signup status

GET /api/v1/signup/:token/status

Polls the status of a signup token. Returns 'pending', 'completed', or 'expired'.

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

USDC Top-Ups

Add credits with BASE USDC using x402 challenge flow.

Agent Wallet Options for x402

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": "USDC",
        "version": "2"
      },
      "maxTimeoutSeconds": 300,
      "network": "eip155:8453",
      "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "scheme": "exact"
    }
  ],
  "amount_cents": 250,
  "payment_requirements": [
    {
      "amount": "2500000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USDC",
        "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}'

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",
    "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"

Create site

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

Creates a new site. Auto-generates product_name and value_proposition from URL if not provided (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, costs 5 credits)
value_proposition string optional Value proposition (auto-generated from URL if not provided, costs 5 credits)

Response

{
  "meta": {
    "credits_used": 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 5 credits Auth

Creates a customer type manually. Costs 5 credits.

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 Auth

Uses AI to generate customer types based on the site's product and value proposition. Costs 5 credits per generated type.

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

{
  "credits_used": 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 5 credits Auth

Creates a persona manually. Costs 5 credits.

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 Auth

Uses AI to generate personas based on the customer type. Costs 5 credits per persona.

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

Response

{
  "personas": [
    {
      "name": "CTO",
      "description": "Technical leader managing...",
      "uuid": "p-1",
      "question_count": 0,
      "created_at": "2026-02-05T10:00:00Z"
    }
  ],
  "credits_used": 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":3}'

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 Auth

Uses AI to generate questions based on the persona and site context. Costs 10 credits flat.

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

{
  "credits_used": 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": [
      "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 5 per question per model Auth

Starts an analysis run. This is asynchronous - poll GET /api/v1/analysis/:uuid for status. Returns 202 Accepted.

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 (openaiclaudeperplexity) AI models: openai, claude, perplexity, gemini, grok

Response

{
  "analysis": {
    "scope": "site",
    "status": "running",
    "started_at": "2026-02-05T10:00:00Z",
    "uuid": "a-1",
    "completed_at": null,
    "response_count": 0,
    "models": [
      "openai",
      "claude",
      "perplexity"
    ],
    "site_uuid": "s-1",
    "credits_used": 0
  },
  "estimated_credits": 45
}

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","claude","perplexity"]}'

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"
      ],
      "site_uuid": "s-1",
      "credits_used": 15
    }
  ]
}

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",
      "claude"
    ],
    "target_uuids": null,
    "site_uuid": "s-1",
    "credits_used": 30,
    "error_count": 0
  }
}

Example

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

Get raw responses

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

Returns raw AI model responses for the analysis.

Parameters

Name In Type Required Description
uuid path string required Analysis UUID

Response

{
  "responses": [
    {
      "question": "What tools help with code review?",
      "uuid": "r-1",
      "model": "openai",
      "created_at": "2026-02-05T10:02:00Z",
      "mentioned": true,
      "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 flag.

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,
          "avg_rank": 2.5,
          "unique_responses": 8,
          "appearance_percentage": 80.0,
          "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",
        "claude",
        "perplexity"
      ]
    }
  ]
}

Example

curl https://botsee.io/api/v1/analysis/ANALYSIS_UUID/keywords -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 Auth

Generates a blog post from analysis results for a specific question. Costs 15 credits.

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-2.0-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"

Webhooks

Register webhook URLs to receive notifications when events occur (e.g., analysis completed).

Webhook Signature Verification

All webhook payloads include two headers for verification:

  • x-botsee-signature: HMAC-SHA256 signature of the payload body
  • x-botsee-timestamp: Unix timestamp of when the webhook was sent

To verify:

import hmac, hashlib

def verify_webhook(payload_body, signature, timestamp, secret):
    message = f"{timestamp}.{payload_body}"
    expected = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)
const crypto = require('crypto');

function verifyWebhook(body, signature, timestamp, secret) {
  const message = `${timestamp}.${body}`;
  const expected = crypto.createHmac('sha256', secret).update(message).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Webhook Events

EventDescription
analysis.completedAnalysis run finished successfully
analysis.failedAnalysis run failed
credits.lowCredit balance dropped below threshold
signup.completedAgent signup flow completed

User-Agent

Webhook requests are sent with User-Agent: BotSee-Webhook/1.0

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: analysis.completed, analysis.failed, credits.low, signup.completed

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"]}'

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.