{
  "data": [
    {
      "id": "rec_01J9ZABCDEF1",
      "call_id": "call_4Kp0Xn2s8u",
      "kind": "audio",
      "duration_seconds": 187,
      "size_bytes": 1498461,
      "transcript_status": "ready",
      "qc_status": "passed",
      "legal_hold": false,
      "sealed": true,
      "created_at": "2026-06-18T14:00:07.000Z"
    },
    {
      "id": "rec_01J9ZABCDEF2",
      "call_id": "call_3Qy1Mn5w2b",
      "kind": "video",
      "duration_seconds": 412,
      "size_bytes": 96218834,
      "transcript_status": "pending",
      "qc_status": "pending",
      "legal_hold": true,
      "sealed": false,
      "created_at": "2026-06-17T09:44:13.000Z"
    }
  ],
  "meta": { "request_id": "req_rec_list_001", "timestamp": "2026-06-18T14:09:00.000Z" }
}

{
  "data": [
    {
      "id": "rec_01J9ZABCDEF1",
      "call_id": "call_4Kp0Xn2s8u",
      "kind": "audio",
      "duration_seconds": 187,
      "size_bytes": 1498461,
      "transcript_status": "ready",
      "qc_status": "passed",
      "legal_hold": false,
      "sealed": true,
      "created_at": "2026-06-18T14:00:07.000Z"
    },
    {
      "id": "rec_01J9ZABCDEF2",
      "call_id": "call_3Qy1Mn5w2b",
      "kind": "video",
      "duration_seconds": 412,
      "size_bytes": 96218834,
      "transcript_status": "pending",
      "qc_status": "pending",
      "legal_hold": true,
      "sealed": false,
      "created_at": "2026-06-17T09:44:13.000Z"
    }
  ],
  "meta": { "request_id": "req_rec_list_001", "timestamp": "2026-06-18T14:09:00.000Z" }
}

Recordings API

These endpoints govern the compliance and sharing lifecycle of a finalized recording — together with the registry’s listing, media, and transcript operations they cover three concerns:

Registry — list a tenant’s finalized recordings, fetch the media (raw audio / video bytes or a signed playback URL), and read the transcript segments that power playback seeking and search.
Legal hold — exempt a recording from the age-based retention sweeps while litigation or an eDiscovery obligation is open.
Cryptographic integrity — seal a recording into a tamper-evident, per-tenant hash chain, verify it later, and export a portable signed provenance digest an auditor can check offline.
Share links — mint a time-limited, signed public link so a guest with no Orbit account can watch a completed video-room recording, and revoke every outstanding link at once.

Base path: /api/v1/recordings Authentication: API key (X-API-Key) or session JWT. Scopes & roles:

Legal-hold and integrity reads (GET) require the voice:read scope.
Placing/releasing a legal hold (PUT) and sealing integrity (POST .../integrity/seal) are compliance-governance actions: they require the voice:write scope and an owner or admin role, and are audit-logged.
Share endpoints operate on video-room artefacts: POST .../share and DELETE .../share require the video:write scope.

Method	Path	Purpose
`GET`	`/api/v1/recordings`	List a tenant’s finalized recordings, newest first
`GET`	`/api/v1/recordings/{id}/media`	Fetch the recording media bytes (or a signed playback URL)
`GET`	`/api/v1/recordings/{id}/transcript`	Read the persisted transcript segments
`GET`	`/api/v1/recordings/{id}/legal-hold`	Get the current legal-hold state
`PUT`	`/api/v1/recordings/{id}/legal-hold`	Place or release a legal hold
`GET`	`/api/v1/recordings/{id}/integrity`	Get the integrity seal (or `sealed: false`)
`GET`	`/api/v1/recordings/{id}/integrity/verify`	Re-hash the seal and report tamper status
`GET`	`/api/v1/recordings/{id}/integrity/export-digest`	Export a signed, portable provenance digest
`POST`	`/api/v1/recordings/{id}/integrity/seal`	Compute and persist the tamper-evident seal
`POST`	`/api/v1/recordings/{id}/share`	Mint a time-limited guest share link
`DELETE`	`/api/v1/recordings/{id}/share`	Revoke every outstanding share link

