{
  "openapi": "3.1.0",
  "info": {
    "title": "Pattflow SEO Traffic Intelligence API",
    "version": "0.1.0",
    "description": "API for SEO opportunity discovery, game-site SOP briefs, GEO content linting, page audits, site audits and competitor structure reverse engineering."
  },
  "servers": [
    {
      "url": "https://seo.pattflow.xyz"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Service health",
        "responses": {
          "200": {
            "description": "Service health and auth mode"
          }
        }
      }
    },
    "/api/v1/source-status": {
      "get": {
        "summary": "Probe source freshness",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Source freshness status"
          }
        }
      }
    },
    "/api/v1/hot-board": {
      "post": {
        "summary": "Build a feed-first opportunity board.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/probe/run": {
      "post": {
        "summary": "Force a fresh live opportunity probe.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/discover": {
      "post": {
        "summary": "Discover demand candidates from seeds.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/batch-discover": {
      "post": {
        "summary": "Compare demand candidates across multiple seeds.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/analyze": {
      "post": {
        "summary": "Analyze relative SERP flow and opportunity gaps.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/site-plan": {
      "post": {
        "summary": "Turn analysis into a buildable site plan.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/report": {
      "post": {
        "summary": "Generate a full SEO opportunity report.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/game-site-brief": {
      "post": {
        "summary": "Generate a game-site SOP brief with keyword, page and review gates.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/geo-content-lint": {
      "post": {
        "summary": "Lint page content for answer-first GEO readiness.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/page-audit": {
      "post": {
        "summary": "Audit a page for publish readiness.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/site-audit": {
      "post": {
        "summary": "Audit a small site for page and indexability gates.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/drift-check": {
      "post": {
        "summary": "Compare current site state against a previous audit snapshot.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/template-reverse": {
      "post": {
        "summary": "Reverse SERP template patterns without a target site.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/competitor-structure-reverse": {
      "post": {
        "summary": "Compare a target site against SERP structure patterns.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON report"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    }
  }
}