{
  "openapi": "3.1.0",
  "info": {
    "title": "MentionDrop API",
    "version": "1.0.0",
    "description": "Account-scoped HTTP API for MentionDrop mentions, monitored keywords, digests, and reply drafts. Authenticate with an API key from the MentionDrop dashboard."
  },
  "servers": [{ "url": "https://www.mentiondrop.com" }],
  "security": [{ "apiKey": [] }, { "bearerAuth": [] }],
  "paths": {
    "/api/v1/me": {
      "get": {
        "summary": "Validate API key",
        "operationId": "getCurrentAccount",
        "responses": {
          "200": { "description": "Authenticated account and capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCapabilities" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/v1/mentions": {
      "get": {
        "summary": "List mentions",
        "operationId": "listMentions",
        "parameters": [
          { "name": "keyword", "in": "query", "description": "Keyword UUID filter (repeatable)", "schema": { "type": "string", "format": "uuid" }, "style": "form", "explode": true },
          { "name": "source", "in": "query", "schema": { "type": "string", "enum": ["firehose", "reddit", "brave", "google_news", "serper"] }, "style": "form", "explode": true },
          { "name": "sentiment", "in": "query", "schema": { "type": "string", "enum": ["positive", "neutral", "negative"] } },
          { "name": "content_type", "in": "query", "schema": { "$ref": "#/components/schemas/ContentType" } },
          { "name": "contact_found", "in": "query", "schema": { "type": "boolean" } },
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
        ],
        "responses": {
          "200": { "description": "Paginated mentions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MentionsResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/v1/mentions/{id}": {
      "get": {
        "summary": "Get mention",
        "operationId": "getMention",
        "parameters": [{ "$ref": "#/components/parameters/IdPath" }],
        "responses": { "200": { "description": "Mention", "content": { "application/json": { "schema": { "type": "object", "properties": { "mention": { "$ref": "#/components/schemas/Mention" } }, "required": ["mention"] } } } }, "404": { "$ref": "#/components/responses/NotFound" } }
      },
      "patch": {
        "summary": "Save mention feedback",
        "operationId": "updateMentionFeedback",
        "parameters": [{ "$ref": "#/components/parameters/IdPath" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MentionFeedbackInput" } } } },
        "responses": { "200": { "description": "Feedback saved" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/api/v1/keywords": {
      "get": { "summary": "List keywords", "operationId": "listKeywords", "responses": { "200": { "description": "Keywords", "content": { "application/json": { "schema": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "$ref": "#/components/schemas/Keyword" } } }, "required": ["keywords"] } } } } } },
      "post": { "summary": "Create keyword", "operationId": "createKeyword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeywordInput" } } } }, "responses": { "201": { "description": "Keyword created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Keyword already exists" } } }
    },
    "/api/v1/keywords/{id}": {
      "patch": { "summary": "Update keyword", "operationId": "updateKeyword", "parameters": [{ "$ref": "#/components/parameters/IdPath" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchKeywordInput" } } } }, "responses": { "200": { "description": "Keyword updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/api/v1/digest": {
      "get": { "summary": "Get grouped digest", "operationId": "getDigest", "responses": { "200": { "description": "Grouped digest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigestResponse" } } } } } }
    },
    "/api/v1/reply-drafts": {
      "post": { "summary": "Create reply draft", "operationId": "createReplyDraft", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReplyDraftInput" } } } }, "responses": { "201": { "description": "Draft created" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Mention is not processed enough for draft generation" } } }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" },
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "MentionDrop API key" }
    },
    "parameters": {
      "IdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
    },
    "responses": {
      "BadRequest": { "description": "Invalid request" },
      "Unauthorized": { "description": "Missing or invalid API key" },
      "Forbidden": { "description": "Plan or permission denied" },
      "NotFound": { "description": "Resource not found" }
    },
    "schemas": {
      "Plan": { "type": "string", "enum": ["free", "starter", "pro"] },
      "KeywordRole": { "type": "string", "enum": ["own_brand", "competitor", "industry"] },
      "ContentType": { "type": "string", "enum": ["article", "comment", "job_posting", "cv", "course", "documentation", "other"] },
      "AccountCapabilities": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": ["string", "null"], "format": "email" }, "plan": { "$ref": "#/components/schemas/Plan" } }, "required": ["id", "plan"] }, "capabilities": { "type": "object", "additionalProperties": true } }, "required": ["user", "capabilities"] },
      "Keyword": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "format": "uuid" }, "keyword": { "type": "string" }, "role": { "$ref": "#/components/schemas/KeywordRole" }, "context": { "type": ["string", "null"] }, "is_active": { "type": "boolean" }, "min_relevance": { "type": "integer" }, "mention_count_30d": { "type": ["integer", "null"] } }, "required": ["id", "keyword", "role", "is_active"] },
      "Mention": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "title": { "type": ["string", "null"] }, "summary": { "type": ["string", "null"] }, "sentiment": { "type": ["string", "null"], "enum": ["positive", "neutral", "negative", null] }, "relevance_score": { "type": ["number", "null"] }, "suggested_action": { "type": ["string", "null"] }, "source": { "type": ["string", "null"] }, "source_domain": { "type": ["string", "null"] }, "matched_at": { "type": ["string", "null"], "format": "date-time" }, "keywords": { "$ref": "#/components/schemas/Keyword" } } },
      "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": ["page", "limit", "hasNext", "hasPrev"] },
      "MentionsResponse": { "type": "object", "properties": { "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "redditLockedCount": { "type": "integer" } }, "required": ["mentions", "pagination"] },
      "CreateKeywordInput": { "type": "object", "properties": { "keyword": { "type": "string", "minLength": 2, "maxLength": 100 }, "context": { "type": ["string", "null"], "maxLength": 300 }, "role": { "$ref": "#/components/schemas/KeywordRole" } }, "required": ["keyword"] },
      "PatchKeywordInput": { "type": "object", "properties": { "is_active": { "type": "boolean" }, "context": { "type": ["string", "null"] }, "role": { "$ref": "#/components/schemas/KeywordRole" }, "excluded_content_types": { "type": "array", "items": { "$ref": "#/components/schemas/ContentType" } }, "exclusion_terms": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "min_relevance": { "type": "integer", "minimum": 0, "maximum": 100 } } },
      "MentionFeedbackInput": { "type": "object", "properties": { "verdict": { "type": ["string", "null"], "enum": ["relevant", "not_relevant", null] }, "user_feedback": { "type": ["string", "null"], "enum": ["relevant", "not_relevant", null] } } },
      "DigestResponse": { "type": "object", "properties": { "sections": { "type": "object", "properties": { "owned_brand_mentions": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" } }, "competitor_signals": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" } }, "demand_signals": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" } }, "conversations_worth_replying_to": { "type": "array", "items": { "$ref": "#/components/schemas/Mention" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": ["sections", "pagination"] },
      "CreateReplyDraftInput": { "type": "object", "properties": { "mention_id": { "type": "string", "format": "uuid" }, "draft_intent": { "type": "string", "enum": ["reply", "outreach_email"], "default": "reply" } }, "required": ["mention_id"] }
    }
  }
}