{
  "openapi": "3.1.0",
  "info": {
    "title": "Behar AI API",
    "description": "API for monitoring and improving brand visibility across AI search engines (ChatGPT, Perplexity, Gemini, Claude, DeepSeek). Track presence scores, competitor rankings, content gaps, and trigger analysis runs.",
    "version": "1.0.0",
    "contact": { "email": "hello@behar.ai" }
  },
  "servers": [{ "url": "https://behar.ai/api/v1" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from Settings > API Keys in the Behar dashboard. Requires Advanced plan or above."
      }
    }
  },
  "paths": {
    "/projects": {
      "get": {
        "operationId": "listProjects",
        "summary": "List all projects in the workspace",
        "description": "Returns all projects (brands) being monitored for AI visibility.",
        "responses": {
          "200": {
            "description": "List of projects",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "projects": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string", "description": "Brand name" },
                          "domain": { "type": "string", "description": "Brand website domain" },
                          "industry": { "type": "string" },
                          "lastRunAt": { "type": "string", "format": "date-time", "nullable": true },
                          "createdAt": { "type": "string", "format": "date-time" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createProject",
        "summary": "Create a new project",
        "description": "Creates a new brand/project to monitor for AI visibility.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "domain", "industry"],
                "properties": {
                  "name": { "type": "string", "description": "Brand name, e.g. 'Acme Inc'" },
                  "domain": { "type": "string", "description": "Brand website domain, e.g. 'acme.com'" },
                  "industry": { "type": "string", "description": "Industry category, e.g. 'SaaS / Software'" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Project created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "project": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string" },
                        "name": { "type": "string" },
                        "domain": { "type": "string" },
                        "industry": { "type": "string" },
                        "createdAt": { "type": "string", "format": "date-time" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/projects/{id}": {
      "get": {
        "operationId": "getProject",
        "summary": "Get project details",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "Project details including active LLMs and market configuration"
          }
        }
      }
    },
    "/projects/{id}/prompts": {
      "get": {
        "operationId": "listPrompts",
        "summary": "List tracked prompts for a project",
        "description": "Returns all prompts (search queries) being monitored. These are the questions users ask AI models, e.g. 'best CRM for startups'.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor from previous response" }
        ],
        "responses": {
          "200": {
            "description": "List of prompts with pagination",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prompts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "text": { "type": "string", "description": "The prompt/query being tracked" },
                          "status": { "type": "string" },
                          "orderIndex": { "type": "integer" },
                          "createdAt": { "type": "string", "format": "date-time" }
                        }
                      }
                    },
                    "cursor": { "type": "string", "nullable": true },
                    "hasMore": { "type": "boolean" }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createPrompt",
        "summary": "Add a prompt to track",
        "description": "Adds a new search query/prompt to monitor across AI models for this project.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string", "description": "The prompt/query to track, e.g. 'best CRM for startups'" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Prompt created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prompt": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string" },
                        "text": { "type": "string" },
                        "createdAt": { "type": "string", "format": "date-time" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/projects/{id}/prompts/{promptId}": {
      "delete": {
        "operationId": "deletePrompt",
        "summary": "Delete a tracked prompt",
        "description": "Removes a prompt from the project. Future runs will no longer include this prompt.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project ID" },
          { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Prompt ID to delete" }
        ],
        "responses": {
          "200": {
            "description": "Prompt deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/projects/{id}/competitors": {
      "get": {
        "operationId": "listCompetitors",
        "summary": "List competitors being tracked",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "List of competitors with their domains"
          }
        }
      },
      "post": {
        "operationId": "addCompetitor",
        "summary": "Add a competitor to track",
        "description": "Adds a competitor brand to compare visibility against in analysis runs.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "domain"],
                "properties": {
                  "name": { "type": "string", "description": "Competitor brand name" },
                  "domain": { "type": "string", "description": "Competitor website domain" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Competitor added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "competitor": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string" },
                        "name": { "type": "string" },
                        "domain": { "type": "string" },
                        "createdAt": { "type": "string", "format": "date-time" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/projects/{id}/gaps": {
      "get": {
        "operationId": "listContentGaps",
        "summary": "List content gaps where competitors outrank you",
        "description": "Returns prompts where your brand scores lower than competitors, ranked by priority. Each gap includes the prompt text, your score, the top competitor's score, affected LLMs, and gap type (absent, losing, declining, new_opportunity).",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "List of content gaps sorted by priority score",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "gaps": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "promptText": { "type": "string" },
                          "gapType": { "type": "string", "enum": ["absent", "losing", "declining", "new_opportunity"] },
                          "brandScore": { "type": "integer", "description": "Your brand's score (0-100)" },
                          "topCompetitorName": { "type": "string", "nullable": true },
                          "topCompetitorScore": { "type": "integer", "nullable": true },
                          "affectedLlms": { "type": "array", "items": { "type": "string" } },
                          "priorityScore": { "type": "integer", "description": "Gap priority (higher = more urgent)" },
                          "status": { "type": "string", "enum": ["open", "closed"] }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/projects/{id}/content": {
      "get": {
        "operationId": "listContent",
        "summary": "List generated content pieces",
        "description": "Returns AI-generated content pieces (blog posts, FAQ pages, landing copy) created to improve visibility on specific prompts.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "List of content pieces with their status and score impact"
          }
        }
      }
    },
    "/projects/{id}/runs": {
      "get": {
        "operationId": "listRuns",
        "summary": "List analysis runs",
        "description": "Returns history of analysis runs — each run queries all active LLMs with all tracked prompts and scores the results.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "List of runs with status and prompt counts"
          }
        }
      },
      "post": {
        "operationId": "triggerRun",
        "summary": "Trigger a new analysis run",
        "description": "Starts a new analysis run that queries all active LLMs with all tracked prompts and scores the results. Returns the run ID for polling status.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "201": {
            "description": "Run started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "runId": { "type": "string", "description": "ID of the started run" },
                    "total": { "type": "integer", "description": "Total number of prompt-LLM combinations to process" },
                    "status": { "type": "string", "enum": ["running", "queued"] }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/projects/{id}/runs/{runId}": {
      "get": {
        "operationId": "getRunDetails",
        "summary": "Get detailed results for a specific run",
        "description": "Returns per-prompt, per-LLM results for a specific analysis run, including scores, mentions, positions, and sentiment.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Run details with individual prompt results per LLM"
          }
        }
      }
    }
  }
}