Concepts
The words the product, the API and the agent guide all use, each in a few sentences.
Workspace and project
A workspace is your team: members (owners and members), API keys, usage meters and an audit log. A project is a thing you monitor: an application, one service in a monorepo, or an area of a large system. A project owns its dependency list, its private inbound email address, its rules, its destinations and its settings (environments, quiet hours, digest schedule, pause state). One repository may be several projects; the agent guide says how to choose.
Dependency and vendor
A dependency is something a project relies on: a package, an API, a cloud service, a hosted platform. It carries an external_ref such as npm:stripe, a type, an importance and the environments it serves. Most dependencies map to a vendor in the platform catalogue, which knows the vendor’s status page, changelog, release feed and advisory source. A dependency can also have custom sources you add by URL.
Source
A source is one place the platform reads: a status page, a GitHub releases feed, an RSS or Atom feed, OSV for a package, a status API, or email. Automatic sources are polled every five minutes, once for the whole platform, and their events fan out to every project that depends on the vendor. Each source has a health: last success, consecutive failures, last error. A stale source means silence from it proves nothing.
Event
An event is one thing a source said, in one shape whatever the source: title, summary, link, when the vendor published it and when we first saw it, a category, the vendor’s upstream severity, the platform priority we assigned with the rule that assigned it, the customer impact (unknown until someone says otherwise), and provenance.
| Category | Family | Means |
|---|---|---|
| incident | status | The vendor reports a problem with their service. |
| maintenance | status | The vendor has scheduled work; a window with a start and an end. |
| release | changes | A new version shipped. |
| breaking_change | changes | A change that needs action from you. |
| deprecation | changes | Something will be withdrawn. |
| security_advisory | changes | A vulnerability or security notice. |
| announcement | changes | News that is none of the above. |
| marketing | neither | Promotional mail; dropped by default. |
| unknown | changes | Mail the rules could not place; a review queue, not a guess. |
Severity, priority and impact are three different things. Severity is the vendor’s word. Priority (low, normal, high, urgent) is what the platform assigned from the category and severity, and it decides immediate delivery. Impact is whether your customers are affected, and it is never inferred.
Duplicates. Repeated updates to the same thing are folded: the later events carry duplicate_of, attach to the same incident timeline, and never alert again. Events a new source back-fills from its history are marked and not delivered.
Incident timeline
An incident groups the updates about one upstream problem. It has two lifecycles that are never merged: upstream (open, monitoring, resolved; severity; affected components) is the vendor’s and read-only; ours (unreviewed, investigating, affected, cleared; customer impact; an impact note; acknowledged; snoozed) is set by a person or your agent. An incident is open for us until we clear it, whatever the vendor says. A maintenance window is a timeline with a scheduled start and end; it lives on the Upcoming tab and in /maintenance endpoints. See Incidents and tickets.
Rule, destination, delivery, digest
A rule matches events (category, severity, priority, dependency, source, environment) and sends them to destinations with a mode: immediate, digest or suppress. A destination is an email address, an HTTPS webhook, or a ticket system (Jira, Linear, GitHub Issues, Statuspage); ticket systems take escalations, never routed events. A delivery is one attempt to send one event or digest to one destination, with its outcome. The digest gathers the routine events for a project and goes out daily at 08:00 UTC unless the project sets a schedule. See Rules, digests and quiet hours.
Inbox, action, sender rule, preference
The inbox is what arrived at the project’s inbound address, with who sent it and whether that could be verified. An action is something only a person can do: confirm a subscription, judge an unknown sender, approve a proposed removal. A sender rule teaches the inbox about a sender: trust, classify as a category, or suppress. A preference belongs to a dependency: ignore categories, sources or named senders, or anything below a severity. See Email and the inbox.
Key and scope
An API key (co_live_…) belongs to a workspace, optionally to one project, and carries scopes. The dashboard’s own calls carry a short-lived token for the signed-in person instead. Every write through either is audited. See the REST API.