Documentation

FrameRelay docs

Setting up a workspace, preparing your network and using the API. Current version 2.14.3.

Overview

A FrameRelay workspace holds your projects, people and media. Inside a project you can open live review rooms, upload and share files, and sync folders between workstations with the agent.

Workspaces are invite-only. Someone has to invite you, or your request for access has to be approved, before you can sign in.

Joining a workspace

  1. Open the invite email and copy the code. It looks like FR-7K2Q-91XD and is valid for 7 days.
  2. Go to framerelay.xyz/invite and enter the code.
  3. Confirm your email. From then on you sign in with a one-time link, so there's no password to forget.
Lost the invite or it expired? Ask your workspace admin to send a new one from Settings → People.

Desktop app and agent

The desktop app hosts live rooms and manages uploads. It installs the sync agent, a background service that starts with the system and keeps one connection open to the nearest edge.

  • macOS 12 or later, Apple silicon or Intel
  • Windows 10 or 11, x64 or ARM64
  • Ubuntu 22.04+, Debian 12+, Fedora 39+

Signed-in members of a workspace can download it from the download page. Updates install automatically in the background.

Network requirements

FrameRelay only needs outbound TCP 443. Allow the following hosts on your studio firewall or proxy:

HostPortProtocolUsed for
framerelay.xyz443HTTPSWeb app, sign-in, invites
static.framerelay.xyz443HTTPSScripts, fonts, images
api.framerelay.xyz443HTTPSAuth, projects, comments, events
edge.framerelay.xyz443TLS 1.3 over TCPLive rooms, sync agent connection
cdn.framerelay.xyz443HTTPSUploads, downloads, review links

TLS inspection

The desktop app and the agent pin FrameRelay's certificates. If your firewall decrypts and re-signs TLS traffic, connections to edge.framerelay.xyz and cdn.framerelay.xyz will fail. Add all five hosts to the inspection bypass list.

Long-lived connections

Edge connections stay open for hours, sometimes days, and carry a steady stream of data. Set idle timeouts on proxies and NAT gateways to at least 60 minutes. The agent sends a heartbeat every 30 seconds, so a healthy connection is never truly idle.

Edge IP addresses can change when we add capacity. Allow by hostname, not by IP.

Bandwidth guide

Live rooms adapt to the slowest reviewer. These are the figures to plan around per connection:

ActivityTypicalPeak
Live room, 4K 10-bit25–35 Mbps50 Mbps
Live room, 1080p 10-bit8–12 Mbps18 Mbps
Reviewer audio and camera0.5–1.5 Mbps2.5 Mbps
Sync agent, active project20–200 GB/dayYour limit
Sync agent, idle<1 MB/hour—

To cap the agent, open Settings → Bandwidth and add a schedule. Limits apply per workstation.

API overview

The REST API lets you automate projects, uploads and review links. All requests go to:

https://api.framerelay.xyz/v2

Requests and responses are JSON. Timestamps are ISO 8601 in UTC. Every response carries an x-request-id header; include it when you contact support.

Authentication

Create a token in Workspace settings → API. Tokens are scoped to one workspace and can be read-only.

curl https://api.framerelay.xyz/v2/projects \
  -H "Authorization: Bearer fr_live_••••••••••••"

Requests without a valid token get 401:

{ "error": "unauthorized", "message": "Missing or invalid bearer token" }

Endpoints

MethodPathDescription
GET/v2/projectsList projects in the workspace
GET/v2/projects/:id/assetsList assets in a project
POST/v2/uploadsStart a resumable upload, returns part URLs on cdn
POST/v2/review-linksCreate a signed review link
DELETE/v2/review-links/:idRevoke a review link everywhere
GET/v2/roomsList active live rooms
GET/v2/eventsServer-sent event stream for the workspace

Rate limits

Each token can make 600 requests per minute. Over the limit you get 429 with a Retry-After header. Upload part requests to cdn.framerelay.xyz don't count toward the limit.

Webhooks

Register an HTTPS endpoint in Workspace settings → Webhooks. We send asset.ready, comment.created, room.started, room.ended and link.viewed. Every request is signed with HMAC-SHA256 in the x-fr-signature header.

# verify a webhook signature
expected = hmac_sha256(secret, timestamp + "." + raw_body)