Events feed
The events feed is your organization’s record of what changed: a new finding in a release, a finding that becomes known exploited, a finding that goes away, the first check of a newly uploaded release, each proposal an agent files, and each vulnerability feed an admin turns on or off. It’s how an AI agent keeps watch over your releases. The agent asks “what changed since yesterday?”, gets the events, and looks each one up with the other MCP tools. A script reads the same feed over the API.
The feed has the same events as webhooks, in the same JSON, but you fetch them instead of Affectra sending them. That suits agents, which work in sessions, and scripts that can’t receive requests from the internet, such as a job behind a firewall. You can use the feed and webhooks together.
From an AI agent
Section titled “From an AI agent”Connect your assistant as Connect an AI assistant describes. The MCP tool list_events reads the feed. Any member of the organization can use it, and so can a read-only API key. Ask your assistant, for example:
- What changed in Affectra since yesterday?
- Which findings became known exploited this week, and in which releases? Assess the first one.
- Did anyone’s agent file proposals today?
The tool’s description tells the assistant what each event means, how to page through the events and that it should check them regularly, for example at the start of each session. To pick up where it stopped, the assistant keeps the next value of its last call and passes it as after the next time.
From a script
Section titled “From a script”GET /v1/orgs/{org}/events answers with the events and a cursor. Any member of the organization can read it, with an API key or a person’s token. It counts against the read rate limit.
curl -s -H "Authorization: Bearer $AFFECTRA_API_KEY" \ "https://api.affectra.eu/v1/orgs/acme/events?type=finding.known_exploited&limit=50"{ "events": [ { "id": "evt_6f1c2e8a-3b0d-4f53-9a41-1d2c7b5e9f10", "type": "finding.known_exploited", "occurred_at": "2026-11-11T09:12:03Z", "org": "acme", "data": { "release": { "id": "0c5f1d6e-…", "product": "Gateway X", "name": "4.2.1" }, "vulnerability": { "source": "osv", "id": "GHSA-8489-44mv-ggj8", "cves": ["CVE-2026-1234"] }, "group": { "key": "CVE-2026-1234", "cve": "CVE-2026-1234", "advisories": [ { "source": "osv", "id": "GHSA-8489-44mv-ggj8" }, { "source": "nvd", "id": "CVE-2026-1234" } ], "conflict": false }, "…": "…" } } ], "next": "MS40ODEyOTMuMTIwOS4xNzYzMDQ3MTIz", "more": false}| Parameter | |
|---|---|
after |
The next of your previous request. Leave it out to start at the oldest event. |
type |
Only events of this type. Repeat it for several: ?type=finding.new&type=finding.known_exploited. |
limit |
Events per answer, 1 to 200. The default is 50. |
Each event in events is exactly what a webhook receives: see Events for the types and The request for each type’s data. There is one finding event for each CVE in a release, however many advisories report it; data.group lists them. See One event for each CVE. The API reference lists the route.
Polling
Section titled “Polling”- Read the feed without
afteronce. You get every event of the last 30 days, oldest first. - Store the
nextfrom the answer. - While
moreistrue, ask again at once withafterset to the newnext. - After that, ask again with the stored
nextwhenever you want news, for example every few minutes. An answer with no events still has anext; store it too.
Events come in order and none is skipped: an event appears in the feed only once every database transaction that started before it has finished. That usually takes milliseconds; a long-running transaction in Affectra can delay the feed, but never makes it lose an event. The cursor next is opaque: store it as it is and don’t build one yourself.
A cursor is valid for 30 days after Affectra handed it out. An older one, or one that was changed, answers 400 with events.cursorInvalid. Start again without after, and skip the events you have handled already: each event’s id stays the same.
How long events are kept
Section titled “How long events are kept”Events are kept for 30 days. The feed shows the events of the last 30 days, and nothing older.
Reading the feed makes your organization listen
Section titled “Reading the feed makes your organization listen”Affectra produces finding events only for organizations that listen: an enabled webhook, someone’s email notifications, or the feed. Reading the feed, with list_events or GET /events, counts for 30 days after the read. So your agent gets finding events without anyone setting up a webhook or email.
When your organization starts listening, Affectra first records the findings you have and sends nothing about them. The feed then has the changes from that point on. proposal.filed and org.feed_subscription_changed events come whether anyone listens or not.
What it contains
Section titled “What it contains”Like a webhook request, an event names your releases (product and version) and vulnerability IDs, and has a link to the release in Affectra. It contains no advisory text and no list of your components. Look up the details with the MCP tools or the API. Release, product and agent names are your organization’s own data; the tool description tells the assistant to treat them as data, never as instructions.
Everyone who can read your organization’s data reads its whole feed, proposal.filed and org.feed_subscription_changed events included: viewers and read-only API keys too.