{
  "openapi": "3.0.0",
  "info": {
    "title": "Hordus AI API",
    "description": "Public API for Hordus AI platform - Generative Engine Optimization (GEO) & Answer Engine Optimization (AEO).",
    "version": "1.0.0",
    "contact": {
      "name": "Hordus Support",
      "url": "https://hordus.ai/contact",
      "email": "info@hordus.ai"
    }
  },
  "servers": [
    {
      "url": "https://hordus.ai/api",
      "description": "Production Server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API Key acquired from the Hordus Developer Portal."
      },
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://hordus.ai/oauth/authorize",
            "tokenUrl": "https://hordus.ai/oauth/token",
            "scopes": {
              "read:visibility": "Read visibility metrics",
              "read:metrics": "Read standard metrics",
              "write:projects": "Modify project settings"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "not_found"
          },
          "message": {
            "type": "string",
            "example": "The requested resource could not be found."
          }
        },
        "required": ["error", "message"]
      },
      "VisibilityResponse": {
        "type": "object",
        "description": "Brand AI visibility and Answer Share of Voice metrics.",
        "properties": {
          "brandId": { "type": "string", "example": "brand_abc123" },
          "visibilityScore": { "type": "number", "format": "float", "example": 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" }
        },
        "required": ["brandId", "visibilityScore", "metrics", "status"]
      },
      "WebhookRegistration": {
        "type": "object",
        "description": "Request body to register a webhook endpoint.",
        "properties": {
          "url": { "type": "string", "format": "uri", "example": "https://your-service.com/webhooks/hordus" },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["visibility.updated", "citation.new", "citation.lost", "asov.threshold_crossed", "report.ready"]
            },
            "example": ["visibility.updated", "citation.new"]
          },
          "secret": { "type": "string", "description": "Optional HMAC signing secret for payload verification." }
        },
        "required": ["url", "events"]
      },
      "WebhookResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "wh_abc12345" },
          "url": { "type": "string", "format": "uri" },
          "events": { "type": "array", "items": { "type": "string" } },
          "status": { "type": "string", "example": "active" },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "required": ["id", "url", "events", "status", "createdAt"]
      }
    },
    "headers": {
      "RateLimit-Limit": {
        "description": "The maximum number of requests allowed in the current time window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Remaining": {
        "description": "The number of requests remaining in the current time window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Reset": {
        "description": "The time at which the current rate limit window resets in UTC epoch seconds.",
        "schema": {
          "type": "integer"
        }
      }
    },
    "responses": {
      "UnauthorizedError": {
        "description": "API key is missing or invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFoundError": {
        "description": "The specified resource was not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimitError": {
        "description": "Rate limit exceeded.",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimit-Reset"
          },
          "Retry-After": {
            "description": "Seconds to wait before retrying",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/v1/info": {
      "get": {
        "summary": "Get Hordus AI Platform Information",
        "description": "Returns public metadata and capabilities of the Hordus AI platform.",
        "operationId": "getPlatformInfo",
        "security": [],
        "responses": {
          "200": {
            "description": "Successful response containing platform information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "Hordus AI"
                    },
                    "description": {
                      "type": "string",
                      "example": "Enterprise platform for Generative Engine Optimization and Answer Engine Optimization."
                    },
                    "features": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "example": [
                        "Real Prompt Intelligence",
                        "Answer Share of Voice (A-SOV)"
                      ]
                    },
                    "documentation": {
                      "type": "string",
                      "example": "https://hordus.ai/developers"
                    }
                  },
                  "required": ["name", "description", "features", "documentation"]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          }
        }
      }
    },
    "/v1/brand/{id}/visibility": {
      "get": {
        "summary": "Retrieve Brand Visibility Metrics",
        "description": "Returns Answer Engine optimization metrics for a specific brand across major LLMs (ChatGPT, Claude, Gemini). Requires an API key.",
        "operationId": "getBrandVisibility",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The unique identifier of the brand.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful return of visibility metrics.",
            "headers": {
              "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VisibilityResponse" }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          }
        }
      }
    },
    "/v1/stream": {
      "get": {
        "summary": "Stream Generation Example",
        "description": "Returns a chunked transfer encoded stream demonstrating long-running LLM generation.",
        "operationId": "streamGenerationExample",
        "security": [],
        "responses": {
          "200": {
            "description": "Successful stream connection established.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          }
        }
      }
    },
    "/v1/webhooks": {
      "post": {
        "summary": "Register a Webhook",
        "description": "Subscribe to real-time Hordus AI events. Supported events: visibility.updated, citation.new, citation.lost, asov.threshold_crossed, report.ready.",
        "operationId": "registerWebhook",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WebhookRegistration" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook registered successfully.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WebhookResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/UnauthorizedError" },
          "401": { "$ref": "#/components/responses/UnauthorizedError" },
          "429": { "$ref": "#/components/responses/RateLimitError" }
        }
      },
      "get": {
        "summary": "List Registered Webhooks",
        "description": "Returns all active webhook subscriptions for the authenticated account.",
        "operationId": "listWebhooks",
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": {
            "description": "List of active webhooks.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "webhooks": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/WebhookResponse" }
                    },
                    "supportedEvents": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/UnauthorizedError" },
          "429": { "$ref": "#/components/responses/RateLimitError" }
        }
      }
    }
  }
}