{
  "openapi": "3.0.3",
  "info": {
    "title": "vaers.globalpatientsafety.com signals API",
    "version": "1.0.0",
    "description": "VAERS (vaccine, event) pairs from https://vaers.globalpatientsafety.com/signals.\n\nVAERS reports are voluntary. Counts are reporting, not incidence. Disproportionate reporting is a hypothesis, not evidence of causation.\n\n`n` is the sum of quarterly observed counts. Those windows overlap, so `n` is not a count of unique reports. `eb05` is the peak quarterly EB05.\n\n`vaccine` and `drug` are the same parameter (the VAERS vaccine name). There is no FDA-label, PDF, novelty, or substance route. `format=label` and `format=pdf` return 400.\n\nHuman docs: https://vaers.globalpatientsafety.com/API.md",
    "contact": {
      "url": "https://vaers.globalpatientsafety.com/"
    }
  },
  "externalDocs": {
    "description": "Human API.md",
    "url": "https://vaers.globalpatientsafety.com/API.md"
  },
  "servers": [
    {
      "url": "https://vaers.globalpatientsafety.com"
    }
  ],
  "tags": [
    {
      "name": "signals",
      "description": "GET /signals"
    }
  ],
  "paths": {
    "/signals": {
      "get": {
        "tags": ["signals"],
        "operationId": "getSignals",
        "summary": "VAERS vaccine × event pairs",
        "description": "Requires `vaccine` and/or `event`, or `q`. Default body is a JSON array of pairs.\n\nFormats: omit or `json` (pair list); `csv`; `series` (one pair's quarters); `profile`; `class` (same vaccine type); `brief` (markdown, text/plain).\n\n`format=label` and `format=pdf` are rejected with 400 and an allowed list. An unknown name returns 200 and an empty list.",
        "parameters": [
          {
            "name": "vaccine",
            "in": "query",
            "required": false,
            "description": "VAERS vaccine name, or an exact type such as COVID19 (expands to every product of that type). Same field as `drug`.",
            "schema": {"type": "string", "example": "COVID19"}
          },
          {
            "name": "drug",
            "in": "query",
            "required": false,
            "description": "Alias of `vaccine`. If both are set they must be identical.",
            "schema": {"type": "string"}
          },
          {
            "name": "event",
            "in": "query",
            "required": false,
            "description": "MedDRA preferred term.",
            "schema": {"type": "string", "example": "Myocarditis"}
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Union of vaccine-name matches and event-name matches.",
            "schema": {"type": "string"}
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["json", "csv", "series", "profile", "brief", "class"],
              "default": "json"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "eb05 (default), n, or latest. trend is rejected. This service does not derive a trend.",
            "schema": {
              "type": "string",
              "enum": ["eb05", "n", "latest"],
              "default": "eb05"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["asc", "desc"],
              "default": "desc"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50}
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {"type": "integer", "minimum": 0, "default": 0}
          },
          {
            "name": "min_eb05",
            "in": "query",
            "required": false,
            "description": "Keep pairs whose peak EB05 is at least this number. Applied after the aggregate. A non-number is HTTP 400.",
            "schema": {"type": "number", "minimum": 0}
          },
          {
            "name": "min_n",
            "in": "query",
            "required": false,
            "description": "Keep pairs whose n is at least this number. Applied after the aggregate. A non-number is HTTP 400.",
            "schema": {"type": "number", "minimum": 0}
          }
        ],
        "responses": {
          "200": {
            "description": "JSON array of pairs, or a profile/series/class object. `format=brief` is text/plain. `format=csv` is text/csv.",
            "headers": {
              "X-Total-Count": {"schema": {"type": "integer"}},
              "X-Limit": {"schema": {"type": "integer"}},
              "X-Offset": {"schema": {"type": "integer"}},
              "X-VAERS-Through": {"schema": {"type": "string"}},
              "X-VAERS-Build": {"schema": {"type": "string"}, "description": "api-<12 hex> src-<deployed sha>"},
              "X-VAERS-Hypothesis": {"schema": {"type": "string"}}
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {"type": "array", "items": {"$ref": "#/components/schemas/Pair"}},
                    {"$ref": "#/components/schemas/Profile"},
                    {"$ref": "#/components/schemas/Series"},
                    {"$ref": "#/components/schemas/ClassResult"}
                  ]
                }
              },
              "text/plain": {"schema": {"type": "string"}},
              "text/csv": {"schema": {"type": "string"}}
            }
          },
          "400": {
            "description": "Missing query, unknown format, vaccine/drug disagree, or query too short.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Error"}
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pair": {
        "type": "object",
        "required": ["vaccine", "drug", "vax_name", "vax_type", "event", "n", "emerging"],
        "properties": {
          "vaccine": {"type": "string"},
          "drug": {"type": "string", "description": "Same string as vaccine and vax_name."},
          "vax_name": {"type": "string", "description": "VAX_NAME. Same string as vaccine. Not the vaccine type."},
          "vax_type": {"type": "string"},
          "event": {"type": "string"},
          "n": {"type": "integer", "description": "Sum of quarterly observed counts. Not unique reports. n_unique is not in this extract."},
          "eb05": {"type": "number", "nullable": true, "description": "Peak quarterly EB05 among flagged quarters (raw, not EWMA). Same number as Peak EB05 in the app."},
          "eb05_peak_pre2021": {"type": "number", "nullable": true, "description": "Highest quarterly EB05 before 2021Q1 on the full series. Null if the pair has no pre-2021 quarter."},
          "eb05_peak_pre2021_quarter": {"type": "string", "nullable": true, "description": "Earliest quarter that attains eb05_peak_pre2021."},
          "eb05_peak_quarter": {"type": "string", "nullable": true, "description": "Earliest quarter that attains the full-series maximum EB05."},
          "peak_in_covid_era": {"type": "boolean", "description": "True when vax_type is not COVID19 and eb05_peak_quarter is inside 2021Q1-2022Q4."},
          "background_note": {"type": "string", "nullable": true, "description": "One sentence on COVID-era background distortion. Not a rescaled EB05."},
          "ewma_eb05": {"type": "number", "nullable": true},
          "n_methods_max": {"type": "integer"},
          "quarters_flagged": {"type": "integer"},
          "first_quarter": {"type": "string"},
          "latest_quarter": {"type": "string"},
          "emerging": {"type": "boolean"}
        }
      },
      "Profile": {
        "type": "object",
        "properties": {
          "query": {"type": "string"},
          "kind": {"type": "string", "enum": ["vaccine", "event", "pair"]},
          "vaers_through": {"type": "string", "nullable": true},
          "n_pairs": {"type": "integer"},
          "returned": {"type": "integer"},
          "hypothesis": {"type": "string"},
          "pairs": {"type": "array", "items": {"$ref": "#/components/schemas/Pair"}}
        }
      },
      "Series": {
        "type": "object",
        "properties": {
          "vaccine": {"type": "string"},
          "drug": {"type": "string"},
          "vax_type": {"type": "string"},
          "event": {"type": "string"},
          "vaers_through": {"type": "string", "nullable": true},
          "hypothesis": {"type": "string"},
          "n_pairs_matched": {"type": "integer"},
          "note": {"type": "string"},
          "quarters": {"type": "array", "items": {"type": "object"}}
        }
      },
      "ClassResult": {
        "type": "object",
        "properties": {
          "vax_type": {"type": "array", "items": {"type": "string"}},
          "vaccines": {"type": "array", "items": {"type": "string"}},
          "event": {"type": "string", "nullable": true},
          "vaers_through": {"type": "string", "nullable": true},
          "n_pairs": {"type": "integer"},
          "hypothesis": {"type": "string"},
          "pairs": {"type": "array", "items": {"$ref": "#/components/schemas/Pair"}}
        }
      },
      "Error": {
        "type": "object",
        "required": ["error", "hypothesis"],
        "properties": {
          "error": {"type": "string"},
          "hypothesis": {"type": "string"},
          "allowed": {"type": "array", "items": {"type": "string"}},
          "usage": {"type": "string"}
        }
      }
    }
  }
}