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-09-12 — New members use normal DSS signup

POST /v1/partners/sponsorships no longer creates a Digital Sea Service account. An unknown email returns account_requires_signup (409) with signup_url. Send Set up my DSS account to /signin?intent=signup&partner=ywc&…. Premium is granted on Connect.

​
2026-09-12 — Account exists is enough

Additive / loosening. Partners that already handled 404 still work. A Connected member with a DSS account is a valid member even with no vessel and no crew list. They add vessels and discharge dates inside the DSS app. Do not treat an empty record as unreachable or incomplete. GET /v1/me/sea-time and /recent therefore return 200 with zero totals (and an empty months array) when the member exists but has no qualifying sea days yet. GET /v1/me/vessels returns 200 with an empty list. A true 404 means the token’s user is unknown to DSS. The DSS Homepage button for an already-Connected YWC member must mint POST /v1/partners/sso/tickets and redirect to login_url. That opens the app signed in; with no fleet they land on add-vessel. Do not link https://digitalseaservice.com.

​
2026-09-09 — YWC partner SSO

Additive. Nothing existing changed shape.

​
Endpoints

  • POST /v1/partners/sso/tickets — Yacht Workers Council only. Mint a 60-second, single-use login URL so an already-Connected member opens the DSS app signed in. HTTP Basic. Body: { "user_id": "<dss uid>" }. Requires live Connect consent. See Open DSS (YWC SSO).

​
2026-09-09 — YWC member-left

Additive. Nothing existing changed shape.

​
Endpoints

  • POST /v1/partners/members/left — Yacht Workers Council only. Close the Connect-billed Crew Premium seat when a member leaves, lapses, or deletes their YWC account. HTTP Basic (client_id:client_secret). Body: user_id (DSS Firebase uid from Connect), optional external_ref (ywc-user-{id}), optional reason (account_deleted | membership_lapsed). Idempotent. See Member left (YWC).

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