REST API
Build cobrowsing into your own product
A REST API and a React viewer SDK. Install the SDK on your pages, ask the API for a session from your server, and show the customer's screen in a new tab or inside your own app.
Let anyone see anyone else's screen, safely
The UserView product connects your support agents to your customers. The API removes that limit. Your server decides who watches whom, and hands each viewer a link or token that expires in minutes and carries only the permissions you chose.
Peer to peer
The viewer doesn't have to be an agent. A teacher and a student, an advisor and a client, two colleagues: any user of your product can view another user's screen, in either direction.
No UserView login
Viewers never get a UserView account or a password to remember. Your app already knows who they are, so your server asks for a short-lived link on their behalf and sends them straight in.
Several viewers, different permissions
More than one person can join the same screen, each with their own permissions. One can click and type, another can only draw, and a third can watch without the session depending on them.
Your server decides
Every session starts with a call from your backend, signed with a secret key that never reaches a browser.
Links expire in minutes
A watch link lasts 5 minutes by default and a viewer token 60 seconds. Neither is meant to be stored.
Permissions per viewer
Switch remote click, typing, drawing, redirects and calls on or off for each link you hand out.
Masking still applies
Anything you mask in the SDK stays hidden while cobrowsing, whoever is watching. Full-screen and full-device sharing show the raw screen, and you can turn them off.
How it differs from the UserView product
UserView is a finished support tool: your agents sign in and help your customers. The API is the same cobrowsing engine without the tool around it, for when you decide who connects to whom and where it happens.
| UserView, the product | The REST API | |
|---|---|---|
| Who can watch | Your agents | Anyone your app chooses: agents, customers, partners, other users |
| Who signs in | Each agent has a UserView account | Nobody. Your app vouches for the viewer |
| Where a session starts | The UserView dashboard or a helpdesk integration | Anywhere in your own code |
| What the viewer looks like | The UserView viewer | The hosted viewer, an unbranded iframe, or your own React UI |
| What you build | Nothing. Paste one snippet | The snippet, plus one server call per viewer |
What you can do with it
You don't need the API to use UserView: the standard install is one snippet and our dashboard. Use the API when a session should start somewhere else, such as a tool your agents already use, a product you sell, or an automated process.
Let agents start a session without leaving their tools
Put a “View screen” button in your helpdesk, CRM or internal admin. Your backend asks for a watch link and redirects the agent to it. No second console, no searching for the customer.
POST /visitors/{id}/watch_urlPut cobrowsing inside a product you sell
Render the session in your own UI with the React viewer SDK, or iframe the hosted viewer with our branding switched off. White-label cobrowsing: your toolbar, your layout, no UserView logo.
POST /visitors/{id}/viewer_token@upscopeio/viewer-sdkTrigger sessions from your own workflows
End a session when the ticket closes. Delete visitor records on your own retention schedule. Pass a webhook_url and we POST the session data to you when it ends.
DELETE /visitors/{id}/sessionDELETE /visitors/{id}Pull session data into your own reporting
List past sessions with filters and read account usage as JSON, then load it into whatever you already report from.
GET /cobrowsing_sessions/listGET /usageFour calls, from ticket to closed session
The whole lifecycle: find the visitor, open their screen, clean up afterwards.
- Step 1
A ticket comes in
You already have the customer's email or user ID.
no API call needed - Step 2
Find them
Search by email, name or the ID you set in the SDK. Skip this if you already store the visitor ID.
GET /list?search=…&max_results=1 - Step 3
Open their screen
Ask for a watch link to redirect to, or a viewer token to embed.
POST …/watch_urlPOST …/viewer_token - Step 4
Close it out
End the session when the ticket closes, and delete the record when you no longer need it.
DELETE …/session
Send them a link, or put the screen inside your own app
Same request body, different endpoint. One returns a URL, the other a token.
A watch link
Returns a URL that is valid for 5 minutes by default. Redirect the agent to it and the hosted viewer opens in its own tab. The agent doesn't need a UserView login. Set branding.naked to drop our chrome and iframe it.
POST /v1.4/visitors/{visitor_id}/watch_url{ "viewer": { "id": "123", "name": "Joe Smith" } }// 200{ "watch_url": "https://userview.com/session/a964…", "expiration": "2026-01-11T18:01:49.700Z" }
Embedded in your own product
Returns a token that lasts 60 seconds by default, so request it right before connecting. Pass it to the React viewer SDK and render the screen wherever you want it. You build the toolbar; hooks give you session state and controls.
import { ViewerProvider, Content } from "@upscopeio/viewer-sdk";<ViewerProvider token={token} shortId={shortId} region={region} idleDisconnectSeconds={600}> <Content color="red" controlTool="cursor" maxWidth={1200} maxHeight={1200} /></ViewerProvider>
Every endpoint, grouped by job
The same lifecycle, with the calls each stage uses.
Find the right visitor
Search by email, name or your own identifiers, or list who is online now. If you already know the visitor ID, fetch it directly: it is much faster than searching.
GET /listGET /visitors/{id}Start a session from your own code
Generate a secure watch link and redirect the agent to it. Set permissions per link (remote control, redirect, screen share) and choose how long it stays valid.
POST /visitors/{id}/watch_urlEmbed cobrowsing in your product
Issue a viewer token and render the session inside your own application with the viewer SDK. This is the route for white-label and embedded builds.
POST /visitors/{id}/viewer_tokenManage sessions and data
End a live session, list past sessions with filters, look up an agent by email or external ID, and delete visitor records on request.
DELETE /visitors/{id}/sessionGET /cobrowsing_sessions/listGET /agents/lookupAuthentication
Send your secret key in an X-Api-Key header on every request.
Keep it on your server. It is not the public key from the browser snippet, and the dashboard shows it once. If you get api_not_enabled, the API isn’t switched on for your account yet: get in touch.
| 401 | Reason |
|---|---|
| invalid_api_key | Key missing or not found |
| no_subscription | Subscription has expired |
| api_not_enabled | Plan doesn't include the API |
| please_contact_team | Access restricted |
Endpoints
Paths are relative to https://api.upscope.io/v1.4/. Requests and responses are JSON.
| Method | Path | Purpose |
|---|---|---|
| GET | /usage | Account usage statistics |
| GET | /list | Search visitors, or list recently active ones |
| GET | /visitors/{visitor_id} | Retrieve one visitor's details |
| POST | /visitors/{visitor_id}/watch_url | Generate a secure link to view their screen |
| POST | /visitors/{visitor_id}/viewer_token | Token to embed cobrowsing in your own app |
| DELETE | /visitors/{visitor_id}/session | End an active session |
| DELETE | /visitors/{visitor_id} | Remove a visitor |
| DELETE | /visitors?all=true | Remove all offline visitors |
| GET | /agents/lookup | Look up an agent by email or external ID |
| GET | /cobrowsing_sessions/list | List sessions, with filtering |
| POST | /onpremise/token | Authorise an on-premise session |
Request bodies, object types, search syntax and embedded session control are in the full API documentation.
Works on-premise too
Running UserView on your own servers keeps the same API. Sessions are authorised through POST /onpremise/token, and the viewer token points at your own endpoint.
Prefer the SDK?
If you only need cobrowsing on your own site, the JavaScript and mobile SDKs are enough: one snippet, no server code. The API is for embedding, automating or white-labelling.
SDK installation docsTransform your customer support
Join hundreds of companies using UserView to deliver faster, more effective customer support experiences.