Summary: 7Mind authored its HTTP APIs in TypeSpec inside the api-contracts repo and shipped the resulting OpenAPI 3 specs as Redoc HTML on GitHub Pages, treating the published site as a shared coordination artefact rather than as generated client code. The repo’s main has not changed since 2026-07-23. Sources: direct code inspection of api-contracts (main.tsp, tspconfig.yaml, package.json, .github/workflows/, docker/); api-contracts origin/main and open PRs, and the Gymondo-git/function-sevenmind-legacy-gateway README, re-read on 2026-11-09 Last updated: 2026-11-09


After the 2026-09-14 migration. The contracts describe the API that elixir-backend implemented. The same SevenMind paths are now answered by function-sevenmind-legacy-gateway, which treats the contract as frozen, so the SevenMind contract is still a useful reference for request and response shapes. The SevenSleep and Identity services are dead (7Sleep sunset, identity moved to Gymondo SSO, see gymondo-sso-auth). For the exact routes the gateway serves, its README endpoint table is more accurate than this repo: the last contract change on main was on 2026-07-23, the SOS toolkit contract (PR #102) was never merged, and routes the gateway added later are missing. New Gymondo APIs are not modelled here.

What is captured

The repo defines five parallel services, each in its own root file under contracts/:

  • SevenMind — the consumer-facing 7Mind API (magic.7mind.de)
  • SevenSleep — the consumer-facing 7Sleep API (magic.7sleep.de)
  • Identity — the identity service (id.7mind.de) plus a SuperTokens sub-namespace covering deprecated direct-to-SuperTokens routes
  • Internal — internal endpoints (admin, healthchecks, Prometheus metrics)
  • External — third-party APIs the backend called, today only Aury (contracts/external/aury/aury.tsp)

Within each service, bounded contexts live in subfolders matching the modulith-domain-model domains on the server side: access, activation, analytics, content, monetization, practice, prevention, user. Each context owns its own .tsp file (and optional subfolder for large contexts like practice and content).

Shared building blocks live in contracts/shared/:

  • common.tsp — error models (Error<S>, CommonError, PremiumError, etc.), the three auth schemes, locale and versioning header aliases
  • prevention_models.tsp — ZPP / prevention models reused across services
  • search.tsp — Algolia search configuration

Toolchain

.tsp files                   contracts/**/*.tsp
   │
   │  @typespec/openapi3 emitter (tspconfig.yaml)
   ▼
specs.<service>.yaml         tsp-output/@typespec/openapi3/
   │
   ├─ @redocly/cli ──▶ static HTML (publish/<service>/index.html)
   │                       │
   │                       └─ GitHub Pages: sevenmind.github.io/api-contracts/
   │
   └─ outofcoffee/imposter-all ──▶ local mock API (ports 5080-5083)

Build-time dependencies (npm, pinned to latest): @typespec/compiler, @typespec/http, @typespec/openapi3, @typespec/rest, @redocly/cli. Runtime: none.

The OpenAPI YAML is the only emitted artefact today. No client SDKs are auto-generated — mobile and web clients hand-write their wire types and use the published spec as the agreed source of truth. If automated code generation is added later, update both this page and the api-contracts repo note.

How a new endpoint gets added

  1. Pick the right service and bounded context (or create a new .tsp under contracts/<service>/<context>/ and import it from <service>/<context>.tsp).
  2. Add models and an interface with @route, @summary, @doc decorators.
  3. Apply one of the three auth schemes from Shared.Common.Requests via @useAuth.
  4. Run npm run format (or just format) — the format check is enforced in CI.
  5. Open a PR. A “PR Preview” comment will appear linking to …/preview/pr_<number> with the rendered Redoc site.
  6. After merge, push to main triggers the publish workflow and the live docs update.

Publish pipeline

  • .github/workflows/check.yml — format + compile matrix on every push.
  • .github/workflows/publish-pr-preview.yml — builds HTML on PR open/sync, uploads pr_<number> artefact (30-day retention), posts/updates the preview comment.
  • .github/workflows/publish-main.yml — on push to main, calls reusable-publish.yml.
  • .github/workflows/reusable-publish.yml — the production GitHub Pages deploy; downloads open PR preview artefacts so previews remain visible alongside main.
  • .github/workflows/post-to-changelog.yml — posts to the #backend-squad-changelog Slack channel when a merged PR has the changelog label.

What agents in other repos should know

  • The published spec is not production-accurate. It was written for elixir-backend, and it now lags the gateway. When you spot drift, opening a PR against api-contracts is encouraged.
  • The #deprecated markers on /user_identity/* (in favour of /user/*) are out of date. The platform migration reversed that plan: the gateway serves /user_identity/*, the website moved there with TP-570, and only /user/signout and /user/password/reset/send are still served under /user/. Target the paths in the gateway README.
  • The mock API (localhost:5080-5083 via just serve) is useful for client development without a live backend.
  • Adding or changing a contract is a code-owned activity — see the CODEOWNERS rules in the api-contracts repo note.