All endpoints are tenant-scoped: you only ever address recordings in your own account. {id} is the recording id, any 1–128 character string — Orbit currently mints them as rec_ followed by 32 hex characters, and legacy-look ids such as rec_abc123 are accepted as well. An unknown id returns 404 NOT_FOUND; a malformed id or body returns 400 VALIDATION_ERROR.

Using the SDKs

The recordings route has no first-class helper yet — none of the SDKs wraps /recordings — so each language reaches it through the same generic escape hatch, which keeps auth, retries, and the response envelope identical to the typed resources. The samples below run the same call as the curl further down the page.

Node.js (@devotel-orbit/node) — orbit.request<T>(method, path)
Python (orbit_sdk) — client.request(method, path, params={...})

curl https://api.orbit.devotel.io/api/v1/recordings/rec_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

interface Recording {
  id: string;
  call_id: string | null;
  room_id: string | null;
  kind: "audio" | "video";
  duration_seconds: number;
  size_bytes: number;
  transcript_status: "pending" | "ready" | "failed";
  qc_status: "pending" | "passed" | "failed";
  legal_hold: boolean;
  sealed: boolean;
  created_at: string;
  deleted_at: string | null;
}

const rec = await orbit.request<{ data: Recording }>(
  "GET",
  "/recordings/rec_abc123",
);

console.log(rec.data.id, rec.data.kind, rec.data.duration_seconds);

import requests

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
    },
)
data = resp.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123", nil)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/recordings/rec_abc123")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Raw curl in the body of this page works identically. Full SDK index at SDK quickstart.

List recordings

Returns one page of finalized recordings rows for the calling tenant, newest first — the same rows the dashboard’s recordings list renders, with the QC verdict, transcript readiness, and the legal-hold / integrity-seal flags you navigate to. Page through with ?cursor=<id of the last row> and ?limit=<N>; each page is capped at 200 rows.

curl "https://api.orbit.devotel.io/api/v1/recordings?limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

interface Recording {
  id: string;
  kind: "audio" | "video";
  duration_seconds: number;
  size_bytes: number;
  transcript_status: "pending" | "ready" | "failed";
  qc_status: "pending" | "passed" | "failed";
  legal_hold: boolean;
  sealed: boolean;
  created_at: string;
}

const page = await orbit.request<{ data: Recording[] }>(
  "GET",
  "/recordings?limit=50",
);

for (const row of page.data) {
  console.log(row.id, row.kind, row.sealed ? "sealed" : "unsealed");
}

import requests

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/recordings?limit=50",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
    },
)
data = resp.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/recordings?limit=50", nil)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings?limit=50")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings?limit=50");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

200 OK returns the page. data is an array of recordings in the shape the registry returns — use the row id to fetch the transcript, media, or the compliance surfaces below:

{
  "data": [
    {
      "id": "rec_01J9ZABCDEF1",
      "call_id": "call_4Kp0Xn2s8u",
      "kind": "audio",
      "duration_seconds": 187,
      "size_bytes": 1498461,
      "transcript_status": "ready",
      "qc_status": "passed",
      "legal_hold": false,
      "sealed": true,
      "created_at": "2026-06-18T14:00:07.000Z"
    },
    {
      "id": "rec_01J9ZABCDEF2",
      "call_id": "call_3Qy1Mn5w2b",
      "kind": "video",
      "duration_seconds": 412,
      "size_bytes": 96218834,
      "transcript_status": "pending",
      "qc_status": "pending",
      "legal_hold": true,
      "sealed": false,
      "created_at": "2026-06-17T09:44:13.000Z"
    }
  ],
  "meta": { "request_id": "req_rec_list_001", "timestamp": "2026-06-18T14:09:00.000Z" }
}

Fetch recording media

A record’s media bytes are served through a signed playback URL the registry returns, so a partner integration can stream or download MP3 (audio) / MP4 (video) with no separate GCP credential.

curl -L "https://api.orbit.devotel.io/api/v1/recordings/rec_01J9ZABCDEF1/media?action=download" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -o rec_01J9ZABCDEF1.mp3

import { Orbit } from "@devotel-orbit/node";

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

