Getting started

The shared preview is a live environment backed by a seeded PostgreSQL database. Public resources are ready without configuration; authenticated flows work with test accounts after you obtain the fixture password from the project team.

Preview base URL
https://zombies.necodex.dev/api/v1. The documentation host is separate; it does not prefix API requests.

1. Call public data

Begin with GET /home. It contains the landing composition: live state, events, content, and community preview. No token is required; sending one only personalizes locks, membership state, and RSVPs.

curl https://zombies.necodex.dev/api/v1/home \
  -H 'Accept: application/json'

All regular JSON responses use the same envelope:

{ "data": { /* resource payload */ }, "requestId": "optional-id" }

{ "error": { "code": "VIP_REQUIRED", "message": "…", "details": {}, "requestId": "…" } }

2. Create or restore a session

Use POST /auth/register for a new Human account or POST /auth/login for a fixture. Store the returned opaque token in platform secure storage. Send it only as Authorization: Bearer <token>.

POST /api/v1/auth/login
Content-Type: application/json

{ "email": "vip@siliconzombies.test", "password": "…" }

Do not decide access in the client.

VIP entitlement changes only after a verified payment webhook. A successful payment screen, redirect, or cached profile never grants a protected resource.

3. Design for locked content

Catalogue resources return VIP cards to all visitors so the product can show the upgrade path. Use access: "vip" as descriptive entitlement metadata and locked: true for the current viewer state. Do not request an audio stream until the user presses play.

4. Handle safe errors

Status	Client behavior
`401`	Clear the stored session and direct the user to sign in.
`403 VIP_REQUIRED`	Open the membership CTA; never retry the protected action automatically.
`403 VIP_APPROVAL_REQUIRED`	Show the VIP application status instead of a payment action.
`422`	Render safe field details returned by the server.
`429 / 503`	Use bounded retry UI. Do not expose provider error details to members.

Next: use the Flutter integration guide →