REST /v1 (mobile)

Base path /v1, built with @hono/zod-openapi. It exists for the mobile app in the sibling tcgkl repo.

Browse the spec

	Production	Beta
Interactive docs	api.tcgkl.com/v1/docs	api-staging.tcgkl.com/v1/docs
OpenAPI 3.1 JSON	/v1/openapi.json	/v1/openapi.json

The spec is generated from the route definitions, so it cannot drift from the code. Do not hand-maintain a copy of it here.

Route groups

apps/api/src/v1/routes/ — auth, events, stamping, profile, feed, social, messaging, notifications, catalog, upload. The OpenAPI tags are finer-grained: Auth, Events, Stamping, Profile, Feed, Interactions, Comments, Follows, Moderation, Messaging, Notifications, Catalog, Shops, Search, Upload.

Authentication

Sessions are Better Auth sessions. POST /v1/auth/verify-otp or /v1/auth/social-login returns a session token — also in the set-auth-token response header — which the client sends as:

Authorization: Bearer <token>
Origin: https://api.tcgkl.com

The Origin header is required on credentialed requests. withSession middleware attaches the session to every /v1 request.

Errors

One envelope for everything, from apps/api/src/v1/errors.ts. A schema failure returns 400 with the first Zod issue rendered as path: message; an unknown route returns 404. This matches the contract the Fastify-era API had, so old clients keep working.

Adding a route

1. The business rule belongs in a tRPC procedure in packages/core.
2. Add the route in apps/api/src/v1/routes/<group>.ts with its Zod request and response schemas, so it appears in the OpenAPI output.
3. Call the procedure through createCaller (apps/api/src/v1/middleware.ts).
4. Tag it so it lands in the right section of the docs.

Caution

Never re-implement a rule in a /v1 handler. A validation or permission check that exists only here is one the web app does not have.