interface RecordingMedia {
  id: string;
  content_type: string;
  size_bytes: number;
  /** One-shot signed playback URL; treat as secret and never log it. */
  signed_url: string;
  /** Always returned; `duration_seconds` matches the registry row. */
  duration_seconds: number;
}

const media = await orbit.request<{ data: RecordingMedia }>(
  "GET",
  "/recordings/rec_01J9ZABCDEF1/media?action=url",
);

console.log(media.data.id, media.data.content_type, media.data.size_bytes);

import requests

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/recordings/rec_01J9ZABCDEF1/media?action=download",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
    },
)
data = resp.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/recordings/rec_01J9ZABCDEF1/media?action=download", nil)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings/rec_01J9ZABCDEF1/media?action=download")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings/rec_01J9ZABCDEF1/media?action=download");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

200 OK returns the playback URL plus the row’s content metadata. For the raw bytes themselves pass ?action=download — the response is the binary stream rather than the JSON envelope, so the escape-hatch variant above is the safer default; copy the CDR export pattern when you need the raw bytes in a typed helper.

{
  "data": {
    "id": "rec_01J9ZABCDEF1",
    "content_type": "audio/mpeg",
    "size_bytes": 1498461,
    "signed_url": "https://storage.googleapis.com/orbit-recordings-eu/...?X-Goog-Signature=…",
    "duration_seconds": 187
  },
  "meta": { "request_id": "req_rec_media_001", "timestamp": "2026-06-18T14:09:00.000Z" }
}

Get transcript segments

Returns the persisted transcript segments for one completed recording — each entry is one utterance with a start/end offset in milliseconds, a speaker label, and the verbatim text; the player uses these offsets for seek, and the search index ingests the same shape. An in-progress call returns 202 Accepted with transcript_status: "pending" until Deepgram finishes; a failed transcription returns 409 with RECORDING_TRANSCRIPT_NOT_READY.

curl https://api.orbit.devotel.io/api/v1/recordings/rec_01J9ZABCDEF1/transcript \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

export interface TranscriptSegment {
  idx: number;
  speaker: string;
  text: string;
  start_ms: number;
  end_ms: number;
  confidence: number;
}

interface Transcript {
  recording_id: string;
  status: "ready";
  segments: TranscriptSegment[];
}

const transcript = await orbit.request<{ data: Transcript }>(
  "GET",
  "/recordings/rec_01J9ZABCDEF1/transcript",
);

for (const segment of transcript.data.segments) {
  console.log(`[${segment.speaker} @${segment.start_ms}ms] ${segment.text}`);
}

import requests

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/recordings/rec_01J9ZABCDEF1/transcript",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
    },
)
data = resp.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/recordings/rec_01J9ZABCDEF1/transcript", nil)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings/rec_01J9ZABCDEF1/transcript")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings/rec_01J9ZABCDEF1/transcript");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

{
  "data": {
    "recording_id": "rec_01J9ZABCDEF1",
    "status": "ready",
    "segments": [
      {
        "idx": 0,
        "speaker": "agent",
        "text": "Thanks for calling Devotel, this is Alex. How can I help?",
        "start_ms": 0,
        "end_ms": 2134,
        "confidence": 0.98
      },
      {
        "idx": 1,
        "speaker": "caller",
        "text": "Hi, I'm checking on the order status for 1Z999AA10123456784.",
        "start_ms": 2134,
        "end_ms": 4890,
        "confidence": 0.96
      }
    ]
  },
  "meta": { "request_id": "req_rec_tr_001", "timestamp": "2026-06-18T14:09:00.000Z" }
}

Get legal-hold state

Returns the current eDiscovery legal-hold state for one recording — the legal_hold flag, the operator-supplied reason, and who/when it last changed. While a recording is held it is exempt from the age-based retention sweeps (both the storage object and the database row), so it survives litigation-preservation obligations.

curl https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/legal-hold \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

interface LegalHold {
  recording_id: string;
  legal_hold: boolean;
  reason: string | null;
  updated_by: string | null;
  updated_at: string | null;
}

const hold = await orbit.request<{ data: LegalHold }>(
  "GET",
  "/recordings/rec_abc123/legal-hold",
);

