REST API (on premise)

On-Premise REST API Overview

The on-premise REST API functions similarly to the cloud version, with some differences detailed below.

Enabling the API

By default, the API is disabled. It will only be enabled when you add a REST_KEY environment variable.

Authentication

To authenticate your requests to the REST API, add an Authorization header set to the value you provided in the REST_KEY environment variable.

The Visitor Object

The Visitor object may differ slightly in the on-premise version, depending on your configuration. Most attributes will be present, and all Visitors will have the same properties.

Endpoints

On-premise, the REST API is mounted on the /api path of your base endpoint. For example, if your BASE_ENDPOINT is https://support.acmetech.com/cobrowsing, one of the endpoints will be https://support.acmetech.com/cobrowsing/api/visitors/list/latest.

Listing the Latest Visitors

Use this endpoint to list the latest online Visitors. This only works with MongoDB.

GET /v1.4/visitors/list/latest

Parameter	Type	Description
`max_results`	`number`, optional	The max number of results to return.

Response

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

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

Searching for a Visitor

Use this endpoint to search for Visitors.

GET /v1.4/visitors/list/search

Parameter	Type	Description
`q`	`string`, optional	The search query in this format. If left empty, the latest Visitors will be returned.
`max_results`	`number`, optional	The max number of results to return.

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 specific Visitor.

GET /v1.4/visitors/{visitor_id}

Parameter	Type	Description
`{visitor_id}`	`string`	The short id of the Visitor.
`includeHistory`	`boolean`, optional	Set to `true` to include the Visitor's pageview history (MongoDB only).

Response

// HTTP 200
{
  "status": "ok",
  "visitor": {
    "short_id": "1234",
    "history": [
      // Pageviews, if includeHistory was set to true
    ],
    // ...
  }
}

Field	Type	Description
`visitor`	`Visitor`	The Visitor.
`visitor.history`	`Pageview[]`, optional	The Visitor's latest pageviews. Only present with `includeHistory`.

Errors

Code	Description
`404`	The Visitor does not exist.

To start a Session with one of your Visitors, first obtain an authorization token from our server, then make a request to your on-premise REST API.

// POST /v1.4/visitors/{visitor_id}/watch_url
{
  "licenseToken": "token1234",
  "branding": {},
  "permissions": {},
  "viewer": {
    "id": "123",
    "name": "Joe Smith"
  }
}

Parameter	Type	Description
`{visitor_id}`	`string`	The short id of the Visitor.
`licenseToken`	`string`	The token obtained from here. Reach out to our team if this is incompatible with your flow for alternative options.
`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`	`"page_only"`, optional	Set to `"page_only"` to remove everything on the page except the shared screen, including the viewer's UI. Ideal when embedding the page inside an iframe.
`branding.show_end_button`	`boolean`, optional	Whether an "End session" button should be shown on the viewer page.
`branding.on_end_url`	`string \| null`, optional	If set, the viewer will be redirected to this URL after the Session ends. Defaults to `null`.
`branding.retry_url`	`string \| null`, optional	If set, the visitor can click a "Retry now" link that redirects to this URL if there are problems. Defaults to `null`.
`permissions.allow_click`	`boolean`, optional	Whether the viewer should have access to remote click (defaults to `true`).
`permissions.allow_confetti`	`boolean`, optional	Whether the viewer should be able to throw confetti (defaults to `true`).
`permissions.allow_console`	`boolean`, optional	Whether the viewer should have access to remote console capabilities (defaults to `false`).
`permissions.allow_draw`	`boolean`, optional	Whether the viewer should have access to drawing (defaults to `true`).
`permissions.allow_redirect`	`boolean`, optional	Whether the viewer should have access to remote redirect & reload features (defaults to `true`). Called `allow_agent_redirect` before v1.4.
`permissions.allow_request_control`	`boolean`, optional	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`, optional	Whether the viewer should be able to request full browser tab sharing (defaults to `false`).
`permissions.allow_request_mode`	`boolean`, optional	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`, optional	Whether the viewer should be able to ask the Visitor to share their full screen (defaults to `true`).
`permissions.allow_scroll`	`boolean`, optional	Whether the viewer should have access to remote scroll (defaults to `true`).
`permissions.allow_show_viewer_screen`	`boolean`, optional	Whether the viewer should be able to share their screen with the Visitor (defaults to `true`). Called `allow_show_agent_screen` before v1.4.
`permissions.allow_type`	`boolean`, optional	Whether the viewer should have access to remote type (defaults to `true`).
`permissions.allow_video`	`boolean`, optional	Whether the viewer should have access to video calls (defaults to `true`). Audio calls are not available on premise.
`permissions.hide_private_details`	`boolean`, optional	Whether the Visitor's private information (such as IP address) should be hidden from the viewer (defaults to `false`).
`permissions.keeps_session_alive`	`boolean`, optional	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 video calls and request a different sharing mode. Defaults to `["viewer"]`.
`session_properties.record`	`boolean`, optional	Whether this Session should be recorded. Defaults to `true` whenever session recording is set up on your server; set it to `false` to skip recording this Session.

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. Requests to the /v1.3/ endpoints keep working with the old names.

