openapi.json

{"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"}},"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, payTo, maxAmountRequired, 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":{"created_at":{"type":"string","format":"date-time"},"domain":{"type":"string"},"product_name":{"type":"string"},"uuid":{"type":"string"},"value_proposition":{"type":"string"}}},"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":{"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"object","properties":{"count":{"type":"integer"},"models":{"type":"array","items":{"type":"string"}},"term":{"type":"string"}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"analysis-keywords"}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"customer_types":{"type":"array","items":{"type":"object","properties":{"created_at":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"persona_count":{"type":"integer"},"uuid":{"type":"string"}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"customer_type":{"type":"object","properties":{"created_at":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"persona_count":{"type":"integer"},"uuid":{"type":"string"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"create-customer-type","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"description":{"type":"string","description":"Description of this market segment"},"name":{"type":"string","description":"Customer type name"}}}}}}}},"/api/v1/billing/settings":{"get":{"description":"Returns the organization's billing settings and current credit balance.","summary":"Get billing settings","tags":["General"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"integer"},"current_month_spend_cents":{"type":"integer"},"low_balance_threshold":{"type":"integer"},"max_monthly_spend_cents":{"type":"integer"},"monthly_spend_limit_cents":{"type":"integer"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"get-billing-settings"},"patch":{"description":"Updates the organization's monthly spend limit. Other settings are read-only via this endpoint.","summary":"Update billing settings","tags":["General"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"integer"},"current_month_spend_cents":{"type":"integer"},"low_balance_threshold":{"type":"integer"},"max_monthly_spend_cents":{"type":"integer"},"monthly_spend_limit_cents":{"type":"integer"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"update-billing-settings","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"monthly_spend_limit_cents":{"type":"integer","description":"Maximum spend per calendar month in cents. Cannot exceed max_monthly_spend_cents."}}}}}}}},"/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"],"responses":{"204":{"description":"No content. Operation succeeded with empty body.","headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"delete-webhook"}},"/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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"credits_used":{"type":"integer"},"customer_types":{"type":"array","items":{"type":"object","properties":{"created_at":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"persona_count":{"type":"integer"},"uuid":{"type":"string"}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"generate-customer-types","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"default":3,"type":"integer","description":"Number of customer types to generate"}}}}}}}},"/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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"accepts":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"string"},"asset":{"type":"string"},"extra":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}},"maxTimeoutSeconds":{"type":"integer"},"network":{"type":"string"},"payTo":{"type":"string"},"scheme":{"type":"string"}}}},"amount_cents":{"type":"integer"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"payment_requirements":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"string"},"asset":{"type":"string"},"extra":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}},"maxTimeoutSeconds":{"type":"integer"},"network":{"type":"string"},"payTo":{"type":"string"},"scheme":{"type":"string"}}}},"x402Version":{"type":"integer"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"operationId":"topoff-via-x402","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"amount_cents":{"type":"integer","description":"Amount in USD cents (250-100000, i.e., $2.50-$1000). Optional for discovery-only 402 challenge (defaults to configured discovery amount)."}}}}}}}},"/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"],"responses":{"204":{"description":"No content. Operation succeeded with empty body.","headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"object","properties":{"category":{"type":"string"},"created_at":{"type":"string"},"is_active":{"type":"boolean"},"priority":{"type":"string"},"question":{"type":"string"},"uuid":{"type":"string"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"update-question","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","description":"Updated category"},"is_active":{"type":"boolean","description":"Active/inactive toggle"},"priority":{"type":"string","description":"Updated priority"},"question":{"type":"string","description":"Updated question text"}}}}}}}},"/api/v1/webhooks":{"get":{"description":"Lists all registered webhooks for the organization.","summary":"List webhooks","tags":["Webhooks"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"created_at":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"failure_count":{"type":"integer"},"last_triggered_at":{"type":"string","nullable":true},"status":{"type":"string"},"url":{"type":"string"},"uuid":{"type":"string"}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"type":"object","properties":{"created_at":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"failure_count":{"type":"integer"},"last_triggered_at":{"type":"string","nullable":true},"secret":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"},"uuid":{"type":"string"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"create-webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"events":{"default":["analysis.completed","analysis.failed"],"type":"array","description":"Events to subscribe to. Call GET /api/v1/webhooks/events for the canonical catalog of currently-emitted event types and their payload schemas."},"url":{"type":"string","description":"HTTPS URL to receive webhook payloads"}}}}}}}},"/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. Optionally pass `prompt` to steer the LLM toward a specific persona within the customer segment (requires `count: 1`).","parameters":[{"in":"path","name":"customer_type_uuid","description":"Customer type UUID","required":true,"schema":{"type":"string"}}],"summary":"Generate personas via LLM","tags":["Personas"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"credits_used":{"type":"integer"},"personas":{"type":"array","items":{"type":"object","properties":{"created_at":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"question_count":{"type":"integer"},"uuid":{"type":"string"}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"generate-personas","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"default":3,"type":"integer","description":"Number of personas to generate"},"prompt":{"type":"string","description":"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."}}}}}}}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"by_customer_type":{"type":"array","items":{"type":"object","properties":{"competitors":{"type":"array","items":{"type":"object","properties":{"appearance_percentage":{"type":"number"},"avg_confidence":{"type":"number"},"avg_rank":{"type":"number"},"best_rank":{"type":"integer"},"mentions":{"type":"integer"},"name":{"type":"string"},"unique_responses":{"type":"integer"},"url":{"type":"string"}}}},"customer_type_name":{"type":"string"},"customer_type_uuid":{"type":"string"},"total_responses":{"type":"integer"},"total_unique_competitors":{"type":"integer"}}}},"overall_summary":{"type":"object","properties":{"own_company_mentioned":{"type":"boolean"},"total_responses_analyzed":{"type":"integer"},"total_unique_competitors":{"type":"integer"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"analysis-competitors"}},"/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"],"responses":{"204":{"description":"No content. Operation succeeded with empty body.","headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"$ref":"#/components/schemas/Site"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"get-site"}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"mentions":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string"}}}},"total_unique":{"type":"integer"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"analysis-source-opportunities"}},"/api/v1/webhooks/events":{"get":{"description":"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.","summary":"List webhook event catalog","tags":["Webhooks"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"event":{"type":"string"},"payload_schema":{"type":"object","properties":{"properties":{"type":"object","properties":{}},"type":{"type":"string"}}}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"list-webhook-events"}},"/api/v1/api-keys/{id}/rotate":{"post":{"description":"Atomically creates a new API key with the same name and revokes the old one. Returns the new raw key once.","parameters":[{"in":"path","name":"id","description":"API key id to rotate","required":true,"schema":{"type":"string"}}],"summary":"Rotate API key","tags":["General"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"object","properties":{"created_at":{"type":"string"},"id":{"type":"string"},"key":{"type":"string"},"key_prefix":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"rotate-api-key"}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string"},"company_name":{"type":"string"},"contact_email":{"type":"string"},"docs_url":{"type":"string"},"payment_method":{"type":"string"},"status":{"type":"string"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"operationId":"signup-status"}},"/api/v1/usage/by-site":{"get":{"description":"Returns credit usage grouped by site: per-site totals plus a per-category breakdown.","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"}},{"in":"query","name":"site_uuid","description":"Limit to a single site (404 if it does not belong to the org)","required":false,"schema":{"type":"string"}}],"summary":"Get usage by site","tags":["Sites"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"sites":{"type":"array","items":{"type":"object","properties":{"breakdown":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"credits":{"type":"integer"}}}},"domain":{"type":"string"},"name":{"type":"string"},"site_uuid":{"type":"string"},"total_credits":{"type":"integer"}}}},"to":{"type":"string"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"usage-by-site"}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"integer"},"current_month_spend_cents":{"type":"integer"},"cursor":{"type":"string","nullable":true},"low_balance_threshold":{"type":"integer"},"max_monthly_spend_cents":{"type":"integer"},"monthly_spend_limit_cents":{"type":"integer"},"transactions":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"integer"},"api_key_id":{"type":"integer"},"balance_after":{"type":"integer"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"integer"},"resource_id":{"type":"string"},"resource_type":{"type":"string"},"type":{"type":"string"}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"202":{"description":"Accepted; processing asynchronously.","content":{"application/json":{"schema":{"type":"object","properties":{"analysis":{"$ref":"#/components/schemas/Analysis"},"estimated_credits":{"type":"integer"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"run-analysis","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site_uuid"],"properties":{"models":{"default":["openai","claude","perplexity"],"type":"array","description":"AI models: openai, claude, perplexity, gemini, grok"},"scope":{"default":"site","type":"string","description":"Scope: 'site', 'customer_type', 'persona', or 'questions'"},"site_uuid":{"type":"string","description":"Site UUID to analyze"},"target_uuids":{"type":"array","description":"Required for non-site scope. UUIDs of customer types, personas, or questions."}}}}}}}},"/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"],"responses":{"204":{"description":"No content. Operation succeeded with empty body.","headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"persona":{"$ref":"#/components/schemas/Persona"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"persona":{"type":"object","properties":{"created_at":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"question_count":{"type":"integer"},"uuid":{"type":"string"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"update-persona","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"Updated persona description"},"name":{"type":"string","description":"Updated persona name"}}}}}}}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"questions":{"type":"array","items":{"$ref":"#/components/schemas/Question"}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"question":{"$ref":"#/components/schemas/Question"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"create-question","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"properties":{"category":{"default":"problem_solving","type":"string","description":"Question category"},"priority":{"default":"medium","type":"string","description":"Priority: low, medium, high"},"question":{"type":"string","description":"The question text to ask AI models"}}}}}}}},"/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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"expires_at":{"type":"string"},"pay_usdc_url":{"type":"string"},"payment_method":{"type":"string"},"poll_url":{"type":"string"},"setup_token":{"type":"string"},"setup_url":{"type":"string"},"status_url":{"type":"string"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"operationId":"signup-via-usdc-token","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"company_name":{"type":"string","description":"Company name (optional)"},"contact_email":{"type":"string","description":"Contact email (optional for USDC)"},"contact_name":{"type":"string","description":"Contact name (optional)"},"no_email":{"default":false,"type":"boolean","description":"Set to true for autonomous agents that skip email verification"}}}}}}}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"analyses":{"type":"array","items":{"$ref":"#/components/schemas/Analysis"}},"cursor":{"type":"string","nullable":true}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"list-analyses"}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"sites":{"type":"array","items":{"$ref":"#/components/schemas/Site"}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"$ref":"#/components/schemas/Site"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"create-site","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"domain":{"type":"string","description":"Domain override (extracted from URL if not provided)"},"product_name":{"type":"string","description":"Product name (auto-generated from URL if not provided, costs 5 credits)"},"url":{"type":"string","description":"Full URL to analyze (e.g. 'https://example.com/products/foo')"},"value_proposition":{"type":"string","description":"Value proposition (auto-generated from URL if not provided, costs 5 credits)"}}}}}}}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"usage_by_key":{"type":"array","items":{"type":"object","properties":{"analysis_count":{"type":"integer"},"api_key_id":{"type":"integer"},"api_key_name":{"type":"string"},"api_key_prefix":{"type":"string"},"generation_count":{"type":"integer"},"total_credits_used":{"type":"integer"}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"object","properties":{"id":{"type":"integer"},"key_prefix":{"type":"string"},"last_used_at":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}},"credits":{"type":"object","properties":{"balance":{"type":"integer"}}},"organization":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"}}},"valid":{"type":"boolean"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"validate-auth"}},"/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"],"responses":{"204":{"description":"No content. Operation succeeded with empty body.","headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"customer_type":{"type":"object","properties":{"created_at":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"persona_count":{"type":"integer"},"personas":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"question_count":{"type":"integer"},"uuid":{"type":"string"}}}},"uuid":{"type":"string"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"customer_type":{"type":"object","properties":{"created_at":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"persona_count":{"type":"integer"},"uuid":{"type":"string"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"update-customer-type","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"Updated description"},"name":{"type":"string","description":"Updated customer type name"}}}}}}}},"/api/v1/account":{"get":{"description":"Returns account details including company name, site count, and owner information.","summary":"Get account information","tags":["General"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"company_name":{"type":"string"},"owner_email":{"type":"string"},"owner_name":{"type":"string"},"site_count":{"type":"integer"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"get-account"}},"/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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"accepts":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"string"},"asset":{"type":"string"},"extra":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}},"maxTimeoutSeconds":{"type":"integer"},"network":{"type":"string"},"payTo":{"type":"string"},"scheme":{"type":"string"}}}},"amount_cents":{"type":"integer"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"payment_requirements":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"string"},"asset":{"type":"string"},"extra":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}},"maxTimeoutSeconds":{"type":"integer"},"network":{"type":"string"},"payTo":{"type":"string"},"scheme":{"type":"string"}}}},"x402Version":{"type":"integer"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"operationId":"signup-via-x402","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_cents"],"properties":{"amount_cents":{"type":"integer","description":"Amount in USD cents (250-100000, i.e., $2.50-$1000)"}}}}}}}},"/api/v1/rate-limits":{"get":{"description":"Returns the caller's current rate-limit state without consuming additional budget. Useful for agents that want to back off proactively before hitting 429.","summary":"Get rate-limit budget","tags":["General"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"limit":{"type":"integer"},"remaining":{"type":"integer"},"reset_at":{"type":"string"},"window_seconds":{"type":"integer"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"get-rate-limits"}},"/api/v1/webhooks/{uuid}/test":{"post":{"description":"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":[{"in":"path","name":"uuid","description":"Webhook UUID","required":true,"schema":{"type":"string"}}],"summary":"Send synthetic test event","tags":["Webhooks"],"responses":{"202":{"description":"Accepted; processing asynchronously.","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"job_id":{"type":"integer"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"test-webhook"}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"personas":{"type":"array","items":{"$ref":"#/components/schemas/Persona"}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"persona":{"$ref":"#/components/schemas/Persona"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"create-persona","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","description"],"properties":{"description":{"type":"string","description":"Detailed persona description"},"name":{"type":"string","description":"Persona name (e.g. 'CTO')"}}}}}}}},"/api/v1/usage/line-items":{"get":{"description":"Lists individual paid operations (line items), newest first. One row per site, category, operation, and resource.","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"}},{"in":"query","name":"site_uuid","description":"Limit to a single site (404 if it does not belong to the org)","required":false,"schema":{"type":"string"}},{"in":"query","name":"category","description":"Limit to one operation category (e.g. analysis, setup, content_generation)","required":false,"schema":{"type":"string"}},{"in":"query","name":"limit","description":"Max line items to return","required":false,"schema":{"type":"integer"}}],"summary":"Get usage line items","tags":["Usage"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"line_items":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"credits":{"type":"integer"},"domain":{"type":"string"},"last_charged_at":{"type":"string"},"name":{"type":"string"},"operation":{"type":"string"},"site_uuid":{"type":"string"}}}},"to":{"type":"string"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"usage-line-items"}},"/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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"credits_used":{"type":"integer"},"questions":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"created_at":{"type":"string"},"is_active":{"type":"boolean"},"priority":{"type":"string"},"question":{"type":"string"},"uuid":{"type":"string"}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"generate-questions","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"default":5,"type":"integer","description":"Number of questions to generate"}}}}}}}},"/api/v1/analysis/{uuid}/recommendations":{"post":{"description":"Generates actionable recommendations from the analysis (cached after first call). Costs 5 credits the first time; subsequent calls return the cached result.","parameters":[{"in":"path","name":"uuid","description":"Analysis UUID","required":true,"schema":{"type":"string"}}],"summary":"Generate recommendations","tags":["Analysis"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"recommendations":{"type":"object","properties":{"actions":{"type":"array","items":{"type":"object","properties":{"detail":{"type":"string"},"title":{"type":"string"}}}},"summary":{"type":"string"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"analysis-recommendations"}},"/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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"expires_at":{"type":"string"},"payment_method":{"type":"string"},"setup_token":{"type":"string"},"setup_url":{"type":"string"},"status_url":{"type":"string"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"operationId":"signup-via-cc","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"company_name":{"type":"string","description":"Company name (optional)"},"contact_email":{"type":"string","description":"Contact email (optional)"},"contact_name":{"type":"string","description":"Contact person name (optional)"},"payment_method":{"default":"credit_card","type":"string","description":"Defaults to 'credit_card'. Use `/api/v1/signup/usdc` for USDC."}}}}}}}},"/api/v1/api-keys/reset":{"post":{"description":"Exchanges a one-time reset token (from email) for a fresh API key. Public endpoint — no Bearer auth required, the token authenticates the request.","summary":"Reset API key with one-time token","tags":["General"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"object","properties":{"created_at":{"type":"string"},"id":{"type":"string"},"key":{"type":"string"},"key_prefix":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"operationId":"reset-api-key","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Single-use reset token from the reset email."}}}}}}}},"/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"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"credits_used":{"type":"integer"},"model":{"type":"string"},"provider":{"type":"string"},"tokens":{"type":"object","properties":{"input":{"type":"integer"},"output":{"type":"integer"},"total":{"type":"integer"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"generate-content","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question_uuid"],"properties":{"keywords":{"type":"array","description":"Custom keywords to incorporate"},"provider":{"default":"gemini","type":"string","description":"LLM provider: 'gemini' or 'claude'"},"question_uuid":{"type":"string","description":"Question UUID to base the post on"}}}}}}}},"/api/v1/pricing":{"get":{"description":"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.","summary":"Get pricing","tags":["General"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"pricing":{"type":"object","properties":{"analysis_estimated_per_query":{"type":"object","properties":{"claude":{"type":"integer"},"default":{"type":"integer"},"gemini":{"type":"integer"},"grok":{"type":"integer"},"openai":{"type":"integer"},"perplexity":{"type":"integer"}}},"analysis_reservation_buffer":{"type":"number"},"customer_type_generation_per_type":{"type":"integer"},"note":{"type":"string"},"persona_generation_per_persona":{"type":"integer"},"question_generation":{"type":"integer"},"site_creation_auto_generate":{"type":"integer"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[],"operationId":"get-pricing"}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"keywords_by_model":{"type":"object","properties":{"claude":{"type":"array","items":{"type":"string"}},"openai":{"type":"array","items":{"type":"string"}}}},"question":{"type":"string"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"question-results"}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"mention_count":{"type":"integer"},"own_company_mentioned":{"type":"boolean"},"title":{"type":"string"},"url":{"type":"string"}}}},"total_unique":{"type":"integer"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"analysis-sources"}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"analysis":{"$ref":"#/components/schemas/Analysis"}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"get-analysis"}},"/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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"responses":{"type":"array","items":{"type":"object","properties":{"created_at":{"type":"string"},"mentioned":{"type":"boolean"},"model":{"type":"string"},"question":{"type":"string"},"response_text":{"type":"string"},"search_terms":{"type":"array","items":{"type":"string"}},"uuid":{"type":"string"}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"analysis-responses"}},"/api/v1/api-keys":{"get":{"description":"Lists all API keys for the organization (raw key never returned).","summary":"List API keys","tags":["General"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"api_keys":{"type":"array","items":{"type":"object","properties":{"created_at":{"type":"string"},"id":{"type":"string"},"key_prefix":{"type":"string"},"last_used_at":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"list-api-keys"},"post":{"description":"Creates a new API key. The raw key is returned only once in the response body — store it immediately.","summary":"Create API key","tags":["General"],"responses":{"201":{"description":"Resource created.","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"object","properties":{"created_at":{"type":"string"},"id":{"type":"string"},"key":{"type":"string"},"key_prefix":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"create-api-key","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"default":"API Key","type":"string","description":"Human-readable name for the key."}}}}}}}},"/api/v1/api-keys/{id}":{"delete":{"description":"Revokes an API key. You cannot revoke the key being used to make this request — use rotate or another key.","parameters":[{"in":"path","name":"id","description":"API key id","required":true,"schema":{"type":"string"}}],"summary":"Revoke API key","tags":["General"],"responses":{"204":{"description":"No content. Operation succeeded with empty body.","headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"delete-api-key"}},"/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":"number"}},{"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"],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"opportunities":{"type":"array","items":{"type":"object","properties":{"by_model":{"type":"array","items":{"type":"object","properties":{"mentioned":{"type":"boolean"},"provider":{"type":"string"},"rank":{"type":"string","nullable":true},"search_keywords":{"type":"array","items":{"type":"string"}}}}},"mentioned_count":{"type":"integer"},"persona":{"type":"string"},"persona_uuid":{"type":"string"},"question":{"type":"string"},"question_uuid":{"type":"string"},"total_responses":{"type":"integer"}}}}}}}},"headers":{"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"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]}],"operationId":"analysis-keyword-opportunities"}}},"openapi":"3.0.3","security":[{"BearerAuth":[]}],"servers":[{"description":"Production","url":"https://botsee.io"}]}