{
  "openapi": "3.1.0",
  "info": {
    "title": "Spytrend Agent API",
    "version": "1.0.0",
    "description": "Read-only API that AI agents use to query Spytrend, an advertising analytics platform for Meta and TikTok (about 280M new ads every month, with everything one advertiser runs gathered into a single record). This is the cherry-picked, agent-facing surface; access is via the MCP server (https://mcp.spytrend.com/mcp) secured with OAuth 2.1 + PKCE. Admin and internal endpoints are intentionally not exposed.",
    "contact": { "name": "Spytrend", "url": "https://spytrend.com" }
  },
  "servers": [
    { "url": "https://mcp.spytrend.com", "description": "MCP-fronted access (OAuth 2.1)" }
  ],
  "security": [ { "oauth2": [ "mcp:read" ] } ],
  "tags": [
    { "name": "ads", "description": "Search and fetch ads" },
    { "name": "trends", "description": "Aggregated trend rankings" },
    { "name": "entities", "description": "Advertisers, webmasters and creatives" }
  ],
  "paths": {
    "/api/v1/ads": {
      "get": {
        "tags": [ "ads" ],
        "operationId": "searchAds",
        "summary": "Search ads",
        "description": "Search ads with filters. To find ads on a specific landing domain (incl. subdomains) use landing_domain, not the free-text q.",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free-text keyword in title, body or link." },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "ISO country code (e.g. US, BR, DE)." },
          { "name": "platforms", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Platform names (e.g. facebook, instagram)." },
          { "name": "creative_categories", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "AI category slugs, e.g. gambling_and_betting, finance_and_banking, dating_and_relationships, ecommerce_and_retail, healthcare_and_medical." },
          { "name": "status_today", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive" ] }, "description": "Current ad status." },
          { "name": "advertiser_id", "in": "query", "schema": { "type": "string" }, "description": "Filter to one advertiser." },
          { "name": "webmaster_id", "in": "query", "schema": { "type": "string" }, "description": "Filter to one webmaster." },
          { "name": "landing_domain", "in": "query", "schema": { "type": "string" }, "description": "Exact landing domain incl. subdomains (e.g. tv.kukufm.com)." },
          { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "date", "days_active", "activity_days_amount", "most_popular", "impressions" ] }, "description": "Sort field (impressions requires a narrowing filter)." },
          { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor from a prior response." }
        ],
        "responses": { "200": { "description": "Matching ads + pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsPage" } } } } }
      }
    },
    "/api/v1/ads/{id}": {
      "get": {
        "tags": [ "ads" ],
        "operationId": "getAd",
        "summary": "Get one ad by id",
        "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "responses": { "200": { "description": "Ad", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/v1/analytics/trends/{dimension}": {
      "get": {
        "tags": [ "trends" ],
        "operationId": "getTrends",
        "summary": "Aggregated trend rankings",
        "description": "Ranked rows for the chosen dimension.",
        "parameters": [
          { "name": "dimension", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "geo", "advertisers/cards", "webmasters", "apps", "timeline", "scaling-creatives" ] } },
          { "name": "country", "in": "query", "schema": { "type": "string" } },
          { "name": "platform", "in": "query", "schema": { "type": "string" } },
          { "name": "ai_category", "in": "query", "schema": { "type": "string" } },
          { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": { "200": { "description": "Ranked rows", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/v1/advertisers/autocomplete": {
      "get": {
        "tags": [ "entities" ],
        "operationId": "searchAdvertisers",
        "summary": "Search advertisers by name",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": { "200": { "description": "Advertisers", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/v1/webmasters": {
      "get": {
        "tags": [ "entities" ],
        "operationId": "searchWebmasters",
        "summary": "Search webmasters (affiliates)",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": { "200": { "description": "Webmasters", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/v1/webmasters/{id}": {
      "get": {
        "tags": [ "entities" ],
        "operationId": "getWebmaster",
        "summary": "Get one webmaster by id",
        "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "responses": { "200": { "description": "Webmaster", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/v1/creo": {
      "get": {
        "tags": [ "entities" ],
        "operationId": "searchCreatives",
        "summary": "Search unique creatives (deduplicated ad media)",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Creatives", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1 + PKCE. Metadata: https://mcp.spytrend.com/.well-known/oauth-authorization-server",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://mcp.spytrend.com/oauth2/auth",
            "tokenUrl": "https://mcp.spytrend.com/oauth2/token",
            "scopes": { "mcp:read": "Read-only access to the data tools" }
          }
        }
      }
    },
    "schemas": {
      "AdsPage": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ad" } },
          "pagination": {
            "type": "object",
            "properties": {
              "next_cursor": { "type": "string" },
              "has_more": { "type": "boolean" },
              "total": { "type": "integer" },
              "total_estimated": { "type": "boolean" }
            }
          }
        }
      },
      "Ad": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "body": { "type": "string" },
          "landing_domain": { "type": "string" },
          "platform_name": { "type": "string" },
          "advertiser_id": { "type": "string" },
          "webmaster_id": { "type": "string" },
          "status_today": { "type": "string" },
          "days_active": { "type": "integer" },
          "first_seen_date": { "type": "string" },
          "last_seen_date": { "type": "string" },
          "countries": { "type": "array", "items": { "type": "string" } },
          "languages": { "type": "array", "items": { "type": "string" } },
          "categories": { "type": "array", "items": { "type": "string" } },
          "creative_format": { "type": "string" },
          "media_count": { "type": "integer" }
        }
      }
    }
  }
}