1# API Reference
2 
3## Authentication
4 
5```bash
6curl -X POST 'https://rtc.live/v1/apps/${CALLS_APP_ID}/sessions/new' \
7  -H "Authorization: Bearer ${CALLS_APP_SECRET}"
8```
9 
10## Core Concepts
11 
12**Sessions:** PeerConnection to Cloudflare edge  
13**Tracks:** Media/data channels (audio/video/datachannel)  
14**No rooms:** Build presence via track sharing
15 
16## Client Libraries
17 
18**PartyTracks (Recommended):** Observable-based client library for production use. Handles device changes, network switches, ICE restarts automatically. Push/pull API with React hooks. See patterns.md for full examples.
19 
20```bash
21npm install partytracks @cloudflare/calls
22```
23 
24**Raw API:** Direct HTTP + WebRTC for custom requirements (documented below).
25 
26## Endpoints
27 
28### Create Session
29```http
30POST /v1/apps/{appId}/sessions/new
31→ {sessionId, sessionDescription}
32```
33 
34### Add Track (Publish)
35```http
36POST /v1/apps/{appId}/sessions/{sessionId}/tracks/new
37Body: {
38  sessionDescription: {sdp, type: "offer"},
39  tracks: [{location: "local", trackName: "my-video"}]
40}
41→ {sessionDescription, tracks: [{trackName}]}
42```
43 
44### Add Track (Subscribe)
45```http
46POST /v1/apps/{appId}/sessions/{sessionId}/tracks/new
47Body: {
48  tracks: [{
49    location: "remote",
50    trackName: "remote-track-id",
51    sessionId: "other-session-id"
52  }]
53}
54→ {sessionDescription} (server offer)
55```
56 
57### Renegotiate
58```http
59PUT /v1/apps/{appId}/sessions/{sessionId}/renegotiate
60Body: {sessionDescription: {sdp, type: "answer"}}
61```
62 
63### Close Tracks
64```http
65PUT /v1/apps/{appId}/sessions/{sessionId}/tracks/close
66Body: {tracks: [{trackName}]}
67→ {requiresImmediateRenegotiation: boolean}
68```
69 
70### Get Session
71```http
72GET /v1/apps/{appId}/sessions/{sessionId}
73→ {sessionId, tracks: TrackMetadata[]}
74```
75 
76## TypeScript Types
77 
78```typescript
79interface TrackMetadata {
80  trackName: string;
81  location: "local" | "remote";
82  sessionId?: string; // For remote tracks
83  mid?: string; // WebRTC mid
84}
85```
86 
87## WebRTC Flow
88 
89```typescript
90// 1. Create PeerConnection
91const pc = new RTCPeerConnection({
92  iceServers: [{urls: 'stun:stun.cloudflare.com:3478'}]
93});
94 
95// 2. Add tracks
96const stream = await navigator.mediaDevices.getUserMedia({video: true, audio: true});
97stream.getTracks().forEach(track => pc.addTrack(track, stream));
98 
99// 3. Create offer
100const offer = await pc.createOffer();
101await pc.setLocalDescription(offer);
102 
103// 4. Send to backend → Cloudflare API
104const response = await fetch('/api/new-session', {
105  method: 'POST',
106  body: JSON.stringify({sdp: offer.sdp})
107});
108 
109// 5. Set remote answer
110const {sessionDescription} = await response.json();
111await pc.setRemoteDescription(sessionDescription);
112```
113 
114## Publishing
115 
116```typescript
117const offer = await pc.createOffer();
118await pc.setLocalDescription(offer);
119 
120const res = await fetch(`/api/sessions/${sessionId}/tracks`, {
121  method: 'POST',
122  body: JSON.stringify({
123    sdp: offer.sdp,
124    tracks: [{location: 'local', trackName: 'my-video'}]
125  })
126});
127 
128const {sessionDescription, tracks} = await res.json();
129await pc.setRemoteDescription(sessionDescription);
130const publishedTrackId = tracks[0].trackName; // Share with others
131```
132 
133## Subscribing
134 
135```typescript
136const res = await fetch(`/api/sessions/${sessionId}/tracks`, {
137  method: 'POST',
138  body: JSON.stringify({
139    tracks: [{location: 'remote', trackName: remoteTrackId, sessionId: remoteSessionId}]
140  })
141});
142 
143const {sessionDescription} = await res.json();
144await pc.setRemoteDescription(sessionDescription);
145 
146const answer = await pc.createAnswer();
147await pc.setLocalDescription(answer);
148 
149await fetch(`/api/sessions/${sessionId}/renegotiate`, {
150  method: 'PUT',
151  body: JSON.stringify({sdp: answer.sdp})
152});
153 
154pc.ontrack = (event) => {
155  const [remoteStream] = event.streams;
156  videoElement.srcObject = remoteStream;
157};
158```
159