Events

Understand the Atlas event taxonomy and the payload envelope used by webhooks and event feeds.

Atlas exposes events through webhook deliveries and authenticated event-feed reads.

Event data appears in:

GET /v1/events
GET /v1/companies/{company_id}/events
GET /v1/funds/{fund_id}/events
webhook POST deliveries

webhook.test is only used for manual webhook validation. It is not part of the event-feed contract and does not appear in /v1/events, company event feeds, or fund event feeds.

Event envelope

Every Atlas event includes:

id
type
occurred_at
created_at
entity_kind
entity_id
company_id
fund_id
source_kind
source_id
title
summary
severity
source_url
source_published_at
data

Versioning

Atlas versions the event contract through /v1/events and the documented webhook contract.

Atlas does not include a top-level event_version field.

additive fields may appear over time without a payload-version bump
breaking envelope changes should ship with an explicit API/webhook contract version change, not a silent payload change
event feeds and webhook deliveries stay compatible within the current API version

Timestamp semantics

Atlas exposes three top-level timestamps:

occurred_at: the timestamp Atlas uses for feed ordering and cursor progression
created_at: when Atlas persisted the event record internally
source_published_at: when the upstream filing, factsheet, or source page was published, if Atlas knows it

Event-specific occurred_at semantics are:

filing.new: the filing published_at
filing.signal.created: the Atlas extraction/promotion time for the structured signal
board_change.detected: the Atlas extraction/promotion time for the structured board-change signal
dividend.declared: the Atlas extraction/promotion time for the structured dividend signal
fund.snapshot.updated: source_published_at when known, otherwise the snapshot as_of_date at 00:00:00Z
fund.disclosure.updated: source_published_at when known, otherwise the snapshot as_of_date at 00:00:00Z

Atlas does not yet expose a stable top-level effective_at field.

For dividends and other corporate actions, use the event-specific data payload and source document until Atlas exposes a normalized top-level effective_at.

Atlas also exposes two top-level provenance fields:

source_kind: the upstream source family Atlas used for provenance, such as filing, filing_signal, portfolio_fund_snapshot, or sandbox_event
source_id: the Atlas-side identifier of that upstream source record

Supported event types

Event type	Trigger	`data` payload
`filing.new`	New filing inserted into Atlas	`company`, `filing`
`filing.signal.created`	Filing first receives a promoted signal	`company`, `filing`, `signal`
`board_change.detected`	Structured board-change details are first available for a filing	`company`, `filing`, `signal`
`dividend.declared`	Structured dividend details are first available for a filing	`company`, `filing`, `signal`
`fund.snapshot.updated`	New fund snapshot is created	`fund`, `snapshot`, `disclosure_kind`
`fund.disclosure.updated`	New fund snapshot includes disclosure content	`fund`, `snapshot`, `disclosure_kind`

Feed behavior

The unified event feed is ordered by:

occurred_at descending
id descending

Filtering supports:

repeated type parameters
company_id
fund_id
from
to
limit

Use cursor pagination for backfills and reconciliation reads.

Examples:

GET /v1/events?type=dividend.declared
GET /v1/events?type=filing.new&type=board_change.detected

Example payloads

{
  "id": "2d0f3ed8-71e3-4d9c-a61a-5ddd84d020b6",
  "type": "filing.new",
  "occurred_at": "2026-04-11T01:05:18.383263Z",
  "created_at": "2026-04-11T01:05:19.012411Z",
  "entity_kind": "filing",
  "entity_id": "0f9df103-7873-4bd1-be96-9379fcaae66b",
  "company_id": "24b76421-51db-45ea-ba65-8c84eface2ea",
  "fund_id": null,
  "source_kind": "filing",
  "source_id": "0f9df103-7873-4bd1-be96-9379fcaae66b",
  "title": "Atlas Bank FY 2025 Results",
  "summary": "New results filing published.",
  "severity": "info",
  "source_url": "https://example.com/atlas-live-f49dbc18.pdf",
  "source_published_at": "2026-04-11T01:05:18.381927Z",
  "data": {
    "company": {
      "id": "24b76421-51db-45ea-ba65-8c84eface2ea",
      "name": "Atlas Live Bank f49dbc18",
      "ticker": "AF49DB",
      "sector": "Financial Services",
      "logo_url": null
    },
    "filing": {
      "id": "0f9df103-7873-4bd1-be96-9379fcaae66b",
      "company_id": "24b76421-51db-45ea-ba65-8c84eface2ea",
      "filing_type": "results",
      "title": "Atlas Bank FY 2025 Results",
      "period": "FY 2025",
      "published_at": "2026-04-11T01:05:18.381927+00:00",
      "url": "https://example.com/atlas-live-f49dbc18.pdf",
      "has_tables": false,
      "company": {
        "id": "24b76421-51db-45ea-ba65-8c84eface2ea",
        "name": "Atlas Live Bank f49dbc18",
        "ticker": "AF49DB",
        "sector": "Financial Services",
        "logo_url": null
      }
    }
  }
}

