{
  "openapi": "3.0.3",
  "info": {
    "title": "faers.mobi signals API",
    "version": "1.0.0",
    "description": "Isolated FAERS (drug, event) pairs from https://faers.mobi/signals.\n\nFAERS disproportionality is a **hypothesis**, not causation. Always read `n`, `eb05`, and `trend`. Isolation is exact / prefix / substring (drugs also same-substance family). Fuzzy near-matches are omitted.\n\nHuman docs: https://faers.mobi/API.md",
    "contact": {
      "url": "https://faers.mobi/"
    }
  },
  "externalDocs": {
    "description": "Human API.md",
    "url": "https://faers.mobi/API.md"
  },
  "servers": [
    {
      "url": "https://faers.mobi"
    }
  ],
  "tags": [
    {
      "name": "signals",
      "description": "GET /signals isolation, formats, and filters"
    }
  ],
  "paths": {
    "/signals": {
      "get": {
        "tags": [
          "signals"
        ],
        "operationId": "getSignals",
        "summary": "Isolated FAERS (drug, event) pairs",
        "description": "Requires `drug` and/or `event`. Default body is a JSON array of pairs.\n\nFormats: omit or `json` (pair list); `csv`; `series` (needs drug AND event); `profile` (needs drug or event); `class` (needs drug); `brief` (needs drug or event, Markdown RWE brief served as text/plain); `pdf` (needs drug or event, same brief as Typst PDF); `label` (needs drug AND event, cached FDA-label Novel status).\n\nExamples:\n- Pair series: `/signals?drug=tzield&event=Nausea&format=series`\n- Pair brief: `/signals?drug=tzield&event=Nausea&format=brief`\n- Event brief: `/signals?event=Nausea&format=brief`\n- Pair PDF: `/signals?drug=tzield&event=Nausea&format=pdf`\n- Event PDF: `/signals?event=Nausea&format=pdf`\n- Event profile: `/signals?event=Nausea&format=profile`\n- Label status: `/signals?drug=tzield&event=Nausea&format=label`\n\nRanking / top-signals asks: add `indication=hide&low_info=hide` (default list order is unchanged and may lead with an indication PT), or use `format=profile` / `format=brief`, whose tops already exclude both. Every list row carries `indication` and `low_info` booleans.\n\nAn unrecognised `format=` value returns 400 with `error`, `allowed` and `usage`; it does not fall back to the pair list. `format=brief` is Markdown served as text/plain by design.",
        "parameters": [
          {
            "$ref": "#/components/parameters/drug"
          },
          {
            "$ref": "#/components/parameters/event"
          },
          {
            "$ref": "#/components/parameters/q"
          },
          {
            "$ref": "#/components/parameters/format"
          },
          {
            "$ref": "#/components/parameters/trend"
          },
          {
            "$ref": "#/components/parameters/novel"
          },
          {
            "$ref": "#/components/parameters/indication"
          },
          {
            "$ref": "#/components/parameters/low_info"
          },
          {
            "$ref": "#/components/parameters/product_type"
          },
          {
            "$ref": "#/components/parameters/medication_error"
          },
          {
            "$ref": "#/components/parameters/min_eb05"
          },
          {
            "$ref": "#/components/parameters/min_n"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "$ref": "#/components/parameters/sort"
          },
          {
            "$ref": "#/components/parameters/order"
          }
        ],
        "responses": {
          "200": {
            "description": "Isolated result. JSON array of pairs by default; object for profile/class; markdown for brief; PDF for format=pdf (same brief, Typst); CSV when format=csv. X-Total-Count is the isolated set size after filters (scan ceiling 5000).",
            "headers": {
              "X-Total-Count": {
                "schema": {
                  "type": "integer"
                },
                "description": "Rows after filters (scan ceiling 5000). For series: isolated pairs, not quarters. For profile: n_pairs."
              },
              "X-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Offset": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-FAERS-Through": {
                "schema": {
                  "type": "string",
                  "example": "2025Q4"
                },
                "description": "Latest FAERS quarter in the live extract (max quarter in the signal store)."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Pair"
                      }
                    },
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Series"
                      }
                    },
                    {
                      "$ref": "#/components/schemas/Profile"
                    },
                    {
                      "$ref": "#/components/schemas/Class"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "examples": {
                  "pair": {
                    "summary": "tzield × Nausea pair list",
                    "description": "GET /signals?drug=tzield&event=Nausea",
                    "value": [
                      {
                        "drug": "tzield",
                        "event": "Nausea",
                        "n": 319,
                        "eb05": 7.81,
                        "novel": "known",
                        "trend": "Rising",
                        "eb05_recent": 7.42,
                        "eb05_prior": 6.0
                      }
                    ]
                  },
                  "series": {
                    "summary": "tzield × Nausea format=series",
                    "description": "GET /signals?drug=tzield&event=Nausea&format=series",
                    "value": [
                      {
                        "drug": "tzield",
                        "event": "Nausea",
                        "points": [
                          {
                            "quarter": "2023Q2",
                            "n": 4,
                            "eb05": 1.7516,
                            "eb50": 4.3541,
                            "eb95": 8.7807,
                            "ewma_eb05": 2.1936
                          },
                          {
                            "quarter": "2025Q4",
                            "n": 43,
                            "eb05": 4.8244,
                            "eb50": 6.2617,
                            "eb95": 7.9599,
                            "ewma_eb05": 7.1425
                          }
                        ]
                      }
                    ]
                  }
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "brief": {
                    "summary": "tzield × Nausea format=brief",
                    "description": "GET /signals?drug=tzield&event=Nausea&format=brief",
                    "value": "# RWE brief: tzield × Nausea\n\n## Profile\n153 pairs · 2 drugs (tzield, teplizumab). ...\n\n## Series\n11 quarters 2023Q2–2025Q4, sum n=319. Last 4: ...\n\n## Pair\nIsolated FAERS pair: tzield × Nausea. ... This is a statistical hypothesis from spontaneous reports, not evidence that the drug causes the event.\n"
                  }
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                },
                "example": "drug,event,n,eb05,novel,trend,eb05_recent,eb05_prior\ntzield,Nausea,319,7.81,known,Rising,7.42,6.0\n"
              },
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                },
                "examples": {
                  "pdf": {
                    "summary": "tzield × Nausea format=pdf",
                    "description": "GET /signals?drug=tzield&event=Nausea&format=pdf. Same RWE brief as format=brief, Typst PDF. Requires drug= or event=. Event-only: /signals?event=Nausea&format=pdf.",
                    "externalValue": "https://faers.mobi/signals?drug=tzield&event=Nausea&format=pdf"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing drug/event, or format missing a required param (series/label need both; class needs drug; profile/brief/pdf need drug or event).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "series": {
                    "value": {
                      "error": "format=series requires drug and event",
                      "usage": "/signals?drug=tzield&event=Nausea&format=series"
                    }
                  },
                  "brief": {
                    "value": {
                      "error": "format=brief requires drug or event",
                      "usage": "/signals?drug=tzield&format=brief or /signals?event=Nausea&format=brief"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "drug": {
        "name": "drug",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Brand or generic. Exact / prefix / substring / same-substance family. Required for format=class. Required with event for format=series. Optional for format=profile / brief / pdf (drug or event).",
        "example": "tzield"
      },
      "event": {
        "name": "event",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "MedDRA PT (spelling-normalized). Exact / prefix / substring. With drug, isolation is AND. Sufficient alone for format=profile / brief / pdf.",
        "example": "Nausea"
      },
      "q": {
        "name": "q",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Used as drug when neither drug nor event is set."
      },
      "format": {
        "name": "format",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "json",
            "csv",
            "series",
            "profile",
            "class",
            "brief",
            "pdf",
            "label"
          ]
        },
        "description": "Response shape. Omit for JSON pair array. series and label need drug AND event. profile, brief, and pdf need drug or event. class needs drug. brief is Markdown served as text/plain; pdf is the same brief via Typst; label is cached FDA-label Novel status.",
        "examples": {
          "series": {
            "summary": "pair time-course",
            "value": "series"
          },
          "brief": {
            "summary": "copyable RWE markdown",
            "value": "brief"
          },
          "pdf": {
            "summary": "same brief as Typst PDF",
            "value": "pdf"
          },
          "label": {
            "summary": "cached FDA-label Novel status",
            "value": "label"
          }
        }
      },
      "trend": {
        "name": "trend",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Comma-separated Trend labels: Accelerating, Rising, New, Stable, Declining.",
        "example": "Rising"
      },
      "novel": {
        "name": "novel",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "novel, known, or ? (aliases: undetermined, unknown).",
        "example": "novel"
      },
      "min_eb05": {
        "name": "min_eb05",
        "in": "query",
        "schema": {
          "type": "number",
          "minimum": 0
        },
        "description": "Keep rows with eb05 ≥ this value."
      },
      "min_n": {
        "name": "min_n",
        "in": "query",
        "schema": {
          "type": "number",
          "minimum": 0
        },
        "description": "Keep rows with n ≥ this value."
      },
      "limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000,
          "default": 500
        }
      },
      "offset": {
        "name": "offset",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "default": 0
        }
      },
      "sort": {
        "name": "sort",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "eb05",
            "n",
            "trend",
            "novel"
          ]
        },
        "description": "Rank the isolated set before paging. Default is isolation priority then peak EWMA EB05."
      },
      "order": {
        "name": "order",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "desc",
            "asc"
          ],
          "default": "desc"
        },
        "description": "Sort direction (trend desc = Accelerating first)."
      },
      "indication": {
        "name": "indication",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "hide"
          ]
        },
        "description": "hide = drop indication-confounded rows (PT reads as the drug's cached-label indication). Opt-in; default order unchanged. Use with low_info=hide for ranking asks.",
        "example": "hide"
      },
      "low_info": {
        "name": "low_info",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "hide"
          ]
        },
        "description": "hide = drop MedDRA low-information PTs (procedures, generic investigations). Opt-in; default order unchanged. Use with indication=hide for ranking asks.",
        "example": "hide"
      },
      "product_type": {
        "name": "product_type",
        "in": "query",
        "required": false,
        "description": "Keep only rows whose reported drug string names this kind of product. Comma-separated. single = resolves to one active ingredient; combination = two or more actives, or one active plus an unidentified co-ingredient (compounded); trial_uncertain = the string carries a blinded-trial or lot code, or no ingredient could be identified. An opt-in view, never a silent merge: unfiltered, every row is returned and every row carries product_type.",
        "schema": {
          "type": "string",
          "example": "single"
        }
      },
      "medication_error": {
        "name": "medication_error",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "hide"
          ]
        },
        "description": "hide = drop rows whose MedDRA PT describes how the product was used or supplied rather than what it did (medication errors, dose omissions, device and product-quality issues). Opt-in; those rows remain in the unfiltered API and every row carries a medication_error boolean."
      }
    },
    "schemas": {
      "Pair": {
        "type": "object",
        "properties": {
          "drug": {
            "type": "string"
          },
          "event": {
            "type": "string"
          },
          "n": {
            "type": "number",
            "description": "Summed observed over flagged quarters"
          },
          "eb05": {
            "type": "number",
            "description": "Peak EWMA EB05: max of ewma_eb05 over the pair's quarters (EB05 = 5th percentile of the dual-Gamma GPS/EBGM posterior). Raw quarterly peak = max(eb05) in format=series."
          },
          "novel": {
            "type": "string",
            "enum": [
              "novel",
              "known",
              "?"
            ],
            "description": "known = the PT or a MedDRA synonym was matched in the cached FDA label; novel = a real label is cached and nothing matched (NOT MATCHED IN CACHED LABEL TEXT, not 'previously unknown risk'); ? = no usable cached label."
          },
          "trend": {
            "type": "string",
            "enum": [
              "Accelerating",
              "Rising",
              "Stable",
              "Declining",
              "New",
              ""
            ]
          },
          "eb05_recent": {
            "type": "number",
            "nullable": true
          },
          "eb05_prior": {
            "type": "number",
            "nullable": true
          },
          "indication": {
            "type": "boolean",
            "description": "PT reads as the drug's cached-label indication text. Limitations of Use spans and negated sentences are excluded, so label warnings are not flagged."
          },
          "low_info": {
            "type": "boolean",
            "description": "MedDRA low-information PT"
          }
        }
      },
      "SeriesPoint": {
        "type": "object",
        "properties": {
          "quarter": {
            "type": "string",
            "example": "2025Q4"
          },
          "n": {
            "type": "number"
          },
          "eb05": {
            "type": "number"
          },
          "eb50": {
            "type": "number"
          },
          "eb95": {
            "type": "number"
          },
          "ewma_eb05": {
            "type": "number"
          }
        }
      },
      "Series": {
        "type": "object",
        "properties": {
          "drug": {
            "type": "string"
          },
          "event": {
            "type": "string"
          },
          "points": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SeriesPoint"
            }
          }
        }
      },
      "ProfilePair": {
        "type": "object",
        "properties": {
          "drug": {
            "type": "string"
          },
          "event": {
            "type": "string"
          },
          "n": {
            "type": "number"
          },
          "eb05": {
            "type": "number"
          },
          "novel": {
            "type": "string"
          },
          "trend": {
            "type": "string"
          }
        }
      },
      "Profile": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "drugs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "n_drugs": {
            "type": "integer"
          },
          "n_pairs": {
            "type": "integer"
          },
          "n_profiled": {
            "type": "integer"
          },
          "faers_through": {
            "type": "string",
            "example": "2025Q4",
            "description": "Latest FAERS quarter in the live extract."
          },
          "trend": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "novel": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "top_eb05": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProfilePair"
            }
          },
          "top_n": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProfilePair"
            }
          },
          "novel_rising": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProfilePair"
            }
          }
        }
      },
      "Class": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "substance": {
            "type": "string",
            "nullable": true
          },
          "atc_code": {
            "type": "string",
            "nullable": true
          },
          "atc_class4": {
            "type": "string",
            "nullable": true
          },
          "n_class_substances": {
            "type": "integer"
          },
          "n_peer_drugs": {
            "type": "integer"
          },
          "class_wide": {
            "type": "boolean",
            "description": "True when ≥5 class drugs flag the event"
          },
          "class_wide_hint": {
            "type": "string"
          },
          "focal": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProfilePair"
            }
          },
          "peers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProfilePair"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "usage": {
            "type": "string"
          }
        }
      }
    }
  }
}