{"openapi":"3.1.0","info":{"title":"Hordus AI API","description":"REST API for Hordus AI — the enterprise Generative Engine Optimization (GEO) and Answer Engine Optimization (AEO) platform. Measure and influence brand visibility across ChatGPT, Claude, Gemini, Perplexity, and AI Overviews.","version":"1.0.0","contact":{"name":"Hordus AI Support","email":"support@hordus.ai","url":"https://www.hordus.ai/developers"},"license":{"name":"Proprietary","url":"https://www.hordus.ai/terms"},"x-logo":{"url":"https://www.hordus.ai/hordus-logo.png","altText":"Hordus AI"}},"servers":[{"url":"https://www.hordus.ai/api/v1","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Brand Visibility","description":"AI visibility scores and Answer Share of Voice metrics"},{"name":"Authentication","description":"API key management"},{"name":"Webhooks","description":"Real-time event notifications"},{"name":"Info","description":"Service metadata and health"}],"paths":{"/info":{"get":{"tags":["Info"],"operationId":"getInfo","summary":"Get Hordus AI service info","description":"Returns service metadata, capabilities, and status. No authentication required.","security":[],"responses":{"200":{"description":"Service info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InfoResponse"}}}}}}},"/brand/{id}/visibility":{"get":{"tags":["Brand Visibility"],"operationId":"getBrandVisibility","summary":"Get AI visibility score for a brand","description":"Returns the Answer Share of Voice (A-SOV), AI mention count, sentiment, and top platforms where the brand is cited by AI engines.","parameters":[{"name":"id","in":"path","required":true,"description":"Brand identifier","schema":{"type":"string","example":"brand_abc123"}}],"responses":{"200":{"description":"Brand visibility metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandVisibilityResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/auth/keys":{"post":{"tags":["Authentication"],"operationId":"createApiKey","summary":"Generate a Hordus AI API key","description":"Creates a new sandbox-tier API key (`hordus_sk_*`) stored securely in Upstash Redis.","security":[],"responses":{"201":{"description":"API key created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/webhooks":{"post":{"tags":["Webhooks"],"operationId":"registerWebhook","summary":"Register a webhook endpoint","description":"Subscribe to real-time events when brand visibility metrics change or thresholds are crossed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRegistration"}}}},"responses":{"201":{"description":"Webhook registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key generated at https://www.hordus.ai/developers. Prefix: `hordus_sk_`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token"}},"schemas":{"InfoResponse":{"type":"object","properties":{"name":{"type":"string","example":"Hordus AI"},"description":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"documentation":{"type":"string","example":"https://www.hordus.ai/developers"},"version":{"type":"string","example":"1.0.0"},"status":{"type":"string","example":"operational"}}},"BrandVisibilityResponse":{"type":"object","properties":{"brandId":{"type":"string","example":"brand_abc123"},"visibilityScore":{"type":"number","example":84},"answerShareOfVoice":{"type":"number","example":0.84},"metrics":{"type":"object","properties":{"aiMentions":{"type":"integer","example":1240},"sentiment":{"type":"string","enum":["positive","neutral","negative"],"example":"positive"},"topPlatforms":{"type":"array","items":{"type":"string"},"example":["ChatGPT","Claude","Perplexity"]}}},"status":{"type":"string","example":"success"}}},"ApiKeyResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"key":{"type":"string","example":"hordus_sk_..."}}},"WebhookRegistration":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","example":"https://your-app.com/webhook"},"events":{"type":"array","items":{"type":"string","enum":["visibility.updated","threshold.crossed","report.ready"]}},"secret":{"type":"string","description":"HMAC secret for payload signing"}}},"WebhookResponse":{"type":"object","properties":{"id":{"type":"string","example":"wh_abc123"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable error code","example":"not_found"},"message":{"type":"string","description":"Human-readable error description"},"hint":{"type":"string","description":"Suggested resolution"},"docs":{"type":"string","description":"URL to relevant documentation"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"bad_request","message":"Invalid request body","hint":"Check required fields","docs":"https://www.hordus.ai/developers"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"unauthorized","message":"Invalid or missing X-API-Key header","hint":"Generate a key at https://www.hordus.ai/developers","docs":"https://www.hordus.ai/developers"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"not_found","message":"The requested resource was not found","docs":"https://www.hordus.ai/developers"}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}},"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"rate_limited","message":"Too many requests. Please try again later."}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"internal_error","message":"An unexpected error occurred","hint":"Contact support@hordus.ai if this persists"}}}}}},"x-mcp-server":"https://www.hordus.ai/mcp?transport=sse","x-agent-card":"https://www.hordus.ai/.well-known/agent-card.json","x-llms-txt":"https://www.hordus.ai/llms.txt"}