{
  "id": "5f9af65d-4932-42c8-a1cf-9732d2e5f102",
  "type": "filing.signal.created",
  "occurred_at": "2026-04-11T01:08:54.191211Z",
  "created_at": "2026-04-11T01:08:54.482992Z",
  "entity_kind": "filing",
  "entity_id": "0f9df103-7873-4bd1-be96-9379fcaae66b",
  "company_id": "24b76421-51db-45ea-ba65-8c84eface2ea",
  "fund_id": null,
  "source_kind": "filing_signal",
  "source_id": "1fe57130-3ef6-4b15-a950-63504c6bce5a",
  "title": "Atlas Bank FY 2025 Results signal extracted",
  "summary": "Revenue grew year over year and profit before tax improved.",
  "severity": "info",
  "source_url": "https://example.com/atlas-live-f49dbc18.pdf",
  "source_published_at": "2026-04-11T01:05:18.381927Z",
  "data": {
    "company": {
      "id": "24b76421-51db-45ea-ba65-8c84eface2ea",
      "name": "Atlas Live Bank f49dbc18",
      "ticker": "AF49DB",
      "sector": "Financial Services",
      "logo_url": null
    },
    "filing": {
      "id": "0f9df103-7873-4bd1-be96-9379fcaae66b",
      "company_id": "24b76421-51db-45ea-ba65-8c84eface2ea",
      "filing_type": "results",
      "title": "Atlas Bank FY 2025 Results",
      "period": "FY 2025",
      "published_at": "2026-04-11T01:05:18.381927+00:00",
      "url": "https://example.com/atlas-live-f49dbc18.pdf",
      "has_tables": false
    },
    "signal": {
      "extraction_id": "1fe57130-3ef6-4b15-a950-63504c6bce5a",
      "summary": "Revenue grew year over year and profit before tax improved.",
      "confidence": 0.94,
      "extracted_at": "2026-04-11T01:08:54.191211+00:00",
      "reporting_period": "FY 2025",
      "key_points": [
        "Revenue growth improved year over year",
        "Profit before tax increased"
      ],
      "mentioned_tickers": [
        "AF49DB"
      ],
      "dates_mentioned": [
        "2025-12-31"
      ],
      "risk_flags": [],
      "corporate_actions": [],
      "board_changes": [],
      "metrics": [],
      "result_details": {
        "headline": "FY 2025 results"
      },
      "corporate_action_details": [],
      "board_change_details": [],
      "highlights": [
        "Improved profitability"
      ]
    }
  }
}

{
  "id": "87f628f4-0497-41c7-a9af-8ab8adba0c89",
  "type": "board_change.detected",
  "occurred_at": "2026-04-10T10:04:11Z",
  "created_at": "2026-04-10T10:04:11.441992Z",
  "entity_kind": "filing",
  "entity_id": "filing_123",
  "company_id": "company_123",
  "fund_id": null,
  "source_kind": "filing_signal",
  "source_id": "signal_board_123",
  "title": "Board changes detected",
  "summary": "Issuer appointed a new independent director and accepted one resignation.",
  "severity": "medium",
  "source_url": "https://example.com/issuer-board-change.pdf",
  "source_published_at": "2026-04-10T10:00:00Z",
  "data": {
    "company": {
      "id": "company_123",
      "name": "Issuer Plc",
      "ticker": "ISSUER"
    },
    "filing": {
      "id": "filing_123",
      "filing_type": "board_change",
      "published_at": "2026-04-10T10:00:00Z",
      "url": "https://example.com/issuer-board-change.pdf"
    },
    "signal": {
      "summary": "Issuer appointed a new independent director and accepted one resignation.",
      "board_changes": [
        "Appointment of Jane Doe as Independent Non-Executive Director",
        "Resignation of John Roe as Executive Director"
      ],
      "highlights": [
        "Independent director appointment",
        "Executive resignation"
      ]
    }
  }
}

