{
  "openapi": "3.1.0",
  "info": {
    "title": "XiaoFlow Keyword Intelligence API",
    "description": "API for real-time search volume, Google Ads metrics, CPC pricing, and category trends.",
    "version": "1.0.0",
    "x-guidance": "Use this API to query search volume, CPC, competition index, and historical trends for keywords.",
    "x-payment-info": {
      "protocols": [
        { "mpp": { "method": "stripe", "currency": "USD" } },
        { "x402": { "currency": "USD", "network": "base" } }
      ],
      "price": {
        "mode": "fixed",
        "currency": "USD",
        "amount": "0.01"
      }
    }
  },
  "servers": [
    {
      "url": "https://www.xiaoflow.com/api/v1",
      "description": "Production API Server"
    }
  ],
  "paths": {
    "/keywords": {
      "get": {
        "summary": "Search keywords",
        "operationId": "searchKeywords",
        "x-payment-info": {
          "protocols": [
            { "mpp": { "method": "stripe", "currency": "USD" } },
            { "x402": { "currency": "USD", "network": "base" } }
          ],
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.01"
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "country",
            "in": "query",
            "schema": { "type": "string", "default": "US" }
          }
        ],
        "responses": {
          "200": {
            "description": "Keywords with search metrics and trends"
          },
          "402": {
            "description": "Payment Required"
          }
        }
      }
    },
    "/keywords/autocomplete": {
      "post": {
        "summary": "Multi-engine autocomplete keyword expansion",
        "operationId": "autocompleteKeywords",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["keyword"],
                "properties": {
                  "keyword": { "type": "string" },
                  "engine": { "type": "string", "default": "google" },
                  "country": { "type": "string", "default": "US" },
                  "language": { "type": "string", "default": "en" },
                  "include_metrics": { "type": "boolean", "default": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Grouped autocomplete suggestions with metrics"
          }
        }
      }
    },
    "/keywords/bing/suggestions": {
      "get": {
        "summary": "Bing Ads keyword suggestions & CPC",
        "operationId": "getBingSuggestions",
        "parameters": [
          { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "country_code", "in": "query", "schema": { "type": "string", "default": "US" } },
          { "name": "language", "in": "query", "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": {
            "description": "Bing Ads suggestions with volume and CPC"
          }
        }
      }
    },
    "/keywords/pinterest/trending": {
      "get": {
        "summary": "Pinterest trending searches & growth curves",
        "operationId": "getPinterestTrending",
        "parameters": [
          { "name": "country", "in": "query", "schema": { "type": "string", "default": "US" } }
        ],
        "responses": {
          "200": {
            "description": "Trending topics and curves"
          }
        }
      }
    },
    "/keywords/pinterest/country-metrics": {
      "get": {
        "summary": "Pinterest country keyword metrics",
        "operationId": "getPinterestCountryMetrics",
        "parameters": [
          { "name": "keywords", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "country", "in": "query", "schema": { "type": "string", "default": "US" } }
        ],
        "responses": {
          "200": {
            "description": "Audience metrics and demographics"
          }
        }
      }
    },
    "/keywords/reddit/suggestions": {
      "get": {
        "summary": "Reddit Ads keyword recommendations",
        "operationId": "getRedditSuggestions",
        "parameters": [
          { "name": "keywords", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "country", "in": "query", "schema": { "type": "string", "default": "US" } }
        ],
        "responses": {
          "200": {
            "description": "Reddit keyword ideas and monthly views"
          }
        }
      }
    }
  }
}
