{"info":{"version":"1.0.0","description":"Monitor how AI search engines see your products. BotSee queries multiple AI models (OpenAI, Claude, Perplexity, Gemini, Grok) with your target questions and analyzes which competitors, sources, and keywords appear in responses.","title":"BotSee API","contact":{"email":"support@botsee.io"},"termsOfService":"https://botsee.io/terms"},"components":{"securitySchemes":{"BearerAuth":{"scheme":"bearer","type":"http","description":"API key starting with 'bts_live_'"}}},"paths":{"/api/v1/questions/:uuid":{"delete":{"description":"Deletes a question. Returns 204 No Content on success.","parameters":[{"in":"path","name":"uuid","description":"Question UUID","required":true,"schema":{"type":"string"}}],"summary":"Delete question","tags":["Questions"],"security":[{"BearerAuth":[]}],"operationId":"delete-question"},"put":{"description":"Updates a question. Only include fields you want to change.","parameters":[{"in":"path","name":"uuid","description":"Question UUID","required":true,"schema":{"type":"string"}}],"summary":"Update question","tags":["Questions"],"security":[{"BearerAuth":[]}],"operationId":"update-question","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/customer-types/:uuid":{"delete":{"description":"Archives a customer type. Returns 204 No Content on success.","parameters":[{"in":"path","name":"uuid","description":"Customer type UUID","required":true,"schema":{"type":"string"}}],"summary":"Archive customer type","tags":["Customer Types"],"security":[{"BearerAuth":[]}],"operationId":"delete-customer-type"},"get":{"description":"Returns a customer type with its personas.","parameters":[{"in":"path","name":"uuid","description":"Customer type UUID","required":true,"schema":{"type":"string"}}],"summary":"Get customer type","tags":["Customer Types"],"security":[{"BearerAuth":[]}],"operationId":"get-customer-type"},"put":{"description":"Updates a customer type. Only include fields you want to change.","parameters":[{"in":"path","name":"uuid","description":"Customer type UUID","required":true,"schema":{"type":"string"}}],"summary":"Update customer type","tags":["Customer Types"],"security":[{"BearerAuth":[]}],"operationId":"update-customer-type","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/analysis/:analysis_uuid/content":{"post":{"description":"Generates a blog post from analysis results for a specific question. Costs 15 credits.","parameters":[{"in":"path","name":"analysis_uuid","description":"Analysis UUID","required":true,"schema":{"type":"string"}}],"summary":"Generate blog post","tags":["Content"],"security":[{"BearerAuth":[]}],"operationId":"generate-content","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/billing/topups/usdc":{"post":{"description":"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":[{"in":"header","name":"authorization","description":"Required on final paid retry when using Bearer auth. Format: Bearer bts_live_...","required":false,"schema":{"type":"string"}},{"in":"header","name":"x-api-key","description":"Alternative to Authorization on final paid retry","required":false,"schema":{"type":"string"}},{"in":"query","name":"api_key","description":"Alternative auth for facilitator-driven final paid retry","required":false,"schema":{"type":"string"}},{"in":"header","name":"payment","description":"Base64-encoded payment payload. Omit for discovery challenge; include on final paid retry.","required":false,"schema":{"type":"string"}},{"in":"header","name":"payment-signature","description":"Alias for `payment` header","required":false,"schema":{"type":"string"}}],"summary":"Top up via x402 challenge","tags":["General"],"security":[],"operationId":"topoff-via-x402","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/signup/:token/status":{"get":{"description":"Polls the status of a signup token. Returns 'pending', 'completed', or 'expired'.","parameters":[{"in":"path","name":"token","description":"Signup token","required":true,"schema":{"type":"string"}}],"summary":"Check signup status","tags":["Signup"],"security":[],"operationId":"signup-status"}},"/api/v1/webhooks":{"get":{"description":"Lists all registered webhooks for the organization.","summary":"List webhooks","tags":["Webhooks"],"security":[{"BearerAuth":[]}],"operationId":"list-webhooks"},"post":{"description":"Registers a webhook URL. Returns the webhook with its signing secret (shown only once).","summary":"Create webhook","tags":["Webhooks"],"security":[{"BearerAuth":[]}],"operationId":"create-webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/sites/:site_uuid/analysis":{"get":{"description":"Lists analysis runs for a site with optional filters.","parameters":[{"in":"path","name":"site_uuid","description":"Site UUID","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","description":"Max results","required":false,"schema":{"type":"integer"}},{"in":"query","name":"cursor","description":"Pagination cursor","required":false,"schema":{"type":"string"}},{"in":"query","name":"persona_uuid","description":"Filter by persona","required":false,"schema":{"type":"string"}},{"in":"query","name":"model","description":"Filter by model","required":false,"schema":{"type":"string"}},{"in":"query","name":"from","description":"Start date (ISO 8601)","required":false,"schema":{"type":"string"}},{"in":"query","name":"to","description":"End date (ISO 8601)","required":false,"schema":{"type":"string"}}],"summary":"List analyses","tags":["General"],"security":[{"BearerAuth":[]}],"operationId":"list-analyses"}},"/api/v1/analysis/:uuid/sources":{"get":{"description":"Returns aggregated sources cited across all responses, with own_company_mentioned flag.","parameters":[{"in":"path","name":"uuid","description":"Analysis UUID","required":true,"schema":{"type":"string"}}],"summary":"Get cited sources","tags":["Analysis"],"security":[{"BearerAuth":[]}],"operationId":"analysis-sources"}},"/api/v1/customer-types/:customer_type_uuid/personas":{"get":{"description":"Lists all personas for a customer type.","parameters":[{"in":"path","name":"customer_type_uuid","description":"Customer type UUID","required":true,"schema":{"type":"string"}}],"summary":"List personas","tags":["Personas"],"security":[{"BearerAuth":[]}],"operationId":"list-personas"},"post":{"description":"Creates a persona manually. Costs 5 credits.","parameters":[{"in":"path","name":"customer_type_uuid","description":"Customer type UUID","required":true,"schema":{"type":"string"}}],"summary":"Create persona","tags":["Personas"],"security":[{"BearerAuth":[]}],"operationId":"create-persona","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/analysis/:uuid/source_opportunities":{"get":{"description":"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":[{"in":"path","name":"uuid","description":"Analysis UUID","required":true,"schema":{"type":"string"}}],"summary":"Get source opportunities","tags":["Analysis"],"security":[{"BearerAuth":[]}],"operationId":"analysis-source-opportunities"}},"/api/v1/webhooks/:uuid":{"delete":{"description":"Deletes a webhook. Returns 204 No Content on success.","parameters":[{"in":"path","name":"uuid","description":"Webhook UUID","required":true,"schema":{"type":"string"}}],"summary":"Delete webhook","tags":["Webhooks"],"security":[{"BearerAuth":[]}],"operationId":"delete-webhook"}},"/api/v1/sites/:uuid":{"delete":{"description":"Archives a site. Returns 204 No Content on success.","parameters":[{"in":"path","name":"uuid","description":"Site UUID","required":true,"schema":{"type":"string"}}],"summary":"Archive site","tags":["Sites"],"security":[{"BearerAuth":[]}],"operationId":"delete-site"},"get":{"description":"Returns a site with its customer types and persona counts.","parameters":[{"in":"path","name":"uuid","description":"Site UUID","required":true,"schema":{"type":"string"}}],"summary":"Get site","tags":["Sites"],"security":[{"BearerAuth":[]}],"operationId":"get-site"}},"/api/v1/personas/:persona_uuid/questions/generate":{"post":{"description":"Uses AI to generate questions based on the persona and site context. Costs 10 credits flat.","parameters":[{"in":"path","name":"persona_uuid","description":"Persona UUID","required":true,"schema":{"type":"string"}}],"summary":"Generate questions via LLM","tags":["Questions"],"security":[{"BearerAuth":[]}],"operationId":"generate-questions","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/usage":{"get":{"description":"Returns credit balance, auto-charge settings, and paginated transaction history.","parameters":[{"in":"query","name":"limit","description":"Max transactions to return","required":false,"schema":{"type":"integer"}},{"in":"query","name":"cursor","description":"Pagination cursor","required":false,"schema":{"type":"string"}},{"in":"query","name":"from","description":"Start date (ISO 8601)","required":false,"schema":{"type":"string"}},{"in":"query","name":"to","description":"End date (ISO 8601)","required":false,"schema":{"type":"string"}}],"summary":"Get usage summary","tags":["Usage"],"security":[{"BearerAuth":[]}],"operationId":"get-usage"}},"/api/v1/analysis":{"post":{"description":"Starts an analysis run. This is asynchronous - poll GET /api/v1/analysis/:uuid for status. Returns 202 Accepted.","summary":"Run analysis","tags":["Analysis"],"security":[{"BearerAuth":[]}],"operationId":"run-analysis","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/sites/:site_uuid/customer-types/generate":{"post":{"description":"Uses AI to generate customer types based on the site's product and value proposition. Costs 5 credits per generated type.","parameters":[{"in":"path","name":"site_uuid","description":"Site UUID","required":true,"schema":{"type":"string"}}],"summary":"Generate customer types via LLM","tags":["Customer Types"],"security":[{"BearerAuth":[]}],"operationId":"generate-customer-types","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/questions/:uuid/results":{"get":{"description":"Returns analysis results for a specific question. Use the `fields` parameter to include additional data (keywords, competitors, sources, responses).","parameters":[{"in":"path","name":"uuid","description":"Question UUID","required":true,"schema":{"type":"string"}},{"in":"query","name":"fields","description":"Comma-separated fields: keywords, competitors, sources, responses. Default: keywords only.","required":false,"schema":{"type":"string"}}],"summary":"Get question results","tags":["Questions"],"security":[{"BearerAuth":[]}],"operationId":"question-results"}},"/api/v1/signup/usdc":{"post":{"description":"Creates a USDC signup token. Use `no_email: true` for autonomous agent flows (no setup_url returned).","summary":"Create USDC signup token","tags":["Signup"],"security":[],"operationId":"signup-via-usdc-token","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/customer-types/:customer_type_uuid/personas/generate":{"post":{"description":"Uses AI to generate personas based on the customer type. Costs 5 credits per persona.","parameters":[{"in":"path","name":"customer_type_uuid","description":"Customer type UUID","required":true,"schema":{"type":"string"}}],"summary":"Generate personas via LLM","tags":["Personas"],"security":[{"BearerAuth":[]}],"operationId":"generate-personas","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/sites":{"get":{"description":"Returns a paginated list of sites for the organization.","parameters":[{"in":"query","name":"limit","description":"Max results (1-100)","required":false,"schema":{"type":"integer"}},{"in":"query","name":"cursor","description":"Pagination cursor from previous response","required":false,"schema":{"type":"string"}},{"in":"query","name":"include_archived","description":"Include archived sites","required":false,"schema":{"type":"boolean"}}],"summary":"List sites","tags":["Sites"],"security":[{"BearerAuth":[]}],"operationId":"list-sites"},"post":{"description":"Creates a new site. Auto-generates product_name and value_proposition from URL if not provided (5 credits).","summary":"Create site","tags":["Sites"],"security":[{"BearerAuth":[]}],"operationId":"create-site","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/usage/by-key":{"get":{"description":"Returns credit usage breakdown per API key.","parameters":[{"in":"query","name":"from","description":"Start date (ISO 8601)","required":false,"schema":{"type":"string"}},{"in":"query","name":"to","description":"End date (ISO 8601)","required":false,"schema":{"type":"string"}}],"summary":"Get usage by API key","tags":["Usage"],"security":[{"BearerAuth":[]}],"operationId":"usage-by-key"}},"/api/v1/auth/validate":{"post":{"description":"Validates the API key and returns organization info and credit balance.","summary":"Validate API key","tags":["Authentication"],"security":[{"BearerAuth":[]}],"operationId":"validate-auth"}},"/api/v1/account":{"get":{"description":"Returns account details including company name, site count, and owner information.","summary":"Get account information","tags":["General"],"security":[{"BearerAuth":[]}],"operationId":"get-account"}},"/api/v1/personas/:uuid":{"delete":{"description":"Archives a persona. Returns 204 No Content on success.","parameters":[{"in":"path","name":"uuid","description":"Persona UUID","required":true,"schema":{"type":"string"}}],"summary":"Archive persona","tags":["Personas"],"security":[{"BearerAuth":[]}],"operationId":"delete-persona"},"get":{"description":"Returns a persona with its questions.","parameters":[{"in":"path","name":"uuid","description":"Persona UUID","required":true,"schema":{"type":"string"}}],"summary":"Get persona","tags":["Personas"],"security":[{"BearerAuth":[]}],"operationId":"get-persona"},"put":{"description":"Updates a persona. Only include fields you want to change.","parameters":[{"in":"path","name":"uuid","description":"Persona UUID","required":true,"schema":{"type":"string"}}],"summary":"Update persona","tags":["Personas"],"security":[{"BearerAuth":[]}],"operationId":"update-persona","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/signup/:token/pay-usdc":{"post":{"description":"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":[{"in":"path","name":"token","description":"Signup token","required":true,"schema":{"type":"string"}},{"in":"header","name":"payment","description":"Omit this header to receive 402 payment-required challenge","required":false,"schema":{"type":"string"}}],"summary":"Sign up via x402 challenge","tags":["Signup"],"security":[],"operationId":"signup-via-x402","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/sites/:site_uuid/customer-types":{"get":{"description":"Lists all customer types for a site.","parameters":[{"in":"path","name":"site_uuid","description":"Site UUID","required":true,"schema":{"type":"string"}}],"summary":"List customer types","tags":["Customer Types"],"security":[{"BearerAuth":[]}],"operationId":"list-customer-types"},"post":{"description":"Creates a customer type manually. Costs 5 credits.","parameters":[{"in":"path","name":"site_uuid","description":"Site UUID","required":true,"schema":{"type":"string"}}],"summary":"Create customer type","tags":["Customer Types"],"security":[{"BearerAuth":[]}],"operationId":"create-customer-type","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/personas/:persona_uuid/questions":{"get":{"description":"Lists all questions for a persona.","parameters":[{"in":"path","name":"persona_uuid","description":"Persona UUID","required":true,"schema":{"type":"string"}}],"summary":"List questions","tags":["Questions"],"security":[{"BearerAuth":[]}],"operationId":"list-questions"},"post":{"description":"Creates a question manually. Free operation.","parameters":[{"in":"path","name":"persona_uuid","description":"Persona UUID","required":true,"schema":{"type":"string"}}],"summary":"Create question","tags":["Questions"],"security":[{"BearerAuth":[]}],"operationId":"create-question","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/signup":{"post":{"description":"Creates a credit-card signup token. USDC signups must use `/api/v1/signup/usdc`.","summary":"Signup Credit Card","tags":["Signup"],"security":[],"operationId":"signup-via-cc","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/analysis/:uuid/keyword_opportunities":{"get":{"description":"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":[{"in":"path","name":"uuid","description":"Analysis UUID","required":true,"schema":{"type":"string"}},{"in":"query","name":"threshold","description":"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.","required":false,"schema":{"type":"float"}},{"in":"query","name":"rank_threshold","description":"Also flag questions where brand appeared at rank worse than this value, even if mention rate meets the threshold.","required":false,"schema":{"type":"integer"}}],"summary":"Get keyword opportunities","tags":["Analysis"],"security":[{"BearerAuth":[]}],"operationId":"analysis-keyword-opportunities"}},"/api/v1/analysis/:uuid/competitors":{"get":{"description":"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":[{"in":"path","name":"uuid","description":"Analysis UUID","required":true,"schema":{"type":"string"}}],"summary":"Get competitors mentioned","tags":["Analysis"],"security":[{"BearerAuth":[]}],"operationId":"analysis-competitors"}},"/api/v1/analysis/:uuid/responses":{"get":{"description":"Returns raw AI model responses for the analysis.","parameters":[{"in":"path","name":"uuid","description":"Analysis UUID","required":true,"schema":{"type":"string"}}],"summary":"Get raw responses","tags":["Analysis"],"security":[{"BearerAuth":[]}],"operationId":"analysis-responses"}},"/api/v1/analysis/:uuid":{"get":{"description":"Returns analysis details including status. Poll this endpoint until status is 'completed' or 'failed'.","parameters":[{"in":"path","name":"uuid","description":"Analysis UUID","required":true,"schema":{"type":"string"}}],"summary":"Get analysis status","tags":["Analysis"],"security":[{"BearerAuth":[]}],"operationId":"get-analysis"}},"/api/v1/analysis/:uuid/keywords":{"get":{"description":"Returns aggregated keywords/search terms from all responses.","parameters":[{"in":"path","name":"uuid","description":"Analysis UUID","required":true,"schema":{"type":"string"}}],"summary":"Get keywords","tags":["Analysis"],"security":[{"BearerAuth":[]}],"operationId":"analysis-keywords"}}},"openapi":"3.0.3","security":[{"BearerAuth":[]}],"servers":[{"description":"Production","url":"https://botsee.io"}]}