# DSS Public API

> Public OAuth 2.0 API for Digital Sea Service. Approved partner platforms read a crew member's verified sea-time, vessel history, and profile with the crew member's explicit consent. Read-only V1, opaque tokens, signed webhooks, RFC 7807 errors. Base URLs: `https://api.digitalseaservice.com` (production), `https://api.dev.digitalseaservice.com` (sandbox).

## Get started

- [Introduction](https://docs.digitalseaservice.com/introduction.md): What's in V1, base URLs, support contacts, AI-readability summary.
- [Quickstart](https://docs.digitalseaservice.com/quickstart.md): 15-minute walkthrough from credentials to a successful `/v1/me` call, with cURL, Python, and Node samples.
- [Authentication](https://docs.digitalseaservice.com/authentication.md): OAuth 2.0 Authorization Code + PKCE end-to-end, scopes, refresh, revocation, failure modes. PKCE generators in cURL, Python, Node, PHP, Go.
- [Rate limits](https://docs.digitalseaservice.com/rate-limits.md): Per-`client_id` sliding-window budgets (600/min, 10,000/day), `X-RateLimit-*` headers, conditional-GET cost model, recommended polling intervals.

## Webhooks

- [Webhooks overview](https://docs.digitalseaservice.com/webhooks/overview.md): Signed delivery model, retry schedule, ordering rules, registration, the `/v1/webhooks/test` endpoint.
- [Event catalogue](https://docs.digitalseaservice.com/webhooks/events.md): Every event we send (`user.profile.updated`, `user.sea_time.updated`, `user.vessels.updated`, `user.consent.revoked`, `webhook.test`) with payload samples and recommended actions.
- [Signature verification](https://docs.digitalseaservice.com/webhooks/verification.md): Drop-in verifier code in Python and Node, FastAPI / Flask / Express / Next.js handler examples, replay-window rules.

## Errors

- [Errors overview](https://docs.digitalseaservice.com/errors.md): RFC 7807 Problem Details shape, how to branch on `type`, how to use `X-Request-Id` for support.
- [invalid_request (400)](https://docs.digitalseaservice.com/errors/invalid_request.md): Malformed request — missing parameter, bad cursor, schema failure.
- [invalid_token (401)](https://docs.digitalseaservice.com/errors/invalid_token.md): Missing, expired, or revoked access token; auto-refresh recipe.
- [insufficient_scope (403)](https://docs.digitalseaservice.com/errors/insufficient_scope.md): Token valid but missing the required scope; reconsent path.
- [partner_suspended (403)](https://docs.digitalseaservice.com/errors/partner_suspended.md): Partner account suspended; account-level, returned by the webhook self-test.
- [not_found (404)](https://docs.digitalseaservice.com/errors/not_found.md): URL or resource doesn't exist; how to distinguish.
- [no_webhook_configured (409)](https://docs.digitalseaservice.com/errors/no_webhook_configured.md): Called the webhook self-test before registering a URL and signing secret.
- [rate_limit_exceeded (429)](https://docs.digitalseaservice.com/errors/rate_limit_exceeded.md): Budgets, `Retry-After`, backoff recipe.
- [internal_error (500)](https://docs.digitalseaservice.com/errors/internal_error.md): Server-side failure, retry-with-backoff guidance, support flow.

## API reference

- [API reference overview](https://docs.digitalseaservice.com/api-reference/overview.md): Where the spec lives and how to feed it into AI agents.
- [OpenAPI 3.1 spec (JSON)](https://docs.digitalseaservice.com/api-reference/openapi.json): Full machine-readable contract — endpoints, schemas, examples, scopes.
- [OpenAPI 3.1 spec (YAML)](https://docs.digitalseaservice.com/api-reference/openapi.yaml): Same content, YAML for AI ingestion.
- [Live spec (production)](https://api.digitalseaservice.com/openapi.json): Always-current spec from the running API.

## Resources

- [Changelog](https://docs.digitalseaservice.com/changelog.md): Breaking-change policy, versioning rules, and the V1 launch entry.
- [Status page](https://status.digitalseaservice.com): Live uptime and incident history.

## Optional

- [llms-full.txt](https://docs.digitalseaservice.com/llms-full.txt): Every documentation page concatenated as one markdown file, ready to drop into an AI context.