Response

// HTTP 200
{
    "status": "ok",
    "watch_url": "https://support.acmetech.com/cobrowsing/screen?id=jfoiajsdoif&token=osdjfoijo"
}

Field	Type	Description
`watch_url`	`string`	The Secure watch URL.

Errors

Code	Description
`400`	A required parameter is missing or invalid.
`402`	This viewer would put you over your subscription limits.
`404`	The Visitor does not exist.
`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. The Visitor's browser is asked to prepare for the Session right away, so only request a token when the viewer is about to connect.

// POST /v1.4/visitors/{visitor_id}/viewer_token
{
  "licenseToken": "token1234",
  "permissions": {},
  "viewer": {
    "id": "123",
    "name": "Joe Smith"
  }
}

Parameter	Type	Description
`{visitor_id}`	`string`	The short id of the Visitor.
`licenseToken`	`string`	The token obtained from here. Reach out to our team if this is incompatible with your flow for alternative options.

The endpoint also accepts the same viewer, permissions and session_properties parameters as the watch link endpoint above.

Response

// HTTP 200
{
    "status": "ok",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
    "endpoint": "https://support.acmetech.com/cobrowsing",
    "region": "onpremise",
    "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 (your on-premise instance).
`region`	`string`	Always `onpremise`.
`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`	A required parameter is missing or invalid.
`402`	This viewer would put you over your subscription limits.
`404`	The Visitor does not exist.
`409`	The Visitor's browser is not supported.

Preparing a Session

Use this endpoint to ask the Visitor's browser to prepare for a Session ahead of time, so the Session starts faster. This is done automatically when you generate a watch link.

POST /v1.4/visitors/{visitor_id}/session/prepare

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.

Stopping an Active Session

Use this endpoint to stop the Visitor's active Session.

DELETE /v1.4/visitors/{visitor_id}/session

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

Response

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

Field	Type	Description
`visitor`	`Visitor`	The Visitor.

Errors

Code	Description
`404`	The Visitor does not exist.

Deleting a Visitor

Use this endpoint to delete a Visitor entirely, including their pageview history and Session recordings. You can only delete Visitors who are not currently online or in a Session.

DELETE /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 in a Session.

Deleting All Visitors

Use this endpoint to delete all Visitors, along with their pageview history and Session recordings.

DELETE /v1.4/visitors

Response

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

Documentation

REST API (on premise)

On-Premise REST API Overview

Enabling the API

Authentication

The Visitor Object

Endpoints

Listing the Latest Visitors

Searching for a Visitor

Retrieving a Visitor

Generating a Link to Start Screen Sharing with a Visitor

Upgrading from v1.3?

Generating a Viewer Token to Embed Co-Browsing

Preparing a Session

Stopping an Active Session

Deleting a Visitor

Deleting All Visitors