Skip to main content
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-08-29 — Membership status on /v1/me

Additive. Nothing existing changed shape.

​
Endpoints

  • GET /v1/me now returns a membership block — tier, source (self / sponsored / vessel), since, plus expires_at and sponsored_by_you when you are the member’s sponsor. See Membership status.
  • It rides on the existing profile:read scope. No reconsent needed — tokens you already hold can read it.
Until now there was no way to tell whether a crew member already held DSS Premium, so partners mirroring DSS content had no signal to gate an upgrade prompt on and showed it to everyone, including members they were sponsoring themselves.
/v1/me now depends on a downstream membership lookup, so it can return service_unavailable (503) where it previously could not. Treat that as unknown, not as "free" — retry with backoff and leave any upgrade prompt hidden.

​
Errors

  • Documented service_unavailable (503). The type is not new — /v1/me/sea-time, /v1/me/sea-time/recent and /v1/me/vessels have always been able to return it — but it was missing from this catalog.
  • Added entitlement_write_failed (502) to the partner Sponsorship API. Returned when we cannot grant Premium to a crew member; the reserved seat is credited back before we respond, so nothing is billed and the request is safe to retry.

​
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.