1# RealtimeKit API Reference
2 
3Complete API reference for Meeting object, REST endpoints, and SDK methods.
4 
5## Meeting Object API
6 
7### `meeting.self` - Local Participant
8 
9```typescript
10// Properties: id, userId, name, audioEnabled, videoEnabled, screenShareEnabled, audioTrack, videoTrack, screenShareTracks, roomJoined, roomState
11// Methods
12await meeting.self.enableAudio() / disableAudio() / enableVideo() / disableVideo() / enableScreenShare() / disableScreenShare()
13await meeting.self.setName("Name")  // Before join only
14await meeting.self.setDevice(device)
15const devices = await meeting.self.getAllDevices() / getAudioDevices() / getVideoDevices() / getSpeakerDevices()
16// Events: 'roomJoined', 'audioUpdate', 'videoUpdate', 'screenShareUpdate', 'deviceUpdate', 'deviceListUpdate'
17meeting.self.on('roomJoined', () => {})
18meeting.self.on('audioUpdate', ({ audioEnabled, audioTrack }) => {})
19```
20 
21### `meeting.participants` - Remote Participants
22 
23**Collections**:
24```typescript
25meeting.participants.joined / active / waitlisted / pinned  // Maps
26const participants = meeting.participants.joined.toArray()
27const count = meeting.participants.joined.size()
28const p = meeting.participants.joined.get('peer-id')
29```
30 
31**Participant Properties**:
32```typescript
33participant.id / userId / name
34participant.audioEnabled / videoEnabled / screenShareEnabled
35participant.audioTrack / videoTrack / screenShareTracks
36```
37 
38**Events**:
39```typescript
40meeting.participants.joined.on('participantJoined', (participant) => {})
41meeting.participants.joined.on('participantLeft', (participant) => {})
42```
43 
44### `meeting.meta` - Metadata
45```typescript
46meeting.meta.meetingId / meetingTitle / meetingStartedTimestamp
47```
48 
49### `meeting.chat` - Chat
50```typescript
51meeting.chat.messages  // Array
52await meeting.chat.sendTextMessage("Hello") / sendImageMessage(file)
53meeting.chat.on('chatUpdate', ({ message, messages }) => {})
54```
55 
56### `meeting.polls` - Polling
57```typescript
58meeting.polls.items  // Array
59await meeting.polls.create(question, options, anonymous, hideVotes)
60await meeting.polls.vote(pollId, optionIndex)
61```
62 
63### `meeting.plugins` - Collaborative Apps
64```typescript
65meeting.plugins.all  // Array
66await meeting.plugins.activate(pluginId) / deactivate()
67```
68 
69### `meeting.ai` - AI Features
70```typescript
71meeting.ai.transcripts  // Live transcriptions (when enabled in Preset)
72```
73 
74### Core Methods
75```typescript
76await meeting.join()   // Emits 'roomJoined' on meeting.self
77await meeting.leave()
78```
79 
80## TypeScript Types
81 
82```typescript
83import type { RealtimeKitClient, States, UIConfig, Participant } from '@cloudflare/realtimekit';
84 
85// Main interface
86interface RealtimeKitClient {
87  self: SelfState;          // Local participant (id, userId, name, audioEnabled, videoEnabled, roomJoined, roomState)
88  participants: { joined, active, waitlisted, pinned };  // Reactive Maps
89  chat: ChatNamespace;      // messages[], sendTextMessage(), sendImageMessage()
90  polls: PollsNamespace;    // items[], create(), vote()
91  plugins: PluginsNamespace;  // all[], activate(), deactivate()
92  ai: AINamespace;          // transcripts[]
93  meta: MetaState;          // meetingId, meetingTitle, meetingStartedTimestamp
94  join(): Promise<void>;
95  leave(): Promise<void>;
96}
97 
98// Participant (self & remote share same shape)
99interface Participant {
100  id: string;                      // Peer ID (changes on rejoin)
101  userId: string;                  // Persistent participant ID
102  name: string;
103  audioEnabled: boolean;
104  videoEnabled: boolean;
105  screenShareEnabled: boolean;
106  audioTrack: MediaStreamTrack | null;
107  videoTrack: MediaStreamTrack | null;
108  screenShareTracks: MediaStreamTrack[];
109}
110```
111 
112## Store Architecture
113 
114RealtimeKit uses reactive store (event-driven updates, live Maps):
115 
116```typescript
117// Subscribe to state changes
118meeting.self.on('audioUpdate', ({ audioEnabled, audioTrack }) => {});
119meeting.participants.joined.on('participantJoined', (p) => {});
120 
121// Access current state synchronously
122const isAudioOn = meeting.self.audioEnabled;
123const count = meeting.participants.joined.size();
124```
125 
126**Key principles:** State updates emit events after changes. Use `.toArray()` sparingly. Collections are live Maps.
127 
128## REST API
129 
130Base: `https://api.cloudflare.com/client/v4/accounts/{account_id}/realtime/kit/{app_id}`
131 
132### Meetings
133```bash
134GET    /meetings                                    # List all
135GET    /meetings/{meeting_id}                       # Get details
136POST   /meetings                                    # Create: {"title": "..."}
137PATCH  /meetings/{meeting_id}                       # Update: {"title": "...", "record_on_start": true}
138```
139 
140### Participants
141```bash
142GET    /meetings/{meeting_id}/participants                          # List all
143GET    /meetings/{meeting_id}/participants/{participant_id}         # Get details
144POST   /meetings/{meeting_id}/participants                          # Add: {"name": "...", "preset_name": "...", "custom_participant_id": "..."}
145PATCH  /meetings/{meeting_id}/participants/{participant_id}         # Update: {"name": "...", "preset_name": "..."}
146DELETE /meetings/{meeting_id}/participants/{participant_id}         # Delete
147POST   /meetings/{meeting_id}/participants/{participant_id}/token   # Refresh token
148```
149 
150### Active Session
151```bash
152GET  /meetings/{meeting_id}/active-session               # Get active session
153POST /meetings/{meeting_id}/active-session/kick          # Kick users: {"user_ids": ["id1", "id2"]}
154POST /meetings/{meeting_id}/active-session/kick-all      # Kick all
155POST /meetings/{meeting_id}/active-session/poll          # Create poll: {"question": "...", "options": [...], "anonymous": false}
156```
157 
158### Recording
159```bash
160GET  /recordings?meeting_id={meeting_id}                 # List recordings
161GET  /recordings/active-recording/{meeting_id}           # Get active recording
162POST /recordings                                         # Start: {"meeting_id": "...", "type": "composite"} (or "track")
163PUT  /recordings/{recording_id}                          # Control: {"action": "pause"} (or "resume", "stop")
164POST /recordings/track                                   # Track recording: {"meeting_id": "...", "layers": [...]}
165```
166 
167### Livestreaming
168```bash
169GET  /livestreams?exclude_meetings=false                                # List all
170GET  /livestreams/{livestream_id}                                       # Get details
171POST /meetings/{meeting_id}/livestreams                                 # Start for meeting
172POST /meetings/{meeting_id}/active-livestream/stop                      # Stop
173POST /livestreams                                                       # Create independent: returns {ingest_server, stream_key, playback_url}
174```
175 
176### Sessions & Analytics
177```bash
178GET  /sessions                                                          # List all
179GET  /sessions/{session_id}                                             # Get details
180GET  /sessions/{session_id}/participants                                # List participants
181GET  /sessions/{session_id}/participants/{participant_id}               # Call stats
182GET  /sessions/{session_id}/chat                                        # Download chat CSV
183GET  /sessions/{session_id}/transcript                                  # Download transcript CSV
184GET  /sessions/{session_id}/summary                                     # Get summary
185POST /sessions/{session_id}/summary                                     # Generate summary
186GET  /analytics/daywise?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD      # Day-wise analytics
187GET  /analytics/livestreams/overall                                     # Livestream analytics
188```
189 
190### Webhooks
191```bash
192GET    /webhooks                    # List all
193POST   /webhooks                    # Create: {"url": "https://...", "events": ["session.started", "session.ended"]}
194PATCH  /webhooks/{webhook_id}       # Update
195DELETE /webhooks/{webhook_id}       # Delete
196```
197 
198## Session Lifecycle
199 
200```
201Initialization → Join Intent → [Waitlist?] → Meeting Screen (Stage) → Ended
202                                   ↓ Approved
203                               [Rejected → Ended]
204```
205 
206UI Kit handles state transitions automatically.
207 
208## See Also
209 
210- [Configuration](./configuration.md) - Setup and installation
211- [Patterns](./patterns.md) - Usage examples
212- [README](./README.md) - Overview and quick start
213