{
  "openapi": "3.1.0",
  "info": {
    "title": "Helios Gather API",
    "version": "1.0.0",
    "description": "Workspace-scoped read API and signed webhook events. See /docs/api for setup and security guidance."
  },
  "servers": [{ "url": "https://forms.lucionglobal.com" }],
  "security": [{ "BearerApiKey": [] }],
  "paths": {
    "/api/v1/forms": {
      "get": {
        "summary": "List forms in the API key workspace",
        "parameters": [
          {
            "name": "X-Gather-API-Version",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "const": "1" }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }
          },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Paginated forms" },
          "401": { "description": "Missing, expired, or revoked key" },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    },
    "/api/v1/forms/{formId}/responses": {
      "get": {
        "summary": "List submitted responses for a workspace form",
        "parameters": [
          { "name": "formId", "in": "path", "required": true, "schema": { "type": "string" } },
          {
            "name": "X-Gather-API-Version",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "const": "1" }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }
          },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Paginated submitted responses" },
          "403": { "description": "Required scope is missing" },
          "404": { "description": "Form is outside the API key workspace or does not exist" },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "hg_live_..." }
    }
  }
}