{
  "id": "b6e820d7-7284-4908-b5fc-c7ae77f01c69",
  "type": "dividend.declared",
  "occurred_at": "2026-04-10T10:06:33Z",
  "created_at": "2026-04-10T10:06:33.172000Z",
  "entity_kind": "filing",
  "entity_id": "filing_456",
  "company_id": "company_456",
  "fund_id": null,
  "source_kind": "filing_signal",
  "source_id": "signal_dividend_456",
  "title": "Dividend declared",
  "summary": "Dividend Plc proposed a final cash dividend for FY 2025.",
  "severity": "medium",
  "source_url": "https://example.com/dividend-plc-action.pdf",
  "source_published_at": "2026-04-10T10:00:00Z",
  "data": {
    "company": {
      "id": "company_456",
      "name": "Dividend Plc",
      "ticker": "DVDND"
    },
    "filing": {
      "id": "filing_456",
      "filing_type": "corporate_action",
      "published_at": "2026-04-10T10:00:00Z",
      "url": "https://example.com/dividend-plc-action.pdf"
    },
    "signal": {
      "summary": "Dividend Plc proposed a final cash dividend for FY 2025.",
      "corporate_actions": [
        "Final cash dividend proposed"
      ],
      "highlights": [
        "Cash dividend declaration"
      ]
    }
  }
}

{
  "id": "d42700c5-00da-4fe2-91c6-9175085d0213",
  "type": "fund.snapshot.updated",
  "occurred_at": "2026-04-09T09:00:00Z",
  "created_at": "2026-04-09T09:00:01.201922Z",
  "entity_kind": "fund",
  "entity_id": "fund_789",
  "company_id": null,
  "fund_id": "fund_789",
  "source_kind": "portfolio_fund_snapshot",
  "source_id": "snapshot_789",
  "title": "Atlas Income Fund snapshot updated",
  "summary": "New fund snapshot recorded for Atlas Income Fund.",
  "severity": "info",
  "source_url": "https://example.com/atlas-income-fund-april-2026.pdf",
  "source_published_at": "2026-04-09T09:00:00Z",
  "data": {
    "fund": {
      "id": "fund_789",
      "provider": "atlas_am",
      "slug": "atlas-income-fund",
      "name": "Atlas Income Fund"
    },
    "snapshot": {
      "id": "snapshot_789",
      "fund_id": "fund_789",
      "as_of_date": "2026-04-09",
      "factsheet_title": "Atlas Income Fund April 2026 Factsheet",
      "factsheet_url": "https://example.com/atlas-income-fund-april-2026.pdf",
      "source_post_url": "https://example.com/atlas-income-fund",
      "source_published_at": "2026-04-09T09:00:00+00:00",
      "source_metrics": {
        "current_asset_allocation": [
          {
            "label": "Cash",
            "weight_pct": 30.0
          }
        ]
      },
      "top_holdings": null,
      "disclosure_kind": "asset_allocation"
    },
    "disclosure_kind": "asset_allocation"
  }
}

{
  "id": "9a47018e-64f2-4712-875e-c1b8cc4fa901",
  "type": "fund.disclosure.updated",
  "occurred_at": "2026-04-09T09:00:00Z",
  "created_at": "2026-04-09T09:00:01.612113Z",
  "entity_kind": "fund",
  "entity_id": "fund_789",
  "company_id": null,
  "fund_id": "fund_789",
  "source_kind": "portfolio_fund_snapshot",
  "source_id": "snapshot_789",
  "title": "Atlas Income Fund April 2026 Factsheet",
  "summary": "Fund disclosure updated with a new factsheet snapshot.",
  "severity": "info",
  "source_url": "https://example.com/atlas-income-fund-april-2026.pdf",
  "source_published_at": "2026-04-09T09:00:00Z",
  "data": {
    "fund": {
      "id": "fund_789",
      "provider": "atlas_am",
      "slug": "atlas-income-fund",
      "name": "Atlas Income Fund"
    },
    "snapshot": {
      "id": "snapshot_789",
      "fund_id": "fund_789",
      "as_of_date": "2026-04-09",
      "factsheet_title": "Atlas Income Fund April 2026 Factsheet",
      "factsheet_url": "https://example.com/atlas-income-fund-april-2026.pdf",
      "source_post_url": "https://example.com/atlas-income-fund",
      "source_published_at": "2026-04-09T09:00:00+00:00",
      "source_metrics": {
        "current_asset_allocation": [
          {
            "label": "Cash",
            "weight_pct": 30.0
          }
        ]
      },
      "top_holdings": null,
      "disclosure_kind": "asset_allocation"
    },
    "disclosure_kind": "asset_allocation"
  }
}