# Server HTTP API

> Raw HTTP endpoints for managing P2P calls and rooms. Every endpoint here takes a secret key (`rad_sk_...`) and must only be called from your backend.

Base URL `https://radist.tech`. All responses are JSON. Authenticate with `Authorization: Bearer rad_sk_...`.

## P2P calls

### `POST /api/v1/projects/:projectId/calls`

Creates a call and auto-mints two participant tokens.

```ts
const response = await fetch(`https://radist.tech/api/v1/projects/${projectId}/calls`, {
	method: 'POST',
	headers: { Authorization: 'Bearer <your secret key>' }
});

const { callId, callTokens } = await response.json();
const [hostCallToken, guestCallToken] = callTokens;
```

| Status | Response                                                         |
| ------ | ---------------------------------------------------------------- |
| `200`  | `{ "callId": "uuid", "callTokens": ["ct_...", "ct_..."] }`       |
| `401`  | `{ "error": "Missing bearer token." }` or invalid project id/key |
| `429`  | `{ "error": "Connection limit reached." }`                       |

### `GET /api/v1/projects/:projectId/calls`

Lists calls for the project. Query parameters: `page` (default 1) and `limit`.

| Status | Response                                                                                        |
| ------ | ----------------------------------------------------------------------------------------------- |
| `200`  | `{ "calls": [{ "callId", "createdAt", "tombstonedAt" }], "page": 1, "limit": 20, "total": 42 }` |
| `400`  | `{ "error": "Invalid page query parameter." }`                                                  |
| `401`  | `{ "error": "Missing bearer token." }` or invalid project id/key                                |

## SFU rooms

Calls with more than two participants use rooms. Create a room from your backend, mint one room token per participant, and each participant connects to the room signaling WebSocket. Audio and video are forwarded through a mediasoup worker.

### `POST /api/v1/projects/:projectId/rooms`

Creates a room and auto-mints two room tokens: `{ roomId, roomTokens }`.

### `POST /api/v1/projects/:projectId/rooms/:roomId/token`

Mints an additional room token for an existing room: `{ roomToken }`.

## Persistent spaces

Spaces are managed under `/api/v1/projects/:projectId/spaces` with the same secret-key auth — create, list, get, update, delete, and `POST .../spaces/:spaceId/rotate-host-token`. The server SDKs wrap these; see /docs/server/js.md.

## Billing

Every second each participant is connected to a room is reported to Stripe as `radist_sfu_participant_seconds`. The 30-day total is visible on the project billing page.