Introduction

Your first room is the guide itself, with copy-pasteable code. It assumes a project and one API key, and nothing else.

Two hosts, and they do different jobs. Everything you call from a server goes to the control plane. Everything a participant sends or receives goes to the media plane.

https://api.usevelo.xyz

The control plane. 53 JSON endpoints over HTTPS, authenticated with a project API key.

wss://rtc.usevelo.xyz

The media plane. Participants connect here with a token minted by the control plane, and never with a key.

The unit of configuration is a template. It holds roles, and a role decides what a participant may publish, who they receive, what they may moderate and how many people may hold that role at once. Your application names a role when it mints a token and stops thinking about permissions.

In order, because each one needs what the last one returned.

1. 1POST /v1/roomsA room. Named, capped, attached to a template.
2. 2POST /v1/tokensA token and a url. One identity, one room, one role, one hour.
3. 3WSS wss://rtc.usevelo.xyzA connected participant. This is the only request a client makes.
4. 4GET /v1/sessionsWho joined, as what role, for how long, with how many tracks.

Three pages carry the rest of the surface. Between them they cover how a call is configured, how a request is authenticated and what every endpoint does.

• Templates and rolesA role fixes what a participant may publish, who they receive and how many may hold it.View concepts→
• AuthenticationProject API keys, the vk_ prefix, and why a browser only ever holds a room token.View authentication→
• REST APIEvery project endpoint on https://api.usevelo.xyz, grouped by the resource it acts on.View reference→

The things people come here to do, each one linking to the part of a page that answers it.

• Create a room and mint a tokenThe two server-side calls, with the request bodies and what comes back.
• Join a call from the browserConnect with a token and url, publish camera and microphone, attach the tracks.
• Decide who may publish whatThe role fields that fix publish sources, moderation and default track settings.
• Let one role hear another without being seenThe subscribe graph, written as a role naming the roles it receives.
• Cap how many people hold a rolePriority and capacity, and what a participant sees when a role is full.
• Keep an API key out of the clientThe difference between a project key and a room token, and which one goes where.

What each package is, how you add it and what it does. Client packages join calls and nothing more, because an app binary cannot hold a secret. Every one of them carries the same chat and reactions helper, so a message sent from Android arrives on the web.

• Web@usevelo/clientnpmA server-side client for the REST API and a browser-safe join helper. The only SDK that accepts a project API key, and only outside the browser.
• React Native@usevelo/react-nativenpmRoom code exchange, connect, and a useVeloRoom hook for a screen. No project-key client, on purpose. Needs a development build rather than Expo Go.
• Androidcom.usevelo:velo-androidGradleKotlin, with connection state and participants exposed as state flows. Join path only, minSdk 24.
• iOSVeloClientSwift packageAdded from the Velo repository in Xcode or Package.swift. Async await throughout, and an observable room for SwiftUI. Join path only, iOS 15 and newer.
• Fluttervelo_clientgit dependencyDart, with room events as a stream. Added by git reference to the repository rather than from pub.dev. Join path only.

On a server, use @usevelo/client on Node, github.com/judeotine/velo/sdks/go on Go, or velo-sdk on Python. On any other backend, call the REST API directly, or generate a client from the OpenAPI document. The Postman collection is the runnable version of the same surface.