# 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

```json
{
  "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`.