{
  "openapi": "3.0.3",
  "info": {
    "title": "Visiblee Public API",
    "version": "1.0.0",
    "description": "Read-only API for Visiblee dashboard data."
  },
  "servers": [
    {
      "url": "https://api.visiblee.xyz/v1/public"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Visiblee API key from the developer API portal."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": { "type": "boolean" },
          "message": { "type": "string" }
        }
      },
      "Project": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "company_id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "domain": { "type": "string", "nullable": true },
          "description": { "type": "string", "nullable": true },
          "category_summary": { "type": "string", "nullable": true },
          "status": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "VisibilityReport": {
        "type": "object",
        "properties": {
          "project_id": { "type": "string", "format": "uuid" },
          "current_score": { "type": "number", "nullable": true },
          "mention_rate": { "type": "number" },
          "average_rank": { "type": "number", "nullable": true },
          "sentiment": { "type": "number", "nullable": true },
          "prompt_count": { "type": "integer" },
          "run_count": { "type": "integer" },
          "top_competitors": { "type": "array", "items": { "type": "object" } },
          "prompt_breakdown": { "type": "array", "items": { "type": "object" } },
          "engine_breakdown": { "type": "array", "items": { "type": "object" } }
        }
      }
    }
  },
  "security": [{ "ApiKeyAuth": [] }],
  "paths": {
    "/projects": {
      "get": {
        "summary": "List projects",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Project" }
                }
              }
            }
          },
          "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/projects/{project_id}": {
      "get": {
        "summary": "Get project",
        "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } }
      }
    },
    "/projects/{project_id}/visibility": {
      "get": {
        "summary": "Get visibility report",
        "parameters": [
          { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
          { "name": "engine_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }
        ],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibilityReport" } } } } }
      }
    },
    "/projects/{project_id}/visibility/timeseries": { "get": { "summary": "Get visibility timeseries", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/scores/daily": { "get": { "summary": "Get daily scores", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/prompts": { "get": { "summary": "List prompts", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/segments": { "get": { "summary": "List segments", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/segments/analytics": { "get": { "summary": "Get segment analytics", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/competitors": { "get": { "summary": "List competitors", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/competitor-rankings": { "get": { "summary": "Get competitor rankings", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/citations": { "get": { "summary": "List citations", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/mentions": { "get": { "summary": "List mentions", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/referrers": { "get": { "summary": "List referrers", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/warm-leads": { "get": { "summary": "List warm leads", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/engines": { "get": { "summary": "List project engines", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/terms": { "get": { "summary": "List project terms", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/runs": { "get": { "summary": "List run groups", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/runs/{run_group_id}": { "get": { "summary": "Get run group", "parameters": [{ "name": "run_group_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/runs/{run_group_id}/results": { "get": { "summary": "Get run results", "parameters": [{ "name": "run_group_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/reddit/metrics": { "get": { "summary": "Get Reddit metrics", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/reddit/leads": { "get": { "summary": "List Reddit leads", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } },
    "/projects/{project_id}/reddit/opportunities": { "get": { "summary": "List Reddit opportunities", "parameters": [{ "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OK" } } } }
  }
}