System

Operational and marketing-site endpoints. Grouped together because none of them fit into a first-class product surface.

Health

GET /v1/health-check

Health probe. Returns status and uptime if the database is reachable.

• Auth: Public
• Cache: public, max-age=30

Response — 200 OK

{
   "status": "OK",
   "uptime": "up 3 days, 4 hours, 12 minutes"
}

Errors

Mailing list

POST /v1/subscribe

Subscribe an email address to the KATFORGE mailing list. Sends a verification email; the address only receives marketing material after the user clicks the verification link.

• Auth: Public
• Rate limit: 5 / 60s

Request

{
   "email": "anders@example.com",
   "channels": [ "product", "marketing" ]
}

Response — 200 OK, empty body.

GET /v1/verify

Verify a mailing-list subscription via the token link in the verification email. Always redirects to a status page on the marketing site.

• Auth: Public

Query params: email, token.

Response — 302 redirect to:

• Success: <frontend>/status/verify?result=success
• Error: <frontend>/status/verify?result=error&code={missing_arguments|invalid_arguments}

GET /v1/unsubscribe

Unsubscribe an email address. Linked from the unsubscribe footer of outgoing emails.

• Auth: Public

Query params: email, token.

Response — 302 redirect to:

• Success: <frontend>/status/unsubscribe?result=success
• Error: <frontend>/status/unsubscribe?result=error&code={missing_arguments|invalid_arguments|not_found}

Contact

POST /v1/leads/contact

Submit a contact form. Stores the message in the leads table and forwards it to the KATFORGE inbox.

• Auth: Public
• Rate limit: 5 / 60s

Request

{
   "fullname": "Anders",
   "email": "anders@example.com",
   "discovery": "search",
   "subject": "How do I…",
   "message": "I'm trying to integrate the SDK with my React Native app and…"
}

Field	Type	Constraints
fullname	string	required, not blank, max 255 chars.
email	string	required, valid email.
discovery	string	required. How the sender heard about KATFORGE (e.g. search, friend, social_media).
subject	string	required, not blank.
message	string	required, 10–5000 chars.

Response — 201 Created, empty body.

Errors

Feedback

POST /v1/leads/feedback

Submit in-game feedback. Distinct from /v1/leads/contact: contacts capture acquisition data and trigger reply emails; feedback captures user opinions tagged by kind and source, with optional route and free-form context. Stored in the feedback table.

• Auth: Optional. When a bearer token is supplied, user_id and player_id are stamped from it. Guests submit anonymously and may attach an email for follow-up.
• Rate limit: 5 / 60s

Request

{
   "kind": "bug",
   "source": "stumper",
   "message": "The pause button doesn't work on iOS Safari.",
   "email": "anders@example.com",
   "route": "/play",
   "context": {
      "viewport": "390x844",
      "mode": "practice"
   }
}

Response — 201 Created, empty body.

Errors