{
  "openapi": "3.1.0",
  "info": {
    "title": "What’s Trending API",
    "version": "1.0.0",
    "description": "Read source-backed customer-interest trends and evidence, or trigger a fresh social scan for an authenticated What’s Trending workspace."
  },
  "servers": [{ "url": "https://api.whatstrending.cc" }],
  "security": [{ "apiKey": [] }],
  "paths": {
    "/v1/workspace": {
      "get": {
        "operationId": "getWorkspace",
        "summary": "Get the configured market workspace",
        "responses": { "200": { "description": "Workspace configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } } }
      }
    },
    "/v1/trends": {
      "get": {
        "operationId": "getTrends",
        "summary": "Get ranked customer-interest trends",
        "parameters": [{ "name": "days", "in": "query", "schema": { "type": "integer", "enum": [7, 30, 90, 180, 365] } }],
        "responses": { "200": { "description": "Ranked trends", "content": { "application/json": { "schema": { "type": "object", "properties": { "windowDays": { "type": "integer" }, "trends": { "type": "array", "items": { "$ref": "#/components/schemas/Trend" } } } } } } }
      }
    },
    "/v1/evidence": {
      "get": {
        "operationId": "listEvidence",
        "summary": "List public source evidence and engagement",
        "parameters": [
          { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [0, 7, 30, 90, 180, 365] }, "description": "Use 0 for all stored evidence." },
          { "name": "platform", "in": "query", "schema": { "type": "string", "enum": ["reddit", "facebook", "instagram", "x"] } },
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }
        ],
        "responses": { "200": { "description": "Evidence posts", "content": { "application/json": { "schema": { "type": "object", "properties": { "windowDays": { "type": "integer" }, "total": { "type": "integer" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } } } }
      }
    },
    "/v1/scans": {
      "post": {
        "operationId": "runScan",
        "summary": "Run a fresh market scan",
        "description": "Runs the configured collectors and persists new source evidence. Agent-triggered scans are limited to one every 15 minutes per workspace.",
        "responses": { "201": { "description": "Scan completed" }, "429": { "description": "A recent scan already exists" } }
      }
    }
  },
  "components": {
    "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "wt_live_…" } },
    "schemas": {
      "WorkspaceResponse": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "productName": { "type": "string" }, "productUrl": { "type": "string", "format": "uri" }, "words": { "type": "array", "items": { "type": "string" } }, "competitorUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "lookbackDays": { "type": "integer" } } } } },
      "Trend": { "type": "object", "properties": { "id": { "type": "string" }, "topic": { "type": "string" }, "score": { "type": "integer" }, "status": { "type": "string" }, "mentions": { "type": "integer" }, "uniqueAuthors": { "type": "integer" }, "platforms": { "type": "array", "items": { "type": "string" } }, "engagement": { "type": "number" }, "summary": { "type": "string" }, "idea": { "type": "object" } } },
      "Post": { "type": "object", "properties": { "platform": { "type": "string" }, "id": { "type": "string" }, "authorHandle": { "type": "string" }, "text": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "commentsUrl": { "type": "string", "format": "uri" }, "publishedAt": { "type": "string", "format": "date-time" }, "matchedTerms": { "type": "array", "items": { "type": "string" } }, "metrics": { "type": "object", "additionalProperties": { "type": ["number", "null"] } } } }
    }
  }
}