{"openapi":"3.1.0","info":{"title":"BotScope API","version":"1.0.0","description":"Read-only access to your organisation's LLM-visibility project data. Authenticate with an org-scoped API key as a Bearer token."},"servers":[{"url":"https://api.botscope.ai/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An org-scoped API key, e.g. `Authorization: Bearer bsk_...`. Create one in the dashboard under Settings → Developers."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable code (e.g. not_found, rate_limited)."},"message":{"type":"string"},"details":{"nullable":true}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/projects":{"get":{"summary":"List projects","description":"All projects in the authenticated organisation.","responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}":{"get":{"summary":"Get a project","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/scans":{"get":{"summary":"List scans","description":"Paginated visibility scan history (newest first).","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Keyset cursor — pass the previous page's pagination.nextBefore."}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/visibility":{"get":{"summary":"Visibility overview","description":"Overall + L1–L4 layer scores with trend deltas, citations, provider breakdown and share of voice.","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider","in":"query","required":false,"schema":{"type":"string"},"description":"Filter to a single provider (e.g. openai, google_ai_overview)."},{"name":"scanId","in":"query","required":false,"schema":{"type":"string"},"description":"A specific scan id. Takes precedence over from/to."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start of date window (ISO-8601). Must be paired with `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End of date window (ISO-8601). Must be paired with `from`."}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/share-of-voice":{"get":{"summary":"Share of voice","description":"Own-brand vs competitor mention share across the resolved scan set.","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider","in":"query","required":false,"schema":{"type":"string"},"description":"Filter to a single provider (e.g. openai, google_ai_overview)."},{"name":"scanId","in":"query","required":false,"schema":{"type":"string"},"description":"A specific scan id. Takes precedence over from/to."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start of date window (ISO-8601). Must be paired with `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End of date window (ISO-8601). Must be paired with `from`."}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/competitors":{"get":{"summary":"Competitor comparison","description":"Own brand + tracked competitors ranked by median mention count.","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"scanId","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/categories":{"get":{"summary":"Category landscape","description":"Per-(category, use-case) share of voice, provider breakdown, trend delta and top competitors.","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"scanId","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/responses":{"get":{"summary":"List responses","description":"Paginated index of raw LLM responses (newest first).","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"provider","in":"query","required":false,"schema":{"type":"string"}},{"name":"scanId","in":"query","required":false,"schema":{"type":"string"}},{"name":"layer","in":"query","required":false,"schema":{"type":"string","enum":["L1","L2","L3","L4"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Keyset cursor — pass the previous page's pagination.nextBefore."}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/responses/{responseId}":{"get":{"summary":"Get a response","description":"One response with its model output, brand detections and citations.","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"responseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}