API v1 stability

What we promise about this contract

If you are deciding whether to build on this API, this is the page that answers it. What can change without warning, what gets 90 days, and how you find out.

v1 stable Contract version: 2026-07-14 Breaking-change notice: 90 days

The promise

/api/v1 is stable. Breaking changes ship as a new major path — /api/v2 — never in place. A URL that works today keeps working.
Breaking changes get 90 days notice, published here and carried on the affected responses as Deprecation and Sunset headers. The deprecated thing keeps working for the entire window.
Additive changes can arrive at any time. Your client must ignore fields it does not recognise.

Two version strings do different jobs, and it is worth keeping them apart. X-ArcNautical-API-Version dates the wire contract — the shape of requests and responses. methodology_version, returned on every assessment, pins the scoring and is what makes a score reproducible. They move independently: we can improve scoring without touching the contract, and the reverse.

Additive changes — any time, no notice

These are not breaking, and we ship them without a notice period:

New fields on existing responses.
New optional request fields.
New endpoints.
New values in fields already documented as open-ended.

Read new fields defensively. An assessment is stored exactly as it was returned, and GET /api/v1/voyage-assessments/{id} replays that stored copy byte-for-byte — that is what makes it an audit record. So a field added last week will be absent from an assessment created last month. Treat every field as optional on retrieval, even ones that are always present on fresh calls.

Breaking changes — 90 days

We treat all of these as breaking:

Removing or renaming a response field.
Narrowing a type, or changing what an existing value means.
Removing an endpoint, or removing a value from a closed enum.
Tightening validation so a request we used to accept now fails.
Making an optional request field required.

None of these ship without the full 90-day window first. If we ever need to move faster than that, it will be for a security or legal reason, we will say so explicitly in the changelog, and it will not be quiet.

How you are told

A dated entry in the changelog below, naming what is deprecated and the date it stops working. This always happens.
deprecated: true on the affected field or operation in the OpenAPI document, which most client generators surface as a compile-time or lint warning. This is the signal for a field.
Deprecation and Sunset response headers when an endpoint is being retired, per RFC 8594.

Those last two are deliberately not interchangeable. Sunset is defined as a statement about a resource, so putting it on a response whose endpoint is staying would tell you the whole endpoint is going away. When a single field is deprecated the OpenAPI marker is the accurate signal, and the changelog says so in words.

The changelog is the record of what actually shipped. It is not a roadmap and we do not announce work here before it exists.

Currently deprecated

What	Replaced by	Stops working
`source_status` on the assessment response	`sources` — same status, plus `checked_at` and `basis`	2026-10-31 (removal ships as v2)

Both fields are populated today and will stay that way for the whole window, so you can migrate whenever suits you. sources reports the same per-source status source_status does, and adds when each source was last known-good.

What we do not promise

Being specific about the gaps is more useful to you than a vague assurance.

No uptime SLA. We do not publish one and do not currently offer contractual availability terms. If you need one, write to us.
No public status page. Health is not externally observable today.
Scores change as the world does. Reproducibility is scoped to a stored assessment, which you can always re-read by id. The same route scored again tomorrow can legitimately return a different number — that is the product working, not a contract break. methodology_version tells you whether the model changed underneath it.
Upstream sources can degrade. When one does, the assessment says so rather than hiding it — check source_status and missing_sources on every response.

API changelog

Newest first. Dates are the day the change reached production.

2026-08-02

Assessments now report per-source freshnessAdded Deprecates

Assessment responses carry a new sources array: each signal’s status as before, plus checked_at and a basis saying what that timestamp means. Previously the response said a source was ok without ever saying when it was last good, so a sanctions list refreshed four days ago was indistinguishable from one refreshed four minutes ago.

checked_at is null wherever we do not genuinely know it — two of the eleven signals carry no timestamp anywhere in their fetch path, and those report basis: "unknown" rather than a filled-in request time. Read basis before comparing timestamps across sources: latest_event_at dates the newest record we hold, which is not the same claim as refreshed_at.

source_status is deprecated by this and keeps working until 2026-10-31. Both fields are populated in the meantime.

2026-08-02

Corridor monitor and webhook endpoints now work with self-serve keysFixed

Keys created through the developer portal were minted with only voyage:score and usage:read, while 12 of the 18 published operations require voyage:monitor or webhooks:manage. Those endpoints returned 403 insufficient_scope to every self-serve key, even though the account’s GET /api/v1/usage reported corridor monitors as available.

New keys now carry all four scopes. Existing keys that still held the old two-scope default have been widened in place — you do not need to rotate. Keys where scopes were set explicitly were left untouched.

2026-08-02

API key creation fixed for accounts created without a passwordFixed

Two of the four sign-up paths did not grant the external API entitlement, so createApiKey returned 403 for accounts created through them and no key could be issued at all. All sign-up paths now grant it, and key creation provisions it on demand if it is ever missing.

2026-07-31

Corridor monitors included in the self-serve allowanceAdded

Monitor runs are now metered against the same monthly assessment quota as interactive calls, so the feature could be granted rather than withheld. Self-serve keys carry 10 corridor monitors at a 6-hour cadence.

2026-07-30

Live API keys became self-serveAdded

Live and test keys are both issued from the developer portal without a manual provisioning step. Live carries 10,000 assessments a month, test 1,000. Neither expires and neither is a trial.