Advisories
An advisory is something a provider has announced about an operation your connection uses. Nothing has broken yet. It is kept apart from findings and incidents for that reason: an incident says "this is failing", an advisory says "this will change, and here is the date if there is one".
Seamward raises two kinds.
| Kind | Raised from | Carries a date |
|---|---|---|
| Deprecation notice | Deprecation and Sunset headers on the provider's responses to your calls | When Sunset is sent |
| Published contract change | A new version of the provider's OpenAPI document that you asked Seamward to watch | No |
What is not built
Seamward does not maintain a list of providers' documents, read changelogs or release feeds, or share anything between workspaces. A published contract is watched only when your team gives its address, and every advisory comes from your own traffic or from that document.
Deprecation notices
Many providers add headers to their responses months before retiring an operation or an API version. The collector reads them on your outbound calls:
| Header | What Seamward keeps |
|---|---|
Deprecation | That the operation is deprecated, and since when |
Sunset | The date the operation stops working |
API-Version, Stripe-Version and equivalents | The API version your calls are served under |
Only those headers are looked at, and each is kept only as a parsed date or a short version label. No header's text leaves your process. The envelope reference lists the exact headers and formats.
One advisory is kept per operation, and it follows what the provider currently says:
| State of the date | Shown as | When |
|---|---|---|
| More than 30 days away | Scheduled | A Sunset date is announced |
| 30 days away or closer | Within 30 days | The same advisory, as the date approaches |
| In the past | Date passed | Calls are still being made after the end date |
| None | No date | Deprecation is sent without a Sunset header |
A version header alone raises nothing. It is shown on the connection as the API version in use.
Connections fed only by OpenTelemetry traces raise no deprecation notices: a span does not carry response headers.
Published contract changes
Give Seamward the address of a provider's OpenAPI document and it fetches the document once a day. The first fetch is a baseline. When a later version differs, Seamward compares the two for the operations your connection has called in the last 30 days and raises an advisory for each one that changed.
| Change reported | Meaning |
|---|---|
| Field removed | A field in a request or response is no longer described |
| Field added | A new field is described |
| Now required | A field a caller must send, or may rely on receiving |
| Now optional | A field that may now be absent |
| Type changed | For example integer to string, or a field that may now be null |
| Allowed values changed | The count of values added to or removed from an enumeration; the values are not repeated |
| No longer described | The operation, or one of its request or response schemas, is gone |
An operation that is new in the document, or that your connection does not call, raises nothing. A published change is not proof that traffic has changed: if the payloads do change, drift detection raises a finding from what was observed, separately.
Set it up from the connection's Provider notices card, or see watching a published contract for the rules on what address is accepted and how failures are handled.
Deciding on an advisory
Open Advisories in the console. The list shows what needs attention, soonest date first.
| Action | Who | Effect |
|---|---|---|
| Acknowledge | Owner or admin | Records that your team has seen it. It stays in the list with its date |
| Dismiss | Owner or admin | Sets it aside. It moves to the Dismissed tab |
| Reopen | Owner or admin | Puts a dismissed advisory back |
Each decision is recorded in the audit trail with who made it.
Seamward reopens an advisory on its own in two cases, because both are new information: the provider moves the end date, or the published contract for the operation changes again. A countdown getting shorter does not reopen anything.
When a provider stops announcing a deprecation, the advisory is marked No longer applies and leaves the list. It is kept under All.
Seamward decides that from evidence, not from silence. A notice is taken back when a response for the operation says so, or when at least 20 answered calls for that operation, over at least 24 hours since the notice was last seen, carried no deprecation or sunset header. A connection with no traffic keeps its advisory. If the provider announces the change again, the advisory reopens.
Alerts
An alert destination subscribed to advisory.opened receives one alert when an advisory opens, one when its end date comes within 30 days (unless your team dismissed it), and one each time a watched contract changes an operation again.
Reading advisories elsewhere
| From | How |
|---|---|
| CLI | seamward advisories list --connection ID |
| MCP | The list_advisories tool, so an agent can plan a change ahead of the date |
Both are read-only. A decision is recorded in the console.
Boundaries
- An advisory is not an incident. It never opens one, never counts affected records, and never proposes a repair.
- A date is the provider's claim. Seamward reports what the header or document says. It does not verify that the provider will act on that date.
- Summaries quote the provider. An operation path or a field path comes from the provider's response or document. Treat it as data.
- A header that disappears is not tracked. If a provider stops sending
Sunsetand your collector reports nothing for that operation, the last notice stays until a newer one replaces it or your team dismisses it.
Next steps
- Contract registry: declare a contract and watch the provider's published one.
- Alerts: send advisories to your team.
- Drift detection: what is raised once traffic actually changes.