We version this API at the URL path. /v1/* runs at least 12 months past /v2 launch, with the deprecation schedule announced on this page and via email to every active partner contact. What counts as a breaking change:
  • Removing or renaming any field, endpoint, header, error code, or scope.
  • Tightening a validation rule on an existing field.
  • Changing the shape of a webhook payload.
  • Removing or changing the meaning of an event type.
What does not count as a breaking change:
  • Adding a new endpoint, field, header, error code, or scope.
  • Adding a new event type.
  • Loosening a validation rule.
  • Adding a new optional query parameter.
We try to be conservative about additive changes too — every new field is something partners may end up depending on by accident. We announce them here first.

​
2026-05-28 — V1 launch

First public release of the DSS Public API.

​
Authentication

  • OAuth 2.0 Authorization Code flow with PKCE (S256 required).
  • Opaque access tokens (1-hour TTL) and rotating refresh tokens (90-day TTL).
  • RFC 7009 token revocation.

​
Endpoints

  • GET /v1/me — basic profile (profile:read).
  • GET /v1/me/sea-time — totals, by-role breakdown, verified split (seatime:read).
  • GET /v1/me/sea-time/recent — rolling 12-month trend (seatime:read).
  • GET /v1/me/vessels — paginated vessel history (vessels:read).
  • GET /v1/webhooks/test — fires a webhook.test event to your registered URL.

​
Caching

  • ETag + If-None-Match on every resource.
  • Last-Modified + If-Modified-Since on every resource.

​
Rate limits

  • 600 / minute, 10,000 / day, per client_id.
  • X-RateLimit-* headers on every authenticated response.

​
Webhooks

  • Event types: user.profile.updated, user.sea_time.updated, user.vessels.updated, user.consent.revoked, webhook.test.
  • HMAC-SHA256 signing with a 5-minute replay window.
  • Retry schedule: +1m, +5m, +30m, +2h, +6h. Give up after 24h.

​
Errors

  • Resource endpoints: RFC 7807 Problem Details with stable type URLs.
  • OAuth endpoints: RFC 6749 §5.2 shape.

​
Docs

  • Mintlify docs site live at docs.digitalseaservice.com.
  • llms.txt, llms-full.txt, and every page as .md for AI agents.
  • OpenAPI 3.1 spec at /openapi.json and /openapi.yaml.

​
Subscribing to changes

We email every partner contact at the address you gave us during onboarding when anything ships here. We will not surprise you with a breaking change — the V1 → V2 transition will have its own announcement, its own dedicated docs section, and at least 12 months of overlap. For the truly paranoid: https://docs.digitalseaservice.com/llms-full.txt is the entire docs tree as a single file. Diff it.