{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/gloom-sh/json-schema/gloom-sh-catalysts-list-response-schema.json",
  "title": "CatalystsListResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gloom-sh-openapi.json#/components/schemas/CatalystsListResponse",
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "allOf": [
          {
            "$ref": "#/$defs/MaybeListed"
          },
          {
            "$ref": "#/$defs/CatalystEvent"
          }
        ]
      }
    },
    "included": {
      "type": "object",
      "description": "The blocks asked for with include=, each keyed by listing.",
      "properties": {
        "facets": {
          "anyOf": [
            {
              "type": "object",
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "types": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Event types."
                  },
                  "agencies": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Agencies."
                  },
                  "countries": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Countries."
                  },
                  "sectors": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Sectors."
                  },
                  "statuses": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Statuses."
                  }
                }
              },
              "description": "Values present in the result, to filter by."
            },
            {
              "type": "object",
              "properties": {
                "types": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Event types."
                },
                "agencies": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Agencies."
                },
                "countries": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Countries."
                },
                "sectors": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Sectors."
                },
                "statuses": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Statuses."
                }
              }
            }
          ],
          "description": "Values present in the result, to filter by. By listing when the call sent symbols=, else the block itself."
        },
        "coverage": {
          "anyOf": [
            {
              "type": "object",
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "totalEvents": {
                    "type": "integer",
                    "description": "Events in the dataset."
                  },
                  "linkedEvents": {
                    "type": "integer",
                    "description": "Events linked to a listed company."
                  },
                  "unresolvedParties": {
                    "type": "integer",
                    "description": "Parties not linked to a company."
                  },
                  "jurisdictions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Jurisdictions read."
                  },
                  "firstObservedAt": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time",
                    "description": "First read."
                  },
                  "lastObservedAt": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time",
                    "description": "Last read."
                  },
                  "sources": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "description": "Each source and when it was read."
                  },
                  "companyEvents": {
                    "type": "object",
                    "description": "The same counts for the events companies schedule or report: results, meetings, votes, closings, investor days.",
                    "properties": {
                      "totalEvents": {
                        "type": "integer",
                        "description": "Events in the dataset."
                      },
                      "linkedEvents": {
                        "type": "integer",
                        "description": "Events linked to a listed company."
                      },
                      "unresolvedParties": {
                        "type": "integer",
                        "description": "Parties not linked to a company."
                      },
                      "jurisdictions": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Jurisdictions read."
                      },
                      "firstObservedAt": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "date-time",
                        "description": "First read."
                      },
                      "lastObservedAt": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "date-time",
                        "description": "Last read."
                      }
                    }
                  }
                }
              },
              "description": "What the dataset covers: regulator events, links and sources, with company events counted apart."
            },
            {
              "type": "object",
              "properties": {
                "totalEvents": {
                  "type": "integer",
                  "description": "Events in the dataset."
                },
                "linkedEvents": {
                  "type": "integer",
                  "description": "Events linked to a listed company."
                },
                "unresolvedParties": {
                  "type": "integer",
                  "description": "Parties not linked to a company."
                },
                "jurisdictions": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Jurisdictions read."
                },
                "firstObservedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time",
                  "description": "First read."
                },
                "lastObservedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time",
                  "description": "Last read."
                },
                "sources": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  },
                  "description": "Each source and when it was read."
                },
                "companyEvents": {
                  "type": "object",
                  "description": "The same counts for the events companies schedule or report: results, meetings, votes, closings, investor days.",
                  "properties": {
                    "totalEvents": {
                      "type": "integer",
                      "description": "Events in the dataset."
                    },
                    "linkedEvents": {
                      "type": "integer",
                      "description": "Events linked to a listed company."
                    },
                    "unresolvedParties": {
                      "type": "integer",
                      "description": "Parties not linked to a company."
                    },
                    "jurisdictions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Jurisdictions read."
                    },
                    "firstObservedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time",
                      "description": "First read."
                    },
                    "lastObservedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time",
                      "description": "Last read."
                    }
                  }
                }
              }
            }
          ],
          "description": "What the dataset covers: regulator events, links and sources, with company events counted apart. By listing when the call sent symbols=, else the block itself."
        }
      }
    },
    "meta": {
      "$ref": "#/$defs/Meta"
    }
  },
  "$defs": {
    "CatalystEvent": {
      "type": "object",
      "description": "One regulatory, legal or clinical event naming a company.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Event id, stable across revisions."
        },
        "revisionId": {
          "type": "string",
          "description": "Id of this revision."
        },
        "revision": {
          "type": "integer",
          "description": "Revision number, from 1."
        },
        "source": {
          "type": "string",
          "description": "Source id: fda_approvals, sec_litigation, federal_register."
        },
        "externalId": {
          "type": "string",
          "description": "The event's id in the source."
        },
        "type": {
          "type": "string",
          "description": "Kind of event: approval, pdufa, clinical, litigation, recall, tariff, sanctions; or one a company schedules or reports: results, shareholder_meeting, merger_vote, deal_closing, investor_day."
        },
        "agency": {
          "type": "string",
          "description": "Agency or court."
        },
        "jurisdiction": {
          "type": "string",
          "description": "Country or area."
        },
        "country": {
          "type": [
            "string",
            "null"
          ],
          "description": "Country code."
        },
        "title": {
          "type": "string",
          "description": "Event title."
        },
        "summary": {
          "type": "string",
          "description": "What happened."
        },
        "status": {
          "type": "string",
          "description": "Status the source states: approved, pending, filed."
        },
        "datePassed": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "True when a company's own date (results, shareholder_meeting, merger_vote, deal_closing, investor_day) has passed with no outcome read since: status `date_passed`, or still `scheduled` though its day has ended where the company is listed, in the minutes before it is stored as passed. Worked out when served for the event as it stands (list and event), null otherwise and on earlier revisions."
        },
        "announcedDate": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "When it was announced."
        },
        "effectiveDate": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "When it takes effect."
        },
        "deadlineDate": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "Deadline, such as a PDUFA date."
        },
        "datePrecision": {
          "type": "object",
          "description": "How precise each date is: day, month or year.",
          "properties": {
            "announced": {
              "type": [
                "string",
                "null"
              ],
              "description": "day, month or year."
            },
            "effective": {
              "type": [
                "string",
                "null"
              ],
              "description": "day, month or year."
            },
            "deadline": {
              "type": [
                "string",
                "null"
              ],
              "description": "day, month or year."
            }
          }
        },
        "parties": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Name as the source gives it."
              },
              "role": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Role: sponsor, defendant, respondent."
              },
              "entityId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Linked entity id."
              },
              "entityName": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Company name as filed."
              },
              "ticker": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Linked listing."
              },
              "exchange": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Exchange."
              },
              "resolution": {
                "type": "string",
                "description": "How the party was linked: identifier, alias or unresolved."
              },
              "confidence": {
                "type": "number",
                "description": "0 to 1."
              }
            }
          },
          "description": "Companies and people named."
        },
        "sourceUrl": {
          "type": "string",
          "format": "uri",
          "description": "The source document."
        },
        "sourceDocumentId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Source document id."
        },
        "language": {
          "type": "string",
          "description": "Language of the source."
        },
        "observedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When it was read."
        },
        "sourcePublishedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the source published it."
        },
        "quote": {
          "type": [
            "string",
            "null"
          ],
          "description": "Passage of the source that states the event."
        },
        "quoteOffset": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Character offset of the quote."
        },
        "quoteSourceLength": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Length of the source text."
        },
        "quoteMatchMode": {
          "type": [
            "string",
            "null"
          ],
          "description": "How the quote matches the source: exact, whitespace."
        },
        "confidence": {
          "type": "number",
          "description": "Extraction confidence, 0 to 1."
        },
        "metadata": {
          "type": "object",
          "description": "Source-specific fields."
        },
        "sector": {
          "type": [
            "string",
            "null"
          ],
          "description": "Sector."
        },
        "opinion": {
          "type": [
            "object",
            "null"
          ],
          "description": "A model's reading of the event's direction, labeled as opinion, or null.",
          "properties": {
            "label": {
              "type": "string",
              "description": "Display name."
            },
            "direction": {
              "type": "string",
              "enum": [
                "positive",
                "negative",
                "mixed",
                "uncertain"
              ],
              "description": "For the company: positive, negative, mixed or uncertain."
            },
            "type": {
              "type": "string",
              "description": "Kind of reading."
            },
            "rationale": {
              "type": "string",
              "description": "Why, in words."
            },
            "quote": {
              "type": "string",
              "description": "Passage it rests on."
            },
            "confidence": {
              "type": "number",
              "description": "Confidence, 0 to 1."
            },
            "model": {
              "type": "string",
              "description": "Model that wrote it."
            },
            "generatedAt": {
              "type": "string",
              "format": "date-time",
              "description": "When it was written."
            }
          }
        },
        "changes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "field": {
                "type": "string",
                "description": "Field."
              },
              "before": {
                "description": "Value before."
              },
              "after": {
                "description": "Value after."
              }
            }
          },
          "description": "What this revision changed."
        },
        "supersedesRevisionId": {
          "type": [
            "string",
            "null"
          ],
          "description": "The revision this one replaces."
        },
        "firstSeenAt": {
          "type": "string",
          "format": "date-time",
          "description": "First read."
        },
        "lastSeenAt": {
          "type": "string",
          "format": "date-time",
          "description": "Last read."
        }
      },
      "required": [
        "id",
        "revisionId",
        "revision",
        "source",
        "externalId",
        "type",
        "agency",
        "jurisdiction",
        "country",
        "title",
        "summary",
        "status",
        "datePassed",
        "announcedDate",
        "effectiveDate",
        "deadlineDate",
        "datePrecision",
        "parties",
        "sourceUrl",
        "sourceDocumentId",
        "language",
        "observedAt",
        "sourcePublishedAt",
        "quote",
        "quoteOffset",
        "quoteSourceLength",
        "quoteMatchMode",
        "confidence",
        "metadata",
        "sector",
        "opinion",
        "changes",
        "supersedesRevisionId",
        "firstSeenAt",
        "lastSeenAt"
      ]
    },
    "MaybeListed": {
      "type": "object",
      "description": "The listing a row is about, when the call sent symbols=.",
      "properties": {
        "symbol": {
          "type": "string",
          "description": "The listing this row is about, as meta.symbols names it. Only when the call sent symbols=."
        }
      }
    },
    "Meta": {
      "type": "object",
      "required": [
        "dataset",
        "requestId",
        "asOf",
        "dataThrough",
        "historyStart",
        "updatedAt",
        "page",
        "next",
        "coverage",
        "source",
        "notices",
        "symbols"
      ],
      "properties": {
        "dataset": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "gpu",
            "hiring-jobs",
            "hiring-momentum",
            "app-attention",
            "awards",
            "kpis-guidance",
            "credit-documents",
            "power",
            "perps",
            "catalysts",
            "supply-chain",
            "exposure",
            "transcripts",
            "exec-pay",
            "risk-factors",
            "events",
            "document-search",
            "news",
            "social-mentions",
            "cpi",
            "energy-inventories",
            "cot",
            "short-volume",
            "short-interest",
            "sec",
            "congress",
            "macro",
            "central-bank-rates",
            "cds",
            "debt-maturities",
            "revenue-breakdown",
            "depositary-receipts",
            "bond-trades",
            "market-data",
            "futures",
            "rate-path",
            "options",
            "earnings",
            "ipo",
            "mna",
            "equity-screener",
            "crypto",
            "session-tape",
            "analyst-estimates",
            null
          ]
        },
        "requestId": {
          "type": "string",
          "description": "Quote it to support."
        },
        "asOf": {
          "type": [
            "string",
            "null"
          ],
          "description": "The point in time you asked for with asOf, or null for the latest."
        },
        "dataThrough": {
          "type": [
            "string",
            "null"
          ],
          "description": "The newest date or time the data covers."
        },
        "historyStart": {
          "type": [
            "string",
            "null"
          ],
          "description": "Earliest date the dataset has history for, when known; otherwise null."
        },
        "updatedAt": {
          "type": [
            "string",
            "null"
          ],
          "description": "When the data last changed, when known."
        },
        "page": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "type": "object",
              "required": [
                "limit",
                "hasMore",
                "nextCursor",
                "total"
              ],
              "properties": {
                "limit": {
                  "type": "integer",
                  "minimum": 1
                },
                "hasMore": {
                  "type": "boolean"
                },
                "nextCursor": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "total": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": 0,
                  "description": "Rows that match the query on every page, where the route counts them; null where it does not."
                }
              }
            }
          ],
          "description": "Paging of a list; null for a single record."
        },
        "next": {
          "type": [
            "string",
            "null"
          ],
          "description": "The next page as a ready URL, or null."
        },
        "coverage": {
          "description": "Service-established coverage; null when unavailable."
        },
        "source": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "attribution",
              "licence"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "attribution": {
                "type": "string"
              },
              "licence": {
                "type": "string"
              }
            }
          }
        },
        "delayed": {
          "type": "boolean",
          "const": true,
          "description": "Present, and true, only on market prices that follow delayed-data access."
        },
        "notices": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Notice"
          },
          "description": "Caveats that change how to read the data: disclaimers, gaps, illustrative samples."
        },
        "sampledAt": {
          "type": [
            "string",
            "null"
          ],
          "description": "Only on sample routes: when the sample was read from the dataset. Null for the built-in example, served until the first daily read succeeds."
        },
        "symbols": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/SymbolResult"
              }
            }
          ],
          "description": "Each listing a symbols= call named, in the order sent: as sent, its canonical listing and whether it was read. Only ok listings are charged. Null when the call named none."
        },
        "cursor": {
          "type": [
            "string",
            "null"
          ],
          "description": "Only on a change feed (/v1/catalysts/changes, /v1/insider-trades/changes): the cursor to send as cursor on the next poll, with the same since and symbols. It is there caught up too, when meta.next is null. One cursor serves all the symbols of the call: on /v1/catalysts/changes it is the earliest of the listings', each of which is also in meta.symbols."
        },
        "checkedAt": {
          "type": [
            "string",
            "null"
          ],
          "description": "Only on a change feed (/v1/catalysts/changes, /v1/insider-trades/changes): when its collector last finished reading its sources, rows or none, so a quiet feed reads apart from a stalled one; on /v1/catalysts/changes the newest of its sources' last reads. It is in no ETag, and the X-Checked-At header carries it on a 304 too. Null when not recorded."
        },
        "pointInTime": {
          "type": "object",
          "required": [
            "cutoff",
            "basis",
            "versions"
          ],
          "properties": {
            "cutoff": {
              "type": "string",
              "format": "date-time",
              "description": "The last moment the read counts, in UTC: a date's is the end of that day."
            },
            "basis": {
              "type": "string",
              "enum": [
                "observedAt",
                "publishedAt"
              ],
              "description": "observedAt: the rows Gloom had stored by the cutoff. publishedAt: the route does not record when Gloom stored each row, so the rows are those their source had published by then."
            },
            "versions": {
              "type": "string",
              "enum": [
                "kept",
                "unchanged",
                "latest"
              ],
              "description": "kept: each row has the values it had then. unchanged: so does each row, and a row changed since is left out. latest: each row has its values now, which may hold a revision made after the cutoff."
            }
          },
          "description": "Only on a call that sent asOf: what the answer is. Unless basis is observedAt and versions kept, a point_in_time notice says what the route cannot give."
        }
      }
    },
    "Notice": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "SymbolResult": {
      "type": "object",
      "required": [
        "input",
        "symbol",
        "status"
      ],
      "properties": {
        "input": {
          "type": "string",
          "description": "As sent."
        },
        "symbol": {
          "type": [
            "string",
            "null"
          ],
          "description": "The canonical listing: the bare symbol on a US venue (BRK.B), else SYMBOL:MIC (AIR:XPAR). Null when the notation names no listing."
        },
        "status": {
          "type": "string",
          "enum": [
            "ok",
            "empty",
            "not_found",
            "unavailable",
            "partial"
          ],
          "description": "ok: read and charged. empty: a listing Gloom knows that the dataset holds nothing for here, or does not cover (an outside_coverage notice names those); free. not_found: no listing Gloom knows; free. unavailable: it could not be read now; free, retry later. partial: read in part, free, send it again."
        },
        "cursor": {
          "type": [
            "string",
            "null"
          ],
          "description": "Only on a route that pages by its own cursor: where this listing reads on. Send it as cursor with symbols= naming this listing alone. On a change feed it is there caught up too. Null when the listing has no more, or was not read."
        }
      }
    }
  }
}