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
SevenMindpaths are now answered by function-sevenmind-legacy-gateway, which treats the contract as frozen, so theSevenMindcontract is still a useful reference for request and response shapes. TheSevenSleepandIdentityservices 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 onmainwas 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 aSuperTokenssub-namespace covering deprecated direct-to-SuperTokens routesInternal— 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 aliasesprevention_models.tsp— ZPP / prevention models reused across servicessearch.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
- Pick the right service and bounded context (or create a new
.tspundercontracts/<service>/<context>/and import it from<service>/<context>.tsp). - Add models and an
interfacewith@route,@summary,@docdecorators. - Apply one of the three auth schemes from
Shared.Common.Requestsvia@useAuth. - Run
npm run format(orjust format) — the format check is enforced in CI. - Open a PR. A “PR Preview” comment will appear linking to
…/preview/pr_<number>with the rendered Redoc site. - After merge, push to
maintriggers 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, uploadspr_<number>artefact (30-day retention), posts/updates the preview comment..github/workflows/publish-main.yml— on push tomain, callsreusable-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-changelogSlack channel when a merged PR has thechangeloglabel.
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
#deprecatedmarkers 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/signoutand/user/password/reset/sendare still served under/user/. Target the paths in the gateway README. - The mock API (
localhost:5080-5083viajust serve) is useful for client development without a live backend. - Adding or changing a contract is a code-owned activity — see the
CODEOWNERSrules in the api-contracts repo note.
Related
- api-contracts — the repo this concept lives in
- api-versioning-headers — how clients declare app version and request a specific response version
- supertokens-auth — the three auth schemes are declared in
contracts/shared/common.tsp - chargebee-billing — Chargebee, Mondia and Fastspring webhook contracts live under
SevenMind.Monetization - modulith-domain-model — the contract bounded contexts mirror the backend domain layout
- elixir-backend — the primary server implementation of these contracts
- 7mind-mobile-apps-monorepo — a primary client of the contracts
- nuxt-website — another client of the contracts
- function-sevenmind-legacy-gateway — current implementation of the SevenMind contract