console.log(hold.data.legal_hold ? "held" : "not held", hold.data.reason);

import requests

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/legal-hold",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
    },
)
data = resp.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/legal-hold", nil)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/legal-hold")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/legal-hold");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

{
  "data": {
    "recording_id": "rec_abc123",
    "legal_hold": true,
    "reason": "Matter #4821 — preserve pending discovery",
    "updated_by": "user_9f2a",
    "updated_at": "2026-06-18T14:02:11.000Z"
  },
  "meta": { "request_id": "req_...", "timestamp": "2026-06-18T14:09:00.000Z" }
}

Place or release a legal hold

Sets the hold on or off. While held, the recording and its linked video-room session artefacts are exempt from the retention sweeps. This is a compliance-governance action — it requires an owner or admin role and is recorded in the audit log.

curl -X PUT https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/legal-hold \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "hold": true,
    "reason": "Matter #4821 — preserve pending discovery"
  }'

import { Orbit } from "@devotel-orbit/node";

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

interface LegalHold {
  recording_id: string;
  legal_hold: boolean;
  reason: string | null;
  updated_by: string | null;
  updated_at: string | null;
}

const updated = await orbit.request<{ data: LegalHold }>(
  "PUT",
  "/recordings/rec_abc123/legal-hold",
  {
    hold: true,
    reason: "Matter #4821 — preserve pending discovery",
  },
);

console.log(updated.data.legal_hold ? "hold set" : "released");

import requests

resp = requests.put(
    "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/legal-hold",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
        "Content-Type": "application/json",
    },
    json={"hold": True, "reason": "Matter #4821 — preserve pending discovery"},
)
data = resp.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]interface{}{ "hold": true, "reason": "Matter #4821 — preserve pending discovery" })
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/legal-hold", bytes.NewReader(body))
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/legal-hold")
request = Net::HTTP::Put.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"
request["Content-Type"] = "application/json"
request.body = JSON.generate({ hold: true, reason: "Matter #4821 — preserve pending discovery" })

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/legal-hold");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["hold" => true, "reason" => "Matter #4821 — preserve pending discovery"]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

Field	Type	Required	Meaning
`hold`	boolean	yes	`true` to place a hold, `false` to release it.
`reason`	string	no	Operator-supplied justification (max 512 characters).

The response echoes the resulting state, identical in shape to the GET above.

Get the integrity seal

Returns the recording’s cryptographic-integrity seal — the content hash, its link in the tenant’s recording-integrity hash chain, and the KMS/BYOK key metadata. A raw key reference is never echoed; only the provider and a key fingerprint travel. sealed is false (and seal is null) when the recording has not been sealed yet.

curl https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

interface IntegritySeal {
  recording_id: string;
  sealed: boolean;
  seal: {
    content_sha256: string;
    prev_hash: string;
    current_hash: string;
    canonicalization_version: number;
    kms_provider: string;
    kms_key_fingerprint: string;
    encryption_algorithm: string;
    sealed_by: string | null;
    sealed_at: string | null;
  } | null;
}

const seal = await orbit.request<{ data: IntegritySeal }>(
  "GET",
  "/recordings/rec_abc123/integrity",
);

console.log(seal.data.sealed ? "sealed" : "unsealed");

import requests

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
    },
)
data = resp.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity", nil)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

{
  "data": {
    "recording_id": "rec_abc123",
    "sealed": true,
    "seal": {
      "content_sha256": "3b1f...e90a",
      "prev_hash": "0000...0000",
      "current_hash": "9c4d...77b1",
      "canonicalization_version": 1,
      "kms_provider": "gcp-kms",
      "kms_key_fingerprint": "f1:a2:...:c9",
      "encryption_algorithm": "AES-256-GCM",
      "sealed_by": "user_9f2a",
      "sealed_at": "2026-06-18T14:05:00.000Z"
    }
  },
  "meta": { "request_id": "req_...", "timestamp": "2026-06-18T14:09:00.000Z" }
}

Verify the integrity seal

Re-hashes the stored seal and reports whether the recording’s bytes and key metadata are intact. valid is the verdict; reason explains a failure; current_hash and expected_hash let an integrator compare the stored versus recomputed chain link.

