BotSee API

{"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":{"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Returned on 429 responses.","schema":{"type":"integer","example":60}},"X-RateLimit-Limit":{"description":"Total requests allowed per window (currently 600 per minute).","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window for the caller's bucket.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) when the current window resets.","schema":{"type":"integer","example":1735689660}}},"responses":{"Forbidden":{"description":"Authenticated but lacks permission (e.g. botsee_disabled).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The requested resource does not exist or is not accessible.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"Payment required (insufficient credits or x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests. Wait and retry per Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"Unauthorized":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Request body or parameters failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Analysis":{"type":"object","properties":{"completed_at":{"type":"string","format":"date-time","nullable":true},"credits_used":{"type":"integer"},"models":{"type":"array","items":{"type":"string"}},"recommendations":{"type":"array","description":"Generated recommendations; empty until POST /analysis/:uuid/recommendations succeeds.","items":{"type":"object","properties":{"action":{"type":"string"},"priority":{"type":"string","enum":["high","medium","low"]},"reasoning":{"type":"string"},"target_keywords":{"type":"array","items":{"type":"string"}},"target_urls":{"type":"array","items":{"type":"string"}}}}},"recommendations_generated_at":{"type":"string","format":"date-time","nullable":true},"response_count":{"type":"integer"},"scope":{"type":"string","enum":["site","customer_type","persona","questions"]},"site_uuid":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"uuid":{"type":"string"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code (e.g. invalid_api_key)."},"details":{"type":"object","description":"Optional per-field validation errors.","additionalProperties":true},"message":{"type":"string","description":"Human-readable error message."}}}}},"PaymentRequirements":{"type":"object","description":"x402 payment requirements returned in 402 responses.","properties":{"accepts":{"type":"array","items":{"type":"object","description":"Payment scheme accepted by the server (chain, asset, chain, etc.).","additionalProperties":true}},"x402Version":{"type":"integer"}}},"Persona":{"type":"object","properties":{"description":{"type":"string"},"icp_persona":{"type":"string"},"name":{"type":"string"},"uuid":{"type":"string"}}},"Question":{"type":"object","properties":{"category":{"type":"string"},"is_active":{"type":"boolean"},"priority":{"type":"string"},"question":{"type":"string"},"uuid":{"type":"string"}}},"RateLimitHeaders":{"type":"object","description":"Documentation reference for rate-limit response headers. Actual values are returned in HTTP response headers (x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, retry-after on 429).","properties":{"limit":{"type":"integer","example":600},"remaining":{"type":"integer","example":599},"reset_at":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp when the bucket resets."},"window_seconds":{"type":"integer","example":60}}},"Site":{"type":"object","properties":{"aliases":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"customer_type_count":{"type":"integer"},"customer_types":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"persona_count":{"type":"integer"},"uuid":{"type":"string"}}}},"domain":{"type":"string"},"product_name":{"type":"string","nullable":true},"status":{"type":"string"},"uuid":{"type":"string"},"value_proposition":{"type":"string","nullable":true}}},"WebhookEvent":{"type":"object","required":["event","timestamp","data"],"properties":{"data":{"type":"object","description":"Event-specific payload. See /api/v1/webhooks/events for per-event schemas.","additionalProperties":true},"event":{"type":"string","description":"Event type (e.g. analysis.completed).","example":"analysis.completed"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 UTC time the event was emitted."}}}},"securitySchemes":{"BearerAuth":{"scheme":"bearer","type":"http","description":"API key starting with 'bts_live_'"}}},"paths":{},"security":[{"BearerAuth":[]}],"openapi":"3.0.3","servers":[{"description":"Production","url":"https://botsee.io"}]}