{
  "openapi": "3.1.0",
  "info": {
    "title": "REVEX Data API",
    "version": "1.0.0",
    "description": "Read-only, organization-scoped access to your REVEX catalog, reviews, partnerships and trust-seal analytics."
  },
  "servers": [
    {
      "url": "https://reviewexchange.io/api/public/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "revex_*"
      }
    }
  },
  "paths": {
    "/summary": {
      "get": {
        "summary": "Organization snapshot",
        "description": "Scope: analytics:read",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "Key lacks the required scope"
          },
          "429": {
            "description": "Rate limited (600 requests / 5 minutes)"
          }
        }
      }
    },
    "/products": {
      "get": {
        "summary": "List catalog products",
        "description": "Scope: products:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 1
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "Key lacks the required scope"
          },
          "429": {
            "description": "Rate limited (600 requests / 5 minutes)"
          }
        }
      }
    },
    "/reviews": {
      "get": {
        "summary": "List reviews",
        "description": "Scope: reviews:read",
        "parameters": [
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "received",
                "owned"
              ],
              "default": "received"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 1
            }
          },
          {
            "name": "product",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_rating",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "Key lacks the required scope"
          },
          "429": {
            "description": "Rate limited (600 requests / 5 minutes)"
          }
        }
      }
    },
    "/partnerships": {
      "get": {
        "summary": "List partnerships",
        "description": "Scope: partnerships:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 1
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "Key lacks the required scope"
          },
          "429": {
            "description": "Rate limited (600 requests / 5 minutes)"
          }
        }
      }
    },
    "/badge-analytics": {
      "get": {
        "summary": "Trust-seal impressions and clicks",
        "description": "Scope: analytics:read",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 180,
              "default": 30
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            }
          },
          {
            "name": "group",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "daily",
                "products",
                "product_variants"
              ],
              "default": "daily"
            }
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "Key lacks the required scope"
          },
          "429": {
            "description": "Rate limited (600 requests / 5 minutes)"
          }
        }
      }
    }
  }
}