{
  "openapi": "3.1.0",
  "info": {
    "title": "Form 5500 Search API",
    "version": "1.0.0",
    "description": "Form 5500 Search is an independent research tool that ingests, normalizes, and scores the U.S. Department of Labor's public Form 5500 retirement- and welfare-plan filings (EFAST2), making plan assets, participants, service providers, and parsed investment holdings searchable for free."
  },
  "servers": [
    {
      "url": "https://form5500search.com"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Liveness / readiness",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Corpus loaded"
          },
          "503": {
            "description": "Warming up or busy"
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "summary": "Search Form 5500 filings",
        "operationId": "searchFilings",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Company, EIN, or plan name"
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Two-letter USPS state"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results"
          }
        }
      }
    },
    "/api/suggest": {
      "get": {
        "summary": "Typeahead suggestions",
        "operationId": "suggest",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "company",
                "custodian",
                "recordkeeper",
                "advisor",
                "provider",
                "cit",
                "holding"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Suggestion rows"
          }
        }
      }
    },
    "/api/plan/{ackId}": {
      "get": {
        "summary": "One filing by ACK_ID",
        "operationId": "getPlan",
        "parameters": [
          {
            "name": "ackId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plan, providers, DFEs, holdings"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP Streamable HTTP (JSON-RPC)",
        "operationId": "mcp",
        "responses": {
          "200": {
            "description": "JSON-RPC result"
          }
        }
      }
    }
  }
}