API Endpoints

Retrieving Usage Statistics

Use this endpoint to retrieve statistics about your account's usage.

Request

GET https://api.upscope.io/v1.4/usage

Response

// HTTP 200
{
  "status": "ok",
  "usage": {
      "agents": {
          "last_30_days": 10,
          "today": 0
      },
      "session_counts": {
          "last_30_days": 20,
          "now": 0,
          "today": 0
      },
      "session_seconds": {
          "last_30_days": 5000,
          "today": 0
      },
      "visitors": {
          "last_24_hrs": 50000,
          "last_30_days": 50000,
          "online_now": 400
      }
  }
}

Field	Type	Description
`usage.agents.last_30_days`	`integer`	Number of Agents who used Co-Browsing API in the last 30 days.
`usage.agents.today`	`integer`	Number of Agents who used Co-Browsing API in the last 24 hours.
`usage.session_counts.last_30_days`	`integer`	Number of Sessions in the last 30 days.
`usage.session_counts.now`	`integer`	Number of Sessions currently ongoing.
`usage.session_counts.today`	`integer`	Number of Sessions in the last 24 hours.
`usage.session_seconds.last_30_days`	`integer`	Number of Session seconds in the past 30 days.
`usage.session_seconds.today`	`integer`	Number of Session seconds in the past 24 hours.
`usage.visitors.last_24_hrs`	`integer`	Number of Visitors in the past 24 hours.
`usage.visitors.last_30_days`	`integer`	Number of Visitors in the past 30 days.
`usage.visitors.online_now`	`integer`	Number of Visitors online now.

Searching for a Visitor or Retrieving a List of Visitors

Use this endpoint to search for a particular Visitor or to show a list of recently online Visitors.

Know the Visitor's ID?

If you know the Visitor's ID, avoid using the search functionality and instead use the direct endpoint, which will be considerably faster.

Need just 1 result?

Make sure to set max_results to 1. This will be considerably faster as our API service will be making a bunch of parallel requests to all the co-browsing regions you have enabled, and by setting to 1, it can respond to you as soon as it gets the first result.

Request

GET https://api.upscope.io/v1.4/list

Parameter	Type	Description
`search`	`string`	The search query in this format. If left empty, the latest Visitors will be returned.
`max_results`	`number`	The max number of results to return, up to 10. Defaults to 10. Setting this to `1` will make the search faster.

Response

// HTTP 200
{
  "status": "ok",
  "visitors": [
    {
      "short_id": "1234",
      // ...
    }
  ]
}

Field	Type	Description
`visitors`	`Visitor[]`	List of Visitors matching the query.

Retrieving a Visitor

Use this endpoint to retrieve a particular Visitor.

Request

GET https://api.upscope.io/v1.4/visitors/{visitor_id}

Parameter	Type	Description
`{visitor_id}`	`string`	The short id of the Visitor.

Response

// HTTP 200
{
  "status": "ok",
  "visitor": {
    "short_id": "1234",
    "sessions": [
      // ...
    ],
    // ...
  }
}

Field	Type	Description
`visitor`	`Visitor`	The Visitor.
`visitor.sessions`	`Session[]`	List of the Visitor's last 50 Sessions.

Errors

Code	Description
`404`	The Visitor does not exist.

Use this endpoint to generate a secure watch link that enables whoever opens it to start a co-browsing Session with the Visitor without needing to be logged into Co-Browsing API as an Agent.

Short lived link

The link returned by this endpoint expires after a few minutes (see the expiration field in the response). It is not meant to be stored anywhere. Ideally, the Agent will make a request to an endpoint on your server, which makes this request behind the scenes and redirects the Agent to the watch_url immediately. This allows you to handle failed requests by setting up a branding.retry_url. Your integration should never store the secure watch link anywhere (server or browser), and instead use it as soon as possible.

Single use link

The link returned by this endpoint is single use. You need to make sure any proxy does not pre-scan the URL and in doing so invalidate the link. If you can, bypass any https://cobrowsingapi.com/session/* from the proxy. Sharing the link on slack or teams while testing (or copying it some clipboard history apps open) might cause a request to be made by the app which invalidates the link.

Request

POST https://api.upscope.io/v1.4/visitors/{visitor_id}/watch_url
{
  "branding": {
    "naked": true,
  },
  "permissions": {},
  "viewer": {
    "id": "123",
    "name": "Joe Smith"
  },
  "metadata": {},
  "webhook_url": "https://example.com"
}

