Templates and roles

Three objects, in a line. A template holds roles and settings. A room references a template. A token references a role.

• template is created once per kind of call you run: a consultation, a class, a webinar.
• room takes template_idat creation. Leave it out and the project's default template is used, if it has one.
• token takes role. The role must exist in the room's template or the request fails with 404 role_not_found.

Roles arrive as a map keyed by name. A name must match [a-zA-Z0-9_-]{1,64}.

curl -X POST https://api.usevelo.xyz/v1/templates \
  -H "Authorization: Bearer $VELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "clinic",
    "roles": {
      "practitioner": {
        "publish": { "allowed": ["audio", "video", "screen"] },
        "subscribe": { "to_roles": ["practitioner", "patient"] },
        "permissions": {
          "mute_others": true,
          "remove_others": true,
          "change_role": true
        },
        "priority": 1
      },
      "patient": {
        "publish": { "allowed": ["audio", "video"] },
        "permissions": { "send_data": true },
        "max_peer_count": 1
      }
    }
  }'

The response returns the template with every role normalised: defaults filled in, simulcast layers resolved, and each role echoed back exactly as the media path will read it. Point a room at it.

curl -X POST https://api.usevelo.xyz/v1/rooms \
  -H "Authorization: Bearer $VELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "consultation-42", "template_id": "tpl_0123456789ab"}'

The same thing through the SDK, where role fields are camelCase.

import { VeloClient } from "@usevelo/client";

const velo = new VeloClient({
  baseUrl: "https://api.usevelo.xyz",
  apiKey: process.env.VELO_API_KEY as string,
});

const template = await velo.createTemplate("clinic", {
  roles: {
    practitioner: {
      publish: { allowed: ["audio", "video", "screen"] },
      subscribe: { toRoles: ["practitioner", "patient"] },
      permissions: { removeOthers: true, muteOthers: true, changeRole: true },
      priority: 1,
    },
    patient: {
      publish: { allowed: ["audio", "video"] },
      permissions: { sendData: true },
      maxPeerCount: 1,
    },
  },
});

await velo.createRoom("consultation-42", { templateId: template.id });

subscribe.to_roles is what turns a set of roles into a shape. A webinar is a speaker role that subscribes to speakers, and an attendee role that subscribes to speakers only. Nobody has to filter tracks client side, because attendees never receive them.

• Omit to_roles and it is filled in with every role in the template, including this one.
• Set subscribe.enabled to false and the role receives nothing at all.
• Every name in to_roles must be a role that exists in the same template, or the request is rejected with 400 invalid_role naming the offending index.
• The graph does not have to be symmetric. Speakers can receive attendees without attendees receiving each other.

max_peer_count is enforced at mint time. Asking for a role that is already full fails with 409 role_capacity_reached, and the message says how many the role allows and how many are already in the room. A role set to -1 rejects everyone, which is how you retire a role without deleting it.

priority runs 1 to 5, lower being more important, and rides along on the publish profile so a client can decide what to keep when bandwidth runs short.

PATCH /v1/templates/{id} is surgical: roles named in the body are created or replaced, roles left out are untouched. PUT /v1/templates/{id}/roles/{name} replaces one role whole, so every field you omit falls back to its default rather than to the value it had before. Read the role, edit it, send it back.

A participant can also be moved between roles mid-call. Grants and the velo.role attribute apply immediately; advisory publish hints only take effect when that participant republishes. Every change is written to an append-only audit trail.

curl -X POST \
  https://api.usevelo.xyz/v1/rooms/consultation-42/participants/patient-1187/role \
  -H "Authorization: Bearer $VELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "practitioner"}'

The endpoints that read and write all of this are listed in the REST API reference.