{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/falpha-ai/json-schema/falpha-ai-events-response-schema.json",
  "title": "events_response",
  "x-generated": "2026-11-07",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/falpha-ai-openapi.json#/components/schemas/events_response",
  "properties": {
    "type": {
      "type": "string",
      "title": "Type"
    },
    "since": {
      "type": "string",
      "title": "Since",
      "description": "Events dated on or after this day are included."
    },
    "as_of": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "As Of",
      "description": "The newest data date the answer was computed from."
    },
    "count": {
      "type": "integer",
      "title": "Count"
    },
    "events": {
      "items": {
        "$ref": "#/$defs/event"
      },
      "type": "array",
      "title": "Events"
    }
  },
  "type": "object",
  "required": [
    "type",
    "since",
    "count",
    "events"
  ],
  "$defs": {
    "event": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id",
          "description": "Stable id for this event. The same event always has the same id; deduplicate on it."
        },
        "type": {
          "type": "string",
          "title": "Type",
          "description": "flip, confidence_cross, sentiment_shift or screener_entry"
        },
        "ticker": {
          "type": "string",
          "title": "Ticker"
        },
        "date": {
          "type": "string",
          "title": "Date",
          "description": "The day the event happened (YYYY-MM-DD)."
        },
        "previous_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Previous Date",
          "description": "The earlier reading this one was compared with."
        },
        "period": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Period",
          "description": "Signal horizon: 5d, 15d or 2m"
        },
        "horizon_label": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Horizon Label"
        },
        "regime": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Regime"
        },
        "signal": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Signal",
          "description": "The signal on the event date: buy or sell"
        },
        "confidence": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Confidence",
          "description": "Confidence on the event date (0.5 to 1)."
        },
        "previous_confidence": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Previous Confidence"
        },
        "from_signal": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "From Signal",
          "description": "flip: the direction before"
        },
        "to_signal": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "To Signal",
          "description": "flip: the direction after"
        },
        "threshold": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Threshold",
          "description": "confidence_cross: the level crossed"
        },
        "crossed": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Crossed",
          "description": "confidence_cross: above or below"
        },
        "sentiment": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Sentiment",
          "description": "sentiment_shift: the daily news sentiment score on the event date"
        },
        "previous_sentiment": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Previous Sentiment"
        },
        "change": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Change",
          "description": "sentiment_shift: sentiment minus previous_sentiment"
        },
        "shift": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Shift",
          "description": "sentiment_shift: up or down"
        },
        "signal_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Signal Date",
          "description": "sentiment_shift: the date of the signal reading carried beside it"
        },
        "rank": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Rank",
          "description": "screener_entry: position in the ranking"
        },
        "rank_by": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Rank By"
        },
        "top": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Top"
        },
        "quality": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Quality",
          "description": "screener_entry: the quality score (a Sharpe-ratio proxy)"
        },
        "url": {
          "type": "string",
          "title": "Url",
          "description": "The ticker's page on fAlpha."
        },
        "summary": {
          "type": "string",
          "title": "Summary",
          "description": "One plain sentence describing the event. Model output, not investment advice."
        }
      },
      "type": "object",
      "required": [
        "id",
        "type",
        "ticker",
        "date",
        "url",
        "summary"
      ],
      "title": "event"
    }
  }
}