Parameter	Type	Description
`{visitor_id}`	`string`	The short id of the Visitor.
`viewer.id`	`string`	The ID of the person viewing the screen (required).
`viewer.name`	`string`, optional	The name of the person viewing the screen.
`branding.naked`	`false`, `true`, or `"page_only"`	If `true`, the Co-Browsing API logo will not be shown on the page. This is ideal if you want to display the page inside an iframe. Defaults to `false`. Can be set to `page_only` to remove everything, including the viewer's UI. You can then control the Session by post-messaging the iframe.
`branding.show_end_button`	`boolean`, optional	Whether an "End session" button should be shown on the viewer page.
`branding.on_end_url`	`string`, optional	If set, the viewer will be redirected to this URL after the Session ends. If not set, the window will be attempted to be closed. Defaults to `null`.
`branding.retry_url`	`string`, optional	If set, the visitor will be able to click a "Retry now" link that redirects to this URL if there are problems. When `null`, no button is displayed. Defaults to `null`.
`initial_notes`	`string`, optional	The starting state of the notes for the Session. You can use this to add a template of what they should fill out.
`metadata`	`Record`, optional	A JSON-encodeable object of metadata to add to the Session object. This can be used when retrieving a list of Sessions to run your own analytics. The object should be flat, meaning values can only be strings, numbers, or booleans.
`permissions.allow_audio`	`boolean`	Whether the viewer should have access to audio calls (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_click`	`boolean`	Whether the viewer should have access to remote click (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_confetti`	`boolean`	Whether the viewer should have access to throw confetti (defaults to `true`).
`permissions.allow_console`	`boolean`	Whether the viewer should have access to remote console capabilities (defaults to `false`).
`permissions.allow_draw`	`boolean`	Whether the viewer should have access to drawing (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_redirect`	`boolean`	Whether the viewer should have access to remote redirect & reload features (defaults to `true`, unless disabled through the Javascript SDK). Called `allow_agent_redirect` before v1.4.
`permissions.allow_request_control`	`boolean`	Whether the viewer should be able to request remote control when the Visitor's SDK requires a control request (defaults to `true`).
`permissions.allow_request_full_tab`	`boolean`	Whether the viewer should be able to request full browser tab sharing (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_request_mode`	`boolean`	Whether the viewer should be able to request a different sharing mode, such as full screen sharing (defaults to `true`).
`permissions.allow_request_visitor_screen`	`boolean`	Whether the viewer should be able to ask the Visitor to share their full screen (defaults to `true`).
`permissions.allow_scroll`	`boolean`	Whether the viewer should have access to remote scroll (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_show_viewer_screen`	`boolean`	Whether the viewer should be able to share their screen to the Visitor (defaults to `true`). Called `allow_show_agent_screen` before v1.4.
`permissions.allow_type`	`boolean`	Whether the viewer should have access to remote type (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_video`	`boolean`	Whether the viewer should have access to video calls (defaults to `true`).
`permissions.hide_private_details`	`boolean`	Whether the Visitor private information (such as IP address) should be hidden from the viewer (defaults to `false`).
`permissions.keeps_session_alive`	`boolean`	Whether this viewer keeps the Session alive. Set to `false` for silent observers, so the Session ends when the last keep-alive viewer leaves (defaults to `true`).
`session_properties.controller`	`Array<"viewer" \| "visitor">`, optional	Which sides of the Session can start audio or video calls and request a different sharing mode. Defaults to `["viewer"]`.
`session_properties.record`	`boolean`, optional	Whether this Session should be recorded. Defaults to your team's session recording setting. Setting it to `true` requires the session recording feature on your plan.
`language`	`string`	The language to use for the interface. Defaults to the user's browser.
`webhook_url`	`string`, URL, optional	After the session is ended, a POST request will be made to this URL, sending the Session data as JSON.

Upgrading from v1.3?

The agent object was replaced by the viewer object, and viewer.id is now required. The permissions.allow_agent_redirect and permissions.allow_show_agent_screen options were renamed to permissions.allow_redirect and permissions.allow_show_viewer_screen, and permissions.allow_notes was removed. Requests to the /v1.3/ endpoints keep working with the old names.

Response

HTTP 200
{
    "status": "ok",
    "watch_url": "https://cobrowsingapi.com/session/a964e00a-c685-4d54-98d4-ea0bcb154d57",
    "expiration": "2022-01-11T18:01:49.700Z"
}

Field	Type	Description
`expiration`	`Datetime` (ISO 8601)	Time at which the link is no longer valid.
`watch_url`	`string`	The Secure watch URL.

Errors

Code	Description
`404`	The Visitor does not exist.
`402`	This Session would put you over your subscription limits.
`409`	The Visitor's browser is not supported.

Generating a Viewer Token to Embed Co-Browsing

Use this endpoint to generate a viewer token instead of a watch link. The token lets you embed the co-browsing screen directly in your own application with the viewer SDK, instead of opening the hosted watch page.

Calling this endpoint counts as the intent to co-browse: the Session is created right away, so only request a token when the viewer is about to connect.

Request

POST https://api.upscope.io/v1.4/visitors/{visitor_id}/viewer_token
{
  "permissions": {},
  "viewer": {
    "id": "123",
    "name": "Joe Smith"
  },
  "metadata": {},
  "webhook_url": "https://example.com"
}

Parameter	Type	Description
`{visitor_id}`	`string`	The short id of the Visitor.
`viewer.id`	`string`	The ID of the person viewing the screen (required).
`viewer.name`	`string`, optional	The name of the person viewing the screen.
`initial_notes`	`string`, optional	The starting state of the notes for the Session.
`metadata`	`Record`, optional	A JSON-encodeable object of metadata to add to the Session object.
`permissions.allow_audio`	`boolean`	Whether the viewer should have access to audio calls (defaults to `true`, unless disabled through the Javascript SDK). Not available on premise.
`permissions.allow_click`	`boolean`	Whether the viewer should have access to remote click (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_confetti`	`boolean`	Whether the viewer should have access to throw confetti (defaults to `true`).
`permissions.allow_console`	`boolean`	Whether the viewer should have access to remote console capabilities (defaults to `false`).
`permissions.allow_draw`	`boolean`	Whether the viewer should have access to drawing (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_redirect`	`boolean`	Whether the viewer should have access to remote redirect & reload features (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_request_control`	`boolean`	Whether the viewer should be able to request remote control when the Visitor's SDK requires a control request (defaults to `true`).
`permissions.allow_request_full_tab`	`boolean`	Whether the viewer should be able to request full browser tab sharing (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_request_mode`	`boolean`	Whether the viewer should be able to request a different sharing mode, such as full screen sharing (defaults to `true`).
`permissions.allow_request_visitor_screen`	`boolean`	Whether the viewer should be able to ask the Visitor to share their full screen (defaults to `true`).
`permissions.allow_scroll`	`boolean`	Whether the viewer should have access to remote scroll (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_show_viewer_screen`	`boolean`	Whether the viewer should be able to share their screen to the Visitor (defaults to `true`).
`permissions.allow_type`	`boolean`	Whether the viewer should have access to remote type (defaults to `true`, unless disabled through the Javascript SDK).
`permissions.allow_video`	`boolean`	Whether the viewer should have access to video calls (defaults to `true`). Not available on premise.
`permissions.hide_private_details`	`boolean`	Whether the Visitor private information (such as IP address) should be hidden from the viewer (defaults to `false`).
`permissions.keeps_session_alive`	`boolean`	Whether this viewer keeps the Session alive. Set to `false` for silent observers, so the Session ends when the last keep-alive viewer leaves (defaults to `true`).
`session_properties.controller`	`Array<"viewer" \| "visitor">`, optional	Which sides of the Session can start audio or video calls and request a different sharing mode. Defaults to `["viewer"]`.
`session_properties.record`	`boolean`, optional	Whether this Session should be recorded. Defaults to your team's session recording setting. Setting it to `true` requires the session recording feature on your plan. On premise, the recording is stored on and retrieved from your own server.
`webhook_url`	`string`, URL, optional	After the session is ended, a POST request will be made to this URL, sending the Session data as JSON.

Response

// HTTP 200
{
    "status": "ok",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
    "endpoint": "https://data--eu.upscope.io",
    "region": "eu",
    "short_id": "1234",
    "expiration": "2026-01-11T18:01:49.700Z"
}

Field	Type	Description
`token`	`string`	The token to pass to the viewer SDK.
`endpoint`	`string`	The server the viewer should connect to. For on-premise accounts, this is your own on-premise endpoint.
`region`	`string`	The region the Visitor is connected to (`onpremise` for on-premise accounts).
`short_id`	`string`	The short id of the Visitor.
`expiration`	`Datetime` (ISO 8601)	Time at which the token is no longer valid. Use it right away.

Errors

Code	Description
`400`	Your on-premise endpoint or secret key is not configured (on-premise accounts only).
`404`	The Visitor does not exist.
`402`	This Session would put you over your subscription limits.
`409`	The Visitor's browser is not supported.

The response fields map directly onto the viewer SDK's ViewerProvider props. As with watch links, the token should be requested by your server and handed to the browser right before connecting. See Embedding with the Viewer SDK for how to use the token.

Stopping an Active Session

Use this endpoint to stop an active Session.

Request

DELETE https://api.upscope.io/v1.4/visitors/{visitor_id}/session

Parameter	Type	Description
`{visitor_id}`	`string`	The short id of the Visitor.

Response

// HTTP 200
{
  "status": "ok"
}

Errors

Code	Description
`404`	The Visitor does not exist.

Deleting a Visitor from Co-Browsing API

Use this endpoint to delete a Visitor from Co-Browsing API entirely. You can only delete Visitors who are not currently online.

Request

DELETE https://api.upscope.io/v1.4/visitors/{visitor_id}

Parameter	Type	Description
`{visitor_id}`	`string`	The short id of the Visitor.

Response

// HTTP 200
{
  "status": "ok"
}

Errors

Code	Description
`404`	The Visitor does not exist.
`409`	The Visitor is online, or one of their Sessions is still ongoing or has a recording still processing.

Deleting All Visitors from Co-Browsing API

Use this endpoint to delete all Visitors from your Co-Browsing API account. This will delete only Visitors that are offline.

Request

DELETE https://api.upscope.io/v1.4/visitors?all=true

Parameter	Type	Description
`all`	`boolean`	Set to `true` to confirm deleting all Visitors.

Response

// HTTP 200
{
  "status": "ok"
}

Agent Lookup

Use this endpoint to lookup an agent from your Co-Browsing API account.

You must send either the email or the external_id

Using the email it will lookup for users from your account, while using the external_id it will lookup for external agents from your account. If you use any other parameter rather than email or external_id it will return not found.

Request

GET https://api.upscope.io/v1.4/agents/lookup?email=john@acme.com

Parameter	Type	Description
`email`	`string` (Only specify `email` or `external_id`)	The Agent email, this will return a HelloScreen or UserView user.
`external_id`	`string` (Only specify `email` or `external_id`)	The External Agent id, this will return a Co-Browsing API Agent.

Response

// HTTP 200
{
  "agent": {
    "id": "u_1234",
    // ... Agent data
  },
  "status": "ok"
}

Field	Type	Description
`agent`	`Agent`	The Agent who started or joined the Session as an observer
`agent.sessions`	`Session[]`	The list of the agent's last 10 sessions.

Errors

Code	Description
`404`	Agent not found

Retrieving a List of Sessions

Use this endpoint to retrieve a list of Sessions.

Request

GET https://api.upscope.io/v1.4/cobrowsing_sessions/list

Parameter	Type	Description
`before_id`	`string`, optional	Only list Sessions that happened before the Session with the specified id (used for pagination)
`after_id`	`string`, optional	Only list Sessions that happened after the Session with the specified id (used for pagination)
`ongoing_only`	`boolean` (defaults to `false`)	Only list Sessions that are currently active.
`updated_after`	`Datetime`, optional	Only list Sessions that have had some sort of update to their record after this time.

Response

// HTTP 200
{
    "status": "ok",
    "cobrowsing_sessions": [
      {
        id: "s_123",
		// ... Session details
      }
	],
    "has_more": true,
    "last_id": "s_456"
}

Field	Type	Description
`cobrowsing_sessions`	`Session[]`	A list of Sessions, sorted by start date, from first to last.
`has_more`	`boolean`	Whether there are more Sessions matching your filter. (If so, paginate by changing the `after_id`)
`last_id`	`string \| null`	The id of the last Session. This is always the same as the last Session from the array, and can be used as a cursor with `after_id`.

Authorizing an On-Premise Session

Use this endpoint to authorize an on-premise Session.

Using our Dashboard?

If you have integrated your on-premise version of Co-Browsing API to our dashboard, you don't need to use the API. It all just works.

Request

POST https://api.upscope.io/v1.4/onpremise/token
{
  "visitor_id": "VISITOR123",
  "agent": {
    "id": "123",
    "name": "Joe Smith"
  }
}

Parameter	Type	Description
`agent.id`	`string`	The ID of the Agent (required).
`agent.name`	`string`, optional	The name of the Agent.
`visitor_id`	`string`	The ID of the Visitor you want to co-browse with.

Response

// HTTP 200
{
    "authorized": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkw...."
}

Field	Type	Description
`authorized`	`boolean`	`true` to indicate the Session was authorized.
`token`	`string`	The `token` to send to the on-premise version of Co-Browsing API.

Errors

Code	Description
`402`	This session was not authorized.

Documentation

API Endpoints

Retrieving Usage Statistics

Searching for a Visitor or Retrieving a List of Visitors

Know the Visitor's ID?

Need just 1 result?

Retrieving a Visitor

Generating a Link to Start Screen Sharing with a Visitor

Short lived link

Single use link

Upgrading from v1.3?

Generating a Viewer Token to Embed Co-Browsing

Stopping an Active Session

Deleting a Visitor from Co-Browsing API

Deleting All Visitors from Co-Browsing API

Agent Lookup

You must send either the email or the external_id

Retrieving a List of Sessions

Authorizing an On-Premise Session

Using our Dashboard?