SlideStage Pro API Reference

This page is a compact reference for the public SlideStage Pro v0 HTTP API.

All business routes are mounted under /api. Authentication uses Better Auth session cookies.

Error shape

{
  "error": {
    "code": "STRING_CODE",
    "message": "Human-readable message",
    "details": {}
  }
}

Clients should branch on error.code.

Auth levels

• Public: no session required.
• Authenticated: valid session required.
• Admin: valid session and user.role === "admin".

Health

GET /api/health

Public readiness endpoint.

Returns status, version, uptimeSeconds, and checks for database and storage.

Auth

Better Auth owns /api/auth/*.

Method	Path	Access	Purpose
POST	/api/auth/sign-in/email	Public	Email sign-in.
POST	/api/auth/sign-out	Authenticated	Sign out.
POST	/api/auth/sign-up/email	Public + invite	Invite-gated signup.
GET	/api/auth/get-session	Public	Current session or null.

Signup must include inviteToken.

Decks

GET /api/decks

Authenticated. Lists decks visible to the current user.

POST /api/decks

Authenticated. Uploads a new .stage file.

Form fields:

• file: required .stage zip.
• title: optional title override.

The server checks size, hashes bytes, loads the deck through @slidestage/core, validates the manifest, checks paths, stores the blob, and writes database records in a transaction.

GET /api/decks/:id

Authenticated. Reads deck details.

GET /api/decks/:id/blob

Authenticated. Streams the current .stage blob.

DELETE /api/decks/:id

Authenticated. Deletes a deck when the user is allowed to do so.

Notes and annotations

Pro stores server-side notes and annotation payloads per deck/slide.

Treat annotation JSON as an opaque client payload.

Admin invites

Admins can list, create, and revoke invite tokens. Invites are one-time registration gates.

Compatibility

Pro does not define the .stage format. It consumes @slidestage/core and @slidestage/spec.