{
  "openapi": "3.1.0",
  "info": {
    "title": "HearBuyers API",
    "version": "1.0.0",
    "description": "Read the buyers HearBuyers finds for your project on Reddit and X, manage what it listens for, and draft replies. Every key belongs to one project. Rate limit per key: Pro 60 requests a minute, Ultra 300; over it the API answers 429 with Retry-After. A project without a live plan answers 402 plan_inactive. Errors look like {\"error\": \"<code>\", \"message\": \"<text>\"}."
  },
  "security": [{ "bearer": [] }],
  "components": {
    "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "hb_live_ followed by 32 characters, made in the app under API." } },
    "schemas": {
      "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } },
      "Match": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "source": { "type": "string", "enum": ["x", "reddit"] },
          "community": { "type": "string" },
          "authorHandle": { "type": "string" },
          "postedAt": { "type": "string", "format": "date-time" },
          "score": { "type": "integer" },
          "intent": { "type": "string", "enum": ["actively_looking", "comparing", "complaining", "just_curious"] },
          "stage": { "type": "string", "enum": ["open", "replied", "won", "not_a_fit", "dismissed"] },
          "keySentence": { "type": "string" },
          "hasDraft": { "type": "boolean" },
          "listenerIds": { "type": "array", "items": { "type": "string" } }
        }
      },
      "ListenerInput": {
        "type": "object",
        "required": ["type"],
        "properties": {
          "type": { "type": "string", "enum": ["keywords", "subreddit", "x_account", "x_mentions", "tweet_replies", "reddit_thread", "competitor"] },
          "name": { "type": "string" },
          "sources": { "type": "array", "items": { "type": "string", "enum": ["x", "reddit"] } },
          "terms": { "type": "array", "items": { "type": "string" } },
          "target": { "type": "string" },
          "excludeWords": { "type": "array", "items": { "type": "string" } }
        }
      }
    },
    "responses": {
      "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  },
  "paths": {
    "/v1/matches": {
      "get": {
        "summary": "List buyers found (matches)",
        "parameters": [
          { "name": "stage", "in": "query", "schema": { "type": "string", "enum": ["open", "replied", "won", "not_a_fit", "dismissed", "closed", "all"], "default": "open" } },
          { "name": "source", "in": "query", "schema": { "type": "string", "enum": ["x", "reddit"] } },
          { "name": "minScore", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100 }, "description": "Defaults to the project's threshold." },
          { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["new", "score"], "default": "new" }, "description": "new is the newest post first; score is the best score first, newest first among equals." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 50 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor from the previous page." }
        ],
        "responses": {
          "200": { "description": "A page of matches", "content": { "application/json": { "schema": { "type": "object", "properties": {
            "items": { "type": "array", "items": { "$ref": "#/components/schemas/Match" } },
            "total": { "type": "integer" }, "threshold": { "type": "integer" }, "nextCursor": { "type": ["string", "null"] },
            "counts": { "type": "object", "additionalProperties": { "type": "integer" } } } } } } },
          "default": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/matches/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
      "get": { "summary": "One match with the post, author, drafts and history", "responses": { "200": { "description": "The match" }, "default": { "$ref": "#/components/responses/Error" } } },
      "patch": {
        "summary": "Move a match to a stage, or mark it not relevant with a reason (teaches the scorer)",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {
          "stage": { "type": "string", "enum": ["open", "replied", "won", "not_a_fit", "dismissed"] },
          "feedback": { "type": "string", "enum": ["not_a_buyer", "wrong_topic", "self_promo", "vendor", "other"] },
          "note": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Updated" }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/matches/{id}/drafts": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
      "post": {
        "summary": "Write a fresh draft (approved drafts are kept)",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["kind"], "properties": { "kind": { "type": "string", "enum": ["reply", "dm", "email"] } } } } } },
        "responses": { "200": { "description": "The draft" }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/listeners": {
      "get": { "summary": "What the project listens for, with plan usage", "responses": { "200": { "description": "Listeners" }, "default": { "$ref": "#/components/responses/Error" } } },
      "post": {
        "summary": "Add a listener (starts a scan). Over the plan's limit answers 402 plan_limit.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListenerInput" } } } },
        "responses": { "201": { "description": "Created" }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/listeners/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
      "delete": { "summary": "Remove a listener (its matches stay)", "responses": { "204": { "description": "Removed" }, "default": { "$ref": "#/components/responses/Error" } } }
    },
    "/v1/leads": {
      "get": {
        "summary": "People who showed buying intent, one row per author",
        "parameters": [
          { "name": "platform", "in": "query", "schema": { "type": "string", "enum": ["x", "reddit"] } },
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 200 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "Leads" }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/brand-signals": {
      "get": {
        "summary": "Mentions of your brand and competitors, with share of voice and sentiment",
        "parameters": [
          { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 365 } },
          { "name": "brand", "in": "query", "schema": { "type": "string" } },
          { "name": "sentiment", "in": "query", "schema": { "type": "string", "enum": ["positive", "neutral", "negative"] } }
        ],
        "responses": { "200": { "description": "Brand signals" }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/overview": {
      "get": {
        "summary": "Buyers found, replied, won and what is waiting, over the last days",
        "parameters": [{ "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 365 } }],
        "responses": { "200": { "description": "Overview" }, "default": { "$ref": "#/components/responses/Error" } }
      }
    }
  }
}
