Cobrowse API

Cobrowse endpoints exposed by the Devotel CPaaS API Base path: /api/v1/cobrowse Endpoint count: 6

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

These five failures cover the session attach (POST /api/v1/cobrowse/sessions//host), on every operator join. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same five classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_cobrowsea1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_cobrowsea1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "visitor_context", "value": "foo", "expected": "a JSON object (for example, { page: url })" }
    },
    "meta": {
      "request_id": "req_cobrowseb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with a JSON object for visitor_context instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_cobrowsec3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

409 — Conflict

  {
    "error": {
      "code": "COBROWSE_SESSION_ALREADY_HOSTED",
      "message": "A host is already attached to this cobrowse session.",
      "status": 409,
      "details": { "host_agent_id": "agent_0192" }
    },
    "meta": {
      "request_id": "req_cobrowsed4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Reconnect the WebSocket instead of re-creating — the session is still live.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`COBROWSE_SESSION_ALREADY_HOSTED` (409 conflict)	Reconnect the WebSocket instead of re-creating	Branch on `error.code`. The session is still live.

SDK surface bridge — End a co-browse session, accept the pending join request, or join for real with the operator’s live key.

These three tabs mirror SDK status and coverage. Python fronts client.request, Go fronts client.Request, and TS fronts fetch-TS — each with the live key.

End the co-browse session

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "scope": "end"
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias", json={
  "scope": "end"
}, headers={ "X-API-Key": os.environ["ORBIT_API_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias", bytes.NewBuffer([]byte(`{
  "scope": "end"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Accept the pending join request

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/requests', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "accept": true
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/requests", json={
  "accept": true
}, headers={ "X-API-Key": os.environ["ORBIT_API_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/requests", bytes.NewBuffer([]byte(`{
  "accept": true
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Alias-wait the join queue

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias/requests', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "position": "front"
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias/requests", json={
  "position": "front"
}, headers={ "X-API-Key": os.environ["ORBIT_API_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/cobrowse/sessions/cb_demo/alias/requests", bytes.NewBuffer([]byte(`{
  "position": "front"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Get the co-browse session for a conversation

GET /api/v1/cobrowse/{conversationId}

Returns the current co-browse session stamped on the conversation (metadata.cobrowse), or null when no session has been initiated. The inbox detail panel polls this to render the ‘Co-browse available / live’ CTA and the agent join affordance.

string

required

—

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "session": {
      "session_id": "cbs_6f1a9b2c3d4e5f6a7b8c9d0e1f",
      "status": "active",
      "room_name": "cobrowse:org_9b2c4d6e1f3a5b7c9d0e2f4a:conv_a1b2c3d4e5f601:cbs_6f1a9b2c3d4e5f6a7b8c9d0e1f",
      "visitor_id": "vis_5b2c4e6f8a1b3c5d7e9f0a1b3c",
      "control": false,
      "requested_at": "2026-08-26T11:59:12.000Z",
      "started_at": "2026-08-26T11:59:45.000Z",
      "ended_at": null,
      "ended_by": null,
      "agent_user_id": "user_2x9v8wJ7kD3qR5mN1pA0"
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Get the co-browse capture-time privacy policy

GET /api/v1/cobrowse/privacy

Returns the tenant’s capture-side masking policy (mask_all_inputs, allowlist_selectors, block_selectors, blocked_input_types, unmask_on_visitor_click) that the co-browse capture client uses to redact PII in the visitor’s browser before publishing a DOM packet, and that the server uses to guard the agent control channel. Returns the default-deny policy when none has been configured.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/cobrowse/privacy" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/privacy', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/cobrowse/privacy", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/cobrowse/privacy", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/cobrowse/privacy')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/cobrowse/privacy');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "enabled": false,
    "mask_fields": [
      "text",
      "input",
      "email",
      "password"
    ],
    "allow_domains": []
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Send a guided-control packet (highlight / scroll / form-fill)

POST /api/v1/cobrowse/{conversationId}/control

Broadcasts an agent-initiated control packet into the co-browse data room, after validating the target selector (and, for form-fill, the input type) against the tenant’s cobrowse_privacy policy. A packet targeting a blocked selector, an always-blocked region, or a password-type input is rejected with 403 and audit-logged — this hard floor cannot be relaxed by tenant config. Requires the visitor to have granted control on this session.

string

required

—

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

string (enum: highlight|scroll|form_fill)

required

What the visitor’s browser renders. Only form_fill writes a value into the page.

string

required

CSS selector of the DOM node the packet targets. Refused with COBROWSE_CONTROL_BLOCKED when it falls inside a privacy-blocked region.

string

Type of the targeted input (form_fill only), so the password hard floor is enforced even when the selector carries no attribute hint.

string

Text to write into the visitor’s field. Sent for form_fill only; ignored for highlight and scroll.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/control" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "highlight",
  "selector": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/control', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "action": "highlight",
  "selector": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/control", headers=headers, json={
  "action": "highlight",
  "selector": "string"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/control", bytes.NewBuffer([]byte(`{
  "action": "highlight",
  "selector": "string"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/control')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "action": "highlight",
  "selector": "string"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/control');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "action": "highlight",
  "selector": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "session_id": "cbs_6f1a9b2c3d4e5f6a7b8c9d0e1f",
    "control": true
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

End a co-browse session

POST /api/v1/cobrowse/{conversationId}/end

Terminates the co-browse session from the operator side (status=‘ended’, stamps ended_at + ended_by=‘agent’). Idempotent on an already-ended session. The visitor can independently end from the widget; either side ending stops the data room.

string

required

—

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/end" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/end', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/end", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/end", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/end')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/end');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "session_id": "cbs_6f1a9b2c3d4e5f6a7b8c9d0e1f",
    "status": "ended",
    "ended_by": "agent",
    "ended_at": "2026-08-26T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Join a live co-browse session

POST /api/v1/cobrowse/{conversationId}/join

Mints an orbit-media data-channel join token for the operator so they can view (and, when the visitor granted control, guide) the customer’s live browser session. The effective control grant is the AND of the agent’s requested control and the visitor’s stored consent — an observe-only session can never be escalated to guided control. Flips the session to ‘active’ and stamps the agent + start time. 404 when no joinable session exists (the visitor must initiate from the widget first). 503 when the media plane is not configured.

string

required

—

string

string (enum: true|false)

boolean

Request guided control (highlight / scroll / form-fill). Effective only when the visitor consented; otherwise the agent joins observe-only.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/join" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/join', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/join", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/join", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/join')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/cobrowse/conv_8b2c4d6e1f/join');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "session_id": "cbs_6f1a9b2c3d4e5f6a7b8c9d0e1f",
    "room_name": "cobrowse:org_9b2c4d6e1f3a5b7c9d0e2f4a:conv_a1b2c3d4e5f601:cbs_6f1a9b2c3d4e5f6a7b8c9d0e1f",
    "token": "orbitmedia.cobrowse.join.jwt_sample",
    "ttl_seconds": 1800
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Update the co-browse capture-time privacy policy

PUT /api/v1/cobrowse/privacy

Upserts the tenant’s capture-side masking + control-channel guard policy. Inputs default-deny (mask_all_inputs defaults true; tel/email/cc blocked by default); selectors round-trip verbatim. password-type inputs and the built-in always-blocked selectors remain blocked regardless of this policy (hard floor). The change reaches new co-browse sessions via the next session-start bootstrap for both visitor and agent.

string

string (enum: true|false)

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/cobrowse/privacy" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/cobrowse/privacy', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.put("https://api.orbit.devotel.io/api/v1/cobrowse/privacy", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/cobrowse/privacy", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/cobrowse/privacy')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/cobrowse/privacy');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "enabled": true,
    "mask_fields": [
      "text",
      "input",
      "email",
      "password"
    ],
    "allow_domains": [
      "portal.example.com"
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

API Reference

All Endpoints

Cobrowse API

Cobrowse API

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

409 — Conflict

60-second retry matrix

SDK surface bridge — End a co-browse session, accept the pending join request, or join for real with the operator’s live key.

End the co-browse session

Accept the pending join request

Alias-wait the join queue

Get the co-browse session for a conversation

Get the co-browse capture-time privacy policy

Send a guided-control packet (highlight / scroll / form-fill)

End a co-browse session

Join a live co-browse session

Update the co-browse capture-time privacy policy

​Cobrowse API

​title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

​Errors worth branching on

​401 — Unauthorized

​403 — Forbidden

​422 — Schema

​429 — Rate

​409 — Conflict

​60-second retry matrix

​SDK surface bridge — End a co-browse session, accept the pending join request, or join for real with the operator’s live key.

​End the co-browse session

​Accept the pending join request

​Alias-wait the join queue

​Get the co-browse session for a conversation

​Get the co-browse capture-time privacy policy

​Send a guided-control packet (highlight / scroll / form-fill)

​End a co-browse session

​Join a live co-browse session

​Update the co-browse capture-time privacy policy

Cobrowse API

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

409 — Conflict

60-second retry matrix

SDK surface bridge — End a co-browse session, accept the pending join request, or join for real with the operator’s live key.

End the co-browse session

Accept the pending join request

Alias-wait the join queue

Get the co-browse session for a conversation

Get the co-browse capture-time privacy policy

Send a guided-control packet (highlight / scroll / form-fill)

End a co-browse session

Join a live co-browse session

Update the co-browse capture-time privacy policy