curl https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/verify \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

interface IntegrityVerify {
  recording_id: string;
  sealed: boolean;
  valid: boolean;
  reason: string | null;
  current_hash: string | null;
  expected_hash: string | null;
}

const verdict = await orbit.request<{ data: IntegrityVerify }>(
  "GET",
  "/recordings/rec_abc123/integrity/verify",
);

if (!verdict.data.valid) {
  console.error("tamper detected:", verdict.data.reason);
}

import requests

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/verify",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
    },
)
data = resp.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/verify", nil)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/verify")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/verify");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

{
  "data": {
    "recording_id": "rec_abc123",
    "sealed": true,
    "valid": true,
    "reason": null,
    "current_hash": "9c4d...77b1",
    "expected_hash": "9c4d...77b1"
  },
  "meta": { "request_id": "req_...", "timestamp": "2026-06-18T14:09:00.000Z" }
}

Export a signed provenance digest

Returns a portable, HMAC-signed digest a customer ships alongside an exported recording so an auditor can verify provenance offline. The recording must already be sealed — calling this on an unsealed recording returns 400 (RECORDING_INTEGRITY_NOT_SEALED).

curl https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/export-digest \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

interface ExportDigest {
  recording_id: string;
  tenant_id: string;
  seal: {
    content_sha256: string;
    prev_hash: string;
    current_hash: string;
    canonicalization_version: number;
    kms_provider: string;
    kms_key_fingerprint: string;
  };
  issued_at: string;
  issued_by: string;
  signature_hmac: string;
}

const digest = await orbit.request<{ data: ExportDigest }>(
  "GET",
  "/recordings/rec_abc123/integrity/export-digest",
);

// Ship digest alongside the exported recording; the auditor recomputes the HMAC offline.
console.log(digest.data.signature_hmac);

import requests

resp = requests.get(
    "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/export-digest",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
    },
)
data = resp.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/export-digest", nil)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/export-digest")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/export-digest");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

The response data is a self-contained digest object: the recording id, the sealed chain hashes and key metadata, the issuing operator and timestamp, and an HMAC signature an auditor recomputes to confirm the digest was issued by your tenant and has not been altered.

Seal a recording

Computes and persists the tamper-evident seal, chaining it into the tenant’s recording-integrity hash chain and stamping the tenant’s BYOK/KMS posture. This is a compliance-governance action — it requires an owner or admin role and is written into the public audit-log hash chain.

curl -X POST https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/seal \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content_sha256": "3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce90a"
  }'

import { Orbit } from "@devotel-orbit/node";

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

interface SealResult {
  recording_id: string;
  sealed: boolean;
  seal: {
    content_sha256: string;
    prev_hash: string;
    current_hash: string;
    canonicalization_version: number;
    kms_provider: string;
    kms_key_fingerprint: string;
    encryption_algorithm: string;
    sealed_by: string;
    sealed_at: string;
  };
}

const result = await orbit.request<{ data: SealResult }>(
  "POST",
  "/recordings/rec_abc123/integrity/seal",
  {
    content_sha256:
      "3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce90a",
  },
);

console.log(result.data.sealed ? "sealed" : "unsealed");

import requests

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/seal",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
        "Content-Type": "application/json",
    },
    json={"content_sha256": "3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce90a"},
)
data = resp.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]interface{}{ "content_sha256": "3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce90a" })
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/seal", bytes.NewReader(body))
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/seal")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"
request["Content-Type"] = "application/json"
request.body = JSON.generate({ "content_sha256": "3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce90a" })

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/integrity/seal");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["content_sha256" => "3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce0a3b1fce90a"]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

Field	Type	Required	Meaning
`content_sha256`	string	no	64-char hex SHA-256 of the recorded media bytes. Defaults to the egress-stamped `metadata.content_sha256`.
`encryption_algorithm`	string	no	Symmetric algorithm the bytes are encrypted under at rest (max 64 characters).

If no content hash is supplied and the egress pipeline has not stamped one yet, the call returns 400 (RECORDING_INTEGRITY_MISSING_CONTENT_HASH). On success the response carries sealed: true and the resulting seal, in the same shape as the GET .../integrity response. Mints a time-limited, signed public link for a completed video-room recording so a guest with no Orbit account can watch it. The requested lifetime is clamped server-side to between 5 minutes and 30 days; omit expires_in_seconds for the 7-day default. Only completed video-room recordings are shareable — anything else returns 400 (RECORDING_SHARE_NOT_SHAREABLE).

curl -X POST https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/share \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in_seconds": 604800
  }'

import { Orbit } from "@devotel-orbit/node";

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

interface ShareLink {
  recording_id: string;
  share_url: string;
  token: string;
  expires_at: string;
  revocable: boolean;
}

const link = await orbit.request<{ data: ShareLink }>(
  "POST",
  "/recordings/rec_abc123/share",
  { expires_in_seconds: 604800 },
);

console.log(link.data.share_url, link.data.expires_at);

import requests

resp = requests.post(
    "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/share",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
        "Content-Type": "application/json",
    },
    json={"expires_in_seconds": 604800},
)
data = resp.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]interface{}{ "expires_in_seconds": 604800 })
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/share", bytes.NewReader(body))
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/share")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"
request["Content-Type"] = "application/json"
request.body = JSON.generate({ expires_in_seconds: 604800 })

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/share");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["expires_in_seconds" => 604800]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

Field	Type	Required	Meaning
`expires_in_seconds`	integer	no	Requested link lifetime in seconds. Clamped to the [5 minutes, 30 days] range; omitted defaults to 7 days.

{
  "data": {
    "recording_id": "rec_abc123",
    "share_url": "https://api.orbit.devotel.io/api/v1/public/recordings/eyJ...",
    "token": "eyJ...",
    "expires_at": "2026-06-25T14:09:00.000Z",
    "revocable": true
  },
  "meta": { "request_id": "req_...", "timestamp": "2026-06-18T14:09:00.000Z" }
}

The grant lives entirely inside the signed token — the only persisted state is a per-recording revocation nonce. A guest opens share_url to stream the recording without authenticating. Revokes every outstanding link for the recording by rotating its share nonce. Previously-shared URLs stop resolving immediately; you can mint fresh links afterwards. The call is audit-logged.

curl -X DELETE https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/share \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

interface RevokeResult {
  recording_id: string;
  revoked: boolean;
}

const result = await orbit.request<{ data: RevokeResult }>(
  "DELETE",
  "/recordings/rec_abc123/share",
);

console.log(result.data.revoked ? "all links revoked" : "nothing to revoke");

import requests

resp = requests.delete(
    "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/share",
    headers={
        "X-API-Key": "dv_live_sk_your_key_here",
    },
)
data = resp.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/share", nil)
	req.Header.Set("X-API-Key", "dv_live_sk_your_key_here")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data map[string]any `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data)
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/share")
request = Net::HTTP::Delete.new(uri)
request["X-API-Key"] = "dv_live_sk_your_key_here"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body)["data"]

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/recordings/rec_abc123/share");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: dv_live_sk_your_key_here",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo json_encode($response["data"]) . PHP_EOL;

{
  "data": { "recording_id": "rec_abc123", "revoked": true },
  "meta": { "request_id": "req_...", "timestamp": "2026-06-18T14:10:00.000Z" }
}

API Reference

All Endpoints

Recordings API: legal holds, integrity seals, and shares

Recordings API

Using the SDKs

List recordings

Fetch recording media

Get transcript segments

Get legal-hold state

Place or release a legal hold

Get the integrity seal

Verify the integrity seal

Export a signed provenance digest

Seal a recording

See also

​Recordings API

​Using the SDKs

​List recordings

​Fetch recording media

​Get transcript segments

​Get legal-hold state

​Place or release a legal hold

​Get the integrity seal

​Verify the integrity seal

​Export a signed provenance digest

​Seal a recording

​Mint a share link

​Revoke share links

​See also

Recordings API

Using the SDKs

List recordings

Fetch recording media

Get transcript segments

Get legal-hold state

Place or release a legal hold

Get the integrity seal

Verify the integrity seal

Export a signed provenance digest

Seal a recording

Mint a share link

Revoke share links

See also