Worked samples + errors worth branching on - Devotel Orbit Documentation

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/calls?limit=25&cursor=eyJpZC...&status=completed" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "call_01J9RSF5GZWZ4TQ0AEXAMPLE",
      "recording_url": "https://storage.googleapis.com/orbit-rec…/call_01J9RS…wav?X-Signed-…",
      "duration_seconds": 142,
      "format": "wav",
      "status": "completed",
      "recording_state": "finalized"
    }
  ],
  "pagination": {
    "cursor": "eyJpZC…next",
    "has_more": true,
    "total": 41
  },
  "meta": {
    "request_id": "req_recordings",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/calls?limit=25&cursor=eyJpZC...&status=completed" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "call_01J9RSF5GZWZ4TQ0AEXAMPLE",
      "recording_url": "https://storage.googleapis.com/orbit-rec…/call_01J9RS…wav?X-Signed-…",
      "duration_seconds": 142,
      "format": "wav",
      "status": "completed",
      "recording_state": "finalized"
    }
  ],
  "pagination": {
    "cursor": "eyJpZC…next",
    "has_more": true,
    "total": 41
  },
  "meta": {
    "request_id": "req_recordings",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Errors worth branching on

These failures cover the recording playback read (GET /api/v1/voice/calls//recording), hammered by every call-detail view and player. 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 classes, including the expired-recording case. 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_recordina1",
      "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_recordina1f",
      "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": "call_id", "value": "call_0192ab", "expected": "an existing call id or the provider CallSid" }
    },
    "meta": {
      "request_id": "req_recordinb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and check the call row for recording_id with a GET first, then fetch the file endpoint 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_recordinc3",
      "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.

404 — Not found

  {
    "error": {
      "code": "RECORDING_FILE_NOT_READY",
      "message": "The recording for this call has not been attached yet.",
      "status": 404,
      "details": { "recording_status": "pending_upload", "estimated_available_in_seconds": 9 }
    },
    "meta": {
      "request_id": "req_recordind4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Retry with backoff — the uploader typically attaches within seconds of call end.

404 — Expired

  {
    "error": {
      "code": "RECORDING_EXPIRED",
      "message": "The recording was deleted by the workspace retention policy.",
      "status": 404,
      "details": { "retention_days": 30 }
    },
    "meta": {
      "request_id": "req_recordine5",
      "timestamp": "2026-09-03T12:00:03Z"
    }
  }

The not-ready 404 above says “retry with backoff.” This one says “gone” — the tenant’s retention sweep has already deleted the media. Stop retrying; the only recovery is raising the retention window before the next sweep runs, or exempting the recording with a legal hold before the window closes.

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.
`RECORDING_FILE_NOT_READY` (404 not found)	recording not attached yet	Branch on `error.code`. Retry with backoff; the uploader typically attaches within seconds of call end.
`RECORDING_EXPIRED` (404 not found)	retention sweep deleted the media	Surface. Do not retry. Raise the retention window or place a legal hold before the next sweep runs.

Worked request and response samples

Copy the request as written, substitute your own ids, and compare the response envelope — a success in the same shape the numbered error sections spell out. The samples cover the full playback path, in the order a call-detail view walks it: list → fetch → conversation scope → BYO delivery → retention posture.

1. List recordings for a call

GET /api/v1/voice/calls

Page through calls that carry recordings, filtered by the call ids you already have. Each row carries a signed, playable recording_url minted on read (never the raw gs:// object path), plus the duration, format, and expiry you can render next to the player. Request

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/calls?limit=25&cursor=eyJpZC...&status=completed" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "call_01J9RSF5GZWZ4TQ0AEXAMPLE",
      "recording_url": "https://storage.googleapis.com/orbit-rec…/call_01J9RS…wav?X-Signed-…",
      "duration_seconds": 142,
      "format": "wav",
      "status": "completed",
      "recording_state": "finalized"
    }
  ],
  "pagination": {
    "cursor": "eyJpZC…next",
    "has_more": true,
    "total": 41
  },
  "meta": {
    "request_id": "req_recordings",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Keep paging on pagination.cursor until has_more flips false. A call whose uploader is still attaching returns recording_url: null — re-poll after a few seconds rather than branching on the null.

2. Fetch the file

GET /api/v1/voice/calls/{id}/recording

Returns a signed, time-limited playback URL for one call’s recording. The binary bytes never cross your JSON envelope — the response carries a V4-signed URL straight to the storage object, so the player downloads the media directly from the CDN layer while your API request stays a few hundred bytes. The expires_at epoch-ms tells the UI when the fetch link dies (a re-GET re-mints it). Request

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/calls/call_7b3e9c2d/recording" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "url": "https://storage.googleapis.com/orbit-rec…/call_7b3e9c2d.wav?X-Signed-…",
    "duration_seconds": 142,
    "format": "wav",
    "expires_at": 1787899680000,
    "recording_id": "rec_a51e2c94",
    "chapters": []
  },
  "meta": {
    "request_id": "req_recordings",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

A call that was never recorded returns the 404 above. When chapters is non-empty it carries [{ start_ms, end_ms, title, summary }] markers the player renders as click-to-seek headings.

3. Conversation chain

GET /api/v1/recordings/conversation/{conversationId}/legal-hold

A conversation can span several recordings — every hold, transfer, agent leg, each lands its own row on the recordings table. This read returns the aggregated hold tally across every recording linked to the conversation, ordered by the same parent link the per-recording write uses, so you can see at a glance whether the chain is fully held before a retention sweep claims anything on it. Request

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

{
  "data": {
    "conversation_id": "conv_01H8ZC3NPA7VLEGAL",
    "total_recordings": 3,
    "held_recordings": 3
  },
  "meta": {
    "request_id": "req_recordings",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

held_recordings < total_recordings means at least one row in the chain survives un-protected — hold the whole chain with PUT /api/v1/recordings/conversation/{conversationId}/legal-hold instead of holding the three ids one by one.

4. Ship to BYO storage

POST /api/v1/video/rooms-scheduled (and POST /api/v1/video/rooms-scheduled/{id}/recording/start)

Video-room recordings can land in your own bucket instead of Orbit-managed storage. Pass recording_storage on room create (or on recording start) and every artifact for that room egresses to the destination you declare; the recording row’s destination then reports the non-secret descriptor so the audit trail answers “where does the file live” without ever storing the key. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quarterly compliance review",
    "recording_enabled": true,
    "recording_storage": {
      "provider": "s3",
      "bucket": "acme-room-recordings",
      "region": "eu-west-1",
      "access_key_id": "AKIA...",
      "secret_access_key": "...",
      "prefix": "rooms/2026"
    }
  }'

{
  "data": {
    "id": "vroom_01J8ZC3NPA7V",
    "recording_enabled": true,
    "recording_storage": {
      "provider": "s3",
      "bucket": "acme-room-recordings",
      "region": "eu-west-1",
      "prefix": "rooms/2026"
    }
  },
  "meta": {
    "request_id": "req_recordings",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

The credential you send needs, at minimum, s3:PutObject on the destination bucket (and s3:GetObject if your flow re-reads the artifact). Restrict the bucket’s IAM policy to the egress use and let bucket lifecycle rules own retention — Orbit delivers the artifact; expiry and versioning stay with you. The full destination contract (S3, GCS, S3-compatible endpoints, region pinning on Orbit-managed storage) is in the BYO storage guide.

5. Tenant-owned retention posture

PUT /api/v1/settings/retention

Retention on recordings is owned by you, not the platform: this is the one knob the scheduled sweep reads, and a partial update merges with what’s stored instead of resetting sibling channels. The response returns the merged override plus the resolved effective values, so you never need a follow-up GET to learn what the sweep will actually do. Request

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/retention" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "recording_days": 90,
    "video_room_days": 180
  }'

{
  "data": {
    "override": { "recording_days": 90, "video_room_days": 180 },
    "effective": { "recording_days": 90, "video_room_days": 180, "voice_days": 365 }
  },
  "meta": {
    "request_id": "req_recordings",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Owner/admin only. Once a sweep deletes media past a window, no placeholder remains waiting — the expired-404 above fires on the next read. Place the hold before the window closes, or widen the window here; the legal-hold and retention controls are the tenant-owned posture the compliance guide expects you to drive.

POST /api/v1/recordings/{id}/share

Mint a time-boxed share link; until the link expires, the same recording streams without an API key. Substitute the recording id for {id}. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/recordings/{id}/share" \
  -H "Content-Type: application/json" \
  -d '{
  "expires_in_seconds": 3600,
  "allow_download": false
}'

{
  "data": {
    "share_url": "https://share.acme.example/r-8c1f4e2a9b3d",
    "expires_at": "2026-09-08T13:00:00Z"
  },
  "meta": {
    "request_id": "req_recordings",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Per-operation success envelopes (concrete shapes)

Each block below fills what used to render as “data”: on this page — the concrete envelope the matching route returns. These blocks moved here from the generated endpoint file (which regeneration owns) so they survive every splice.

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "clips": [
      {
        "id": "clip_4e8c2b7a1d9f3e0a6b3c9d0e1f2a3b4c",
        "label": "Pricing concession",
        "start_ms": 42000,
        "end_ms": 61000,
        "created_by": "usr_3f2a1b9c4d",
        "created_at": "2026-09-11T14:22:31Z",
        "duration_ms": 19000,
        "media_fragment": "#t=42,61"
      },
      {
        "id": "clip_7b2d9a4c6f1e5b8d0a3c6f1e2d3c4b5a",
        "label": "Escalation promise",
        "start_ms": 182000,
        "end_ms": 205400,
        "created_by": "usr_3f2a1b9c4d",
        "created_at": "2026-09-11T14:23:02Z",
        "duration_ms": 23400,
        "media_fragment": "#t=182,205.4"
      }
    ],
    "total": 2
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "desktop_analytics": [
      {
        "id": "dtan_9a3f0c2e7b1d4f8a6c3e9b",
        "agent_id": "agt_2f7a9c4e1d",
        "segment_count": 137,
        "report": {
          "total_desktop_seconds": 2710,
          "talk_app_seconds": 1890,
          "non_talk_seconds": 820,
          "non_talk_ratio": 0.3026,
          "idle_seconds": 310,
          "application_count": 9,
          "switch_count": 41,
          "applications": [
            {
              "application": "crm-tickets",
              "category": "reference",
              "total_seconds": 640,
              "visit_count": 11,
              "share_of_desktop": 0.2362,
              "average_visit_seconds": 58.2,
              "automation_candidate": false
            }
          ],
          "top_transitions": [
            { "from": "crm-tickets", "to": "knowledge-base", "count": 7 }
          ],
          "automation_opportunities": [
            {
              "application": "billing-lookup",
              "category": "reference",
              "visit_count": 9,
              "total_seconds": 210,
              "estimated_reclaimable_seconds": 210,
              "reason": "Recurring lookup of the same record type per call."
            }
          ],
          "segment_count": 137,
          "window": {
            "start_at": "2026-09-11T14:04:12Z",
            "end_at": "2026-09-11T14:51:40Z"
          },
          "generated_at": "2026-09-11T15:02:11Z"
        },
        "created_by": "webhook.edge",
        "created_at": "2026-09-11T15:02:11Z",
        "updated_at": "2026-09-11T15:02:11Z"
      }
    ],
    "desktop_analytics_count": 1
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_9d8c7b6a5c4e3f2d1b0a",
    "moments": [
      {
        "id": "hl_7d2a1c9e4f8b3d06a5f2e8c1b9d40732",
        "kind": "question",
        "label": "string",
        "start_ms": 0,
        "end_ms": 0,
        "score": 0,
        "reason": "string",
        "detected_at": "1970-01-01T00:00:00.000Z",
        "duration_ms": 0,
        "media_fragment": "string"
      }
    ],
    "total": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "sealed": true,
    "seal": {
      "content_sha256": "9d0e2f8a7c1b4e6d3a5c9e0b7f2d1a6b4c8e3a0d7f5b2a9c4e6d1b3a5f7c9e2a",
      "prev_hash": "2b7c4e1a6d0f3a8c5b9e2d7a4c1f6b3e0d8a5c2e7b4f9a1d6c3e8b0a5c2e7f4a",
      "current_hash": "8c3f9a2e7b5d1c4a6f0e9b3d2c8a5e1f7b4d0a6c9e2a5f8b1d4c7a0e3f6b9c2d",
      "canonicalization_version": 1,
      "kms_provider": "google_kms",
      "kms_key_fingerprint": "projects/acme-pci/locations/eu-w1/keyRings/orbit-integrity/cryptoKeys/rec-seal/a1f9c4e8",
      "encryption_algorithm": "AES-256-GCM",
      "sealed_by": "usr_3f2a1b9c4d",
      "sealed_at": "2026-09-11T15:04:27Z"
    }
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "content_sha256": "9d0e2f8a7c1b4e6d3a5c9e0b7f2d1a6b4c8e3a0d7f5b2a9c4e6d1b3a5f7c9e2a",
    "integrity_hash": "8c3f9a2e7b5d1c4a6f0e9b3d2c8a5e1f7b4d0a6c9e2a5f8b1d4c7a0e3f6b9c2d",
    "kms_provider": "google_kms",
    "kms_key_fingerprint": "projects/acme-pci/locations/eu-w1/keyRings/orbit-integrity/cryptoKeys/rec-seal/a1f9c4e8",
    "encryption_algorithm": "AES-256-GCM",
    "sealed_at": "2026-09-11T15:04:27Z",
    "jurisdiction": "EU",
    "issued_at": "2026-09-14T08:31:00Z",
    "signature": "a1f9c4e8b2d7a3e0c5b8f1a4d6c9e2b5a8d1f4c7e0a3b6d9c2e5f8a1b4d7c0e3f6a9b2c5e8d1f4a7c0e3b6d9c2e5f8a1b4d7c0e3f6a9b2"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "sealed": true,
    "valid": true,
    "reason": "ok",
    "current_hash": "8c3f9a2e7b5d1c4a6f0e9b3d2c8a5e1f7b4d0a6c9e2a5f8b1d4c7a0e3f6b9c2d",
    "expected_hash": "8c3f9a2e7b5d1c4a6f0e9b3d2c8a5e1f7b4d0a6c9e2a5f8b1d4c7a0e3f6b9c2d"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "legal_hold": true,
    "reason": "Dispute case #48211 — preserve until resolved",
    "updated_by": "usr_3f2a1b9c4d",
    "updated_at": "2026-09-12T09:18:44Z"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "screen_recordings": [
      {
        "id": "scrn_1f4b8c2e7a9d3f0e6b5c8a",
        "gcs_path": "orbit-prod-screen/acme/card/workspace/library-assets/tut-dufaaP/video/base/2026-09-11/rec_8d1e2f3a9b.mp4",
        "started_at": "2026-09-11T14:04:12Z",
        "ended_at": "2026-09-11T14:51:40Z",
        "duration_seconds": 2848,
        "agent_id": "agt_2f7a9c4e1d",
        "consent_method": "announcement",
        "jurisdiction": "EU",
        "retention_days": 90,
        "retain_until": "2026-12-10T14:04:12Z",
        "redaction_windows": [],
        "sync_status": "synced",
        "sync_failed_count": 0,
        "coverage_ratio": 0.98,
        "sync_offset_seconds": 1.2,
        "created_by": "webhook.edge",
        "created_at": "2026-09-11T14:51:50Z",
        "updated_at": "2026-09-11T14:51:50Z"
      }
    ],
    "screen_recording_count": 1
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "note": "This export returns the caption file itself (WebVTT or SubRip), not a JSON envelope — headers set the content type to `text/vtt` (or `application/x-subrip`) and `Content-Disposition: attachment`; `X-Pseudonymized-Count` is set only when `pseudonymize=true`.",
  "example_body": "WEBVTT\n\n00:00:04.000 --> 00:00:09.000\n<v.agent>Can we confirm the [PHONE] ending in 4217?</v.agent>",
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "unique_viewers": 14,
    "concurrent_viewers": 3,
    "concurrent_window_seconds": 30
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "unique_viewers": 14,
    "total_watch_seconds": 26120,
    "avg_watch_seconds": 1865.7,
    "completed_viewers": 6,
    "completion_rate": 0.4286,
    "avg_completion_ratio": 0.66,
    "total_events": 208,
    "first_viewed_at": "2026-09-12T08:02:11Z",
    "last_viewed_at": "2026-09-14T07:41:20Z",
    "retention_curve": [
      { "upto_percent": 50, "viewers_reached": 11, "reached_ratio": 0.79 },
      { "upto_percent": 95, "viewers_reached": 6, "reached_ratio": 0.43 }
    ],
    "viewers": [
      {
        "viewer_id": "usr_3f2a1b9c4d",
        "furthest_position_seconds": 2848,
        "watched_seconds": 2848,
        "duration_seconds": 2848,
        "completion_ratio": 1,
        "completed": true,
        "event_count": 17,
        "last_event": "ended",
        "first_seen_at": "2026-09-12T08:02:11Z",
        "last_seen_at": "2026-09-12T08:49:59Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "regions": [
      {
        "id": "vred_7a2c9e0f4b1d8a3e6f0c5b",
        "start_ms": 90000,
        "end_ms": 147000,
        "bbox": { "x": 0.41, "y": 0.18, "w": 0.22, "h": 0.35 },
        "effect": "pixelate",
        "source": "face_detection",
        "label": "Customer's on-screen card number",
        "created_by": "usr_3f2a1b9c4d",
        "created_at": "2026-09-12T10:12:30Z",
        "updated_at": "2026-09-12T10:12:30Z",
        "duration_ms": 57000
      }
    ],
    "total": 1
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "clip": {
      "id": "clip_4e8c2b7a1d9f3e0a6b3c9d0e1f2a3b4c",
      "label": "Pricing concession",
      "start_ms": 42000,
      "end_ms": 61000,
      "created_by": "usr_3f2a1b9c4d",
      "created_at": "2026-09-11T14:22:31Z",
      "duration_ms": 19000,
      "media_fragment": "#t=42,61"
    }
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "desktop_analytics": {
      "id": "dtan_9a3f0c2e7b1d4f8a6c3e9b",
      "agent_id": "agt_2f7a9c4e1d",
      "segment_count": 137,
      "report": {
        "total_desktop_seconds": 2710,
        "talk_app_seconds": 1890,
        "non_talk_seconds": 820,
        "non_talk_ratio": 0.3026,
        "idle_seconds": 310,
        "application_count": 9,
        "switch_count": 41,
        "applications": [
          {
            "application": "crm-tickets",
            "category": "reference",
            "total_seconds": 640,
            "visit_count": 11,
            "share_of_desktop": 0.2362,
            "average_visit_seconds": 58.2,
            "automation_candidate": false
          }
        ],
        "top_transitions": [
          { "from": "crm-tickets", "to": "knowledge-base", "count": 7 }
        ],
        "automation_opportunities": [
          {
            "application": "billing-lookup",
            "category": "reference",
            "visit_count": 9,
            "total_seconds": 210,
            "estimated_reclaimable_seconds": 210,
            "reason": "Recurring lookup of the same record type per call."
          }
        ],
        "segment_count": 137,
        "window": {
          "start_at": "2026-09-11T14:04:12Z",
          "end_at": "2026-09-11T14:51:40Z"
        },
        "generated_at": "2026-09-11T15:02:11Z"
      },
      "created_by": "webhook.edge",
      "created_at": "2026-09-11T15:02:11Z",
      "updated_at": "2026-09-11T15:02:11Z"
    },
    "desktop_analytics_count": 1
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_9d8c7b6a5c4e3f2d1b0a",
    "moment_id": "string",
    "clip": {
      "id": "clip_3f6a81c2d4e5471a9b0c2d5e4f8c100a",
      "label": "string",
      "start_ms": 0,
      "end_ms": 0,
      "duration_ms": 0,
      "media_fragment": "string",
      "created_by": "string",
      "created_at": "1970-01-01T00:00:00.000Z"
    }
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_9d8c7b6a5c4e3f2d1b0a",
    "moments": [
      {
        "id": "hl_7d2a1c9e4f8b3d06a5f2e8c1b9d40732",
        "kind": "question",
        "label": "string",
        "start_ms": 0,
        "end_ms": 0,
        "score": 0,
        "reason": "string",
        "detected_at": "1970-01-01T00:00:00.000Z",
        "duration_ms": 0,
        "media_fragment": "string"
      }
    ],
    "total": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "sealed": true,
    "seal": {
      "content_sha256": "9d0e2f8a7c1b4e6d3a5c9e0b7f2d1a6b4c8e3a0d7f5b2a9c4e6d1b3a5f7c9e2a",
      "prev_hash": "2b7c4e1a6d0f3a8c5b9e2d7a4c1f6b3e0d8a5c2e7b4f9a1d6c3e8b0a5c2e7f4a",
      "current_hash": "8c3f9a2e7b5d1c4a6f0e9b3d2c8a5e1f7b4d0a6c9e2a5f8b1d4c7a0e3f6b9c2d",
      "canonicalization_version": 1,
      "kms_provider": "google_kms",
      "kms_key_fingerprint": "projects/acme-pci/locations/eu-w1/keyRings/orbit-integrity/cryptoKeys/rec-seal/a1f9c4e8",
      "encryption_algorithm": "AES-256-GCM",
      "sealed_by": "usr_3f2a1b9c4d",
      "sealed_at": "2026-09-11T15:04:27Z"
    }
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "sync_status": "synced",
    "sync_report": {
      "failed_count": 0,
      "coverage_ratio": 0.98
    },
    "screen_recording": {
      "id": "scrn_1f4b8c2e7a9d3f0e6b5c8a",
      "gcs_path": "orbit-prod-screen/acme/card/workspace/library-assets/tut-dufaaP/video/base/2026-09-11/rec_8d1e2f3a9b.mp4",
      "started_at": "2026-09-11T14:04:12Z",
      "ended_at": "2026-09-11T14:51:40Z",
      "duration_seconds": 2848,
      "agent_id": "agt_2f7a9c4e1d",
      "consent_method": "announcement",
      "jurisdiction": "EU",
      "retention_days": 90,
      "retain_until": "2026-12-10T14:04:12Z",
      "redaction_windows": [],
      "sync_status": "synced",
      "sync_failed_count": 0,
      "coverage_ratio": 0.98,
      "sync_offset_seconds": 1.2,
      "created_by": "webhook.edge",
      "created_at": "2026-09-11T14:51:50Z",
      "updated_at": "2026-09-11T14:51:50Z"
    },
    "screen_recording_count": 1
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "share_url": "https://orbit.devotel.io/share/rcst_9c8d3e2a1b0f",
    "token": "rcst_9c8d3e2a1b0f",
    "expires_at": "2026-09-14T14:22:31Z",
    "revocable": true
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "accepted": true,
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "unique_viewers": 14,
    "concurrent_viewers": 3,
    "concurrent_window_seconds": 30
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "regions": [
      {
        "id": "vred_7a2c9e0f4b1d8a3e6f0c5b",
        "start_ms": 90000,
        "end_ms": 147000,
        "bbox": { "x": 0.41, "y": 0.18, "w": 0.22, "h": 0.35 },
        "effect": "pixelate",
        "source": "face_detection",
        "label": "Customer's on-screen card number",
        "created_by": "usr_3f2a1b9c4d",
        "created_at": "2026-09-12T10:12:30Z",
        "updated_at": "2026-09-12T10:12:30Z",
        "duration_ms": 57000
      }
    ],
    "total": 1
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "legal_hold": true,
    "reason": "Dispute case #48211 — preserve until resolved",
    "updated_by": "usr_3f2a1b9c4d",
    "updated_at": "2026-09-12T09:18:44Z"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "2026-09-14T08:00:00Z"
  }
}

Sample

{
  "data": {
    "recording_id": "rec_9d8c7b6a5c4e3f2d1b0a",
    "moment_id": "string",
    "dismissed": false,
    "remaining": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Worked operator samples — QC score, view analytics, hold lifecycle

The sections above cover the playback and artefact chain; these three continue with the operator side: scoring a recording, the view telemetry your player feeds, and the legal-hold posture the retention sweep reads. Same envelope rules apply — { data, meta } on success, { error, meta } on failure.

7. Score a recording programmatically

POST /api/v1/recordings/{id}/qc/run (read-back: GET /api/v1/recordings/{id}/qc)

Re-runs the QC scorer synchronously against the recording’s current attributes and persists the verdict. The operation takes no request body — the recording id in the path selects the row, so there is nothing to POST beyond the headers. It is idempotent: re-running an already-passed recording returns the same verdict and emits no recording.qc_failed webhook. Requires the developer role or above and the voice:write scope; GET /{id}/qc only needs voice:read. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/recordings/rec_8d1e2f3a9b0c4e5fa2b7/qc/run" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const res = await fetch(
  `https://api.orbit.devotel.io/api/v1/recordings/${recordingId}/qc/run`,
  { method: "POST", headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const { data } = (await res.json()) as {
  data: {
    recording_id: string;
    qc_status: "passed" | "failed" | "skipped";
    qc_report: {
      failed_count: number;
      passed_count: number;
      checks: { name: string; passed: boolean; message: string | null }[];
    } | null;
  };
};

if (data.qc_status === "failed") {
  const failed = data.qc_report?.checks.filter((c) => !c.passed) ?? [];
  console.log(failed[0]?.message);
}

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "qc_status": "failed",
    "qc_report": {
      "failed_count": 1,
      "passed_count": 4,
      "checks": [
        { "name": "duration_within_bounds", "passed": true, "message": null },
        { "name": "audio_levels", "passed": true, "message": null },
        { "name": "stereo_channels", "passed": true, "message": null },
        { "name": "container_codec", "passed": true, "message": null },
        {
          "name": "audible_coverage",
          "passed": false,
          "message": "Customer channel audible for 61% of the call (minimum 90%)."
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_qcrun1",
    "timestamp": "2026-09-14T09:12:04Z"
  }
}

Branch on qc_status, not on the HTTP status — the run returns 200 whether the verdict is passed or failed; the status-code branches are 404 for an unknown id and 400 for a malformed one. GET /{id}/qc returns the same envelope plus classification (null until scored) and reports qc_status: "pending" for a row that has never been scored, so a dashboard can render “QC not yet run” without treating it as a miss.

8. Views and view analytics

POST /api/v1/recordings/{id}/views · GET /api/v1/recordings/{id}/views/report · POST /api/v1/recordings/{id}/desktop-analytics

Your playback widget reports each viewer’s playback events; the API rolls them into a live viewership monitor and an engagement report with the drop-off curve. viewer_id is an opaque session id your player mints — never an email address or user id — so the telemetry carries no personal data. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/recordings/rec_8d1e2f3a9b0c4e5fa2b7/views" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "viewer_id": "view_9f2e7d1c4b8a",
    "event_type": "progress",
    "position_seconds": 1240,
    "duration_seconds": 2848,
    "watched_delta_seconds": 30
  }'

Node.js

await fetch(
  `https://api.orbit.devotel.io/api/v1/recordings/${recordingId}/views`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      viewer_id: viewerSessionId,
      event_type: "progress", // play | pause | seek | progress | ended
      position_seconds: player.currentTime,
      duration_seconds: player.duration,
      watched_delta_seconds: secondsSinceLastEvent,
    }),
  },
);

{
  "data": {
    "accepted": true,
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "unique_viewers": 14,
    "concurrent_viewers": 3,
    "concurrent_window_seconds": 30
  },
  "meta": {
    "request_id": "req_views1",
    "timestamp": "2026-09-14T09:41:12Z"
  }
}

The 200 doubles as the player’s “watching now” badge — no second read needed. Event ingest is best-effort: a backing-store outage returns 503 SERVICE_UNAVAILABLE, never 500; do not block the player on a retry or treat the 503 as a playback failure. The rollup read is GET /{id}/views/report — the watch-rate figures plus the audience-retention curve (how many viewers reached each percentile of the recording: your drop-off chart) and a bounded per-viewer breakdown:

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "unique_viewers": 14,
    "total_watch_seconds": 26120,
    "avg_watch_seconds": 1865.7,
    "completed_viewers": 6,
    "completion_rate": 0.4286,
    "avg_completion_ratio": 0.66,
    "total_events": 208,
    "first_viewed_at": "2026-09-12T08:02:11Z",
    "last_viewed_at": "2026-09-14T07:41:20Z",
    "retention_curve": [
      { "upto_percent": 25, "viewers_reached": 12, "reached_ratio": 0.86 },
      { "upto_percent": 50, "viewers_reached": 11, "reached_ratio": 0.79 },
      { "upto_percent": 75, "viewers_reached": 8, "reached_ratio": 0.57 },
      { "upto_percent": 95, "viewers_reached": 6, "reached_ratio": 0.43 }
    ],
    "viewers": [
      {
        "viewer_id": "view_9f2e7d1c4b8a",
        "furthest_position_seconds": 2848,
        "watched_seconds": 2848,
        "duration_seconds": 2848,
        "completion_ratio": 1,
        "completed": true,
        "event_count": 17,
        "last_event": "ended",
        "first_seen_at": "2026-09-12T08:02:11Z",
        "last_seen_at": "2026-09-12T08:49:59Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_views2",
    "timestamp": "2026-09-14T09:44:00Z"
  }
}

The agent-side counterpart is POST /{id}/desktop-analytics: your desktop agent uploads the raw application-usage segments it captured during the call, and the API derives the report server-side (time-in-application, non-talk split, swivel-chair transitions, automation opportunities). The body carries agent_id plus a segments array; every other field in the response is derived:

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/recordings/rec_8d1e2f3a9b0c4e5fa2b7/desktop-analytics" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_2f7a9c4e1d",
    "segments": [
      {
        "application": "crm-tickets",
        "started_at": "2026-09-11T14:04:12Z",
        "ended_at": "2026-09-11T14:14:52Z",
        "category": "reference",
        "window_title": "Ticket #48211"
      },
      {
        "application": "billing-lookup",
        "started_at": "2026-09-11T14:14:52Z",
        "ended_at": "2026-09-11T14:18:22Z"
      }
    ]
  }'

Node.js

await fetch(
  `https://api.orbit.devotel.io/api/v1/recordings/${recordingId}/desktop-analytics`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: agentId,
      segments: capturedSegments.map((s) => ({
        application: s.appName,
        started_at: s.start.toISOString(),
        ended_at: s.end.toISOString(),
        window_title: s.windowTitle, // optional
      })),
    }),
  },
);

The 200 returns { recording_id, desktop_analytics, desktop_analytics_count } where desktop_analytics is the persisted record shown in full in the per-operation sample above (derived report with applications, top_transitions, automation_opportunities, window). A recording already at the per-recording record limit answers 400 DESKTOP_ANALYTICS_LIMIT_REACHED — that branch means drop or replace your oldest record, not retry.

9. Legal hold lifecycle

PUT /api/v1/recordings/{id}/legal-hold

Placing a hold exempts the recording from the age-based retention sweep (media object and DB row), so it survives past the window the expired-404 above describes. The hold persists until you release it — there is no expiry field and no separate DELETE operation on this surface; releasing is the same PUT with hold: false. Owner/admin role only. Request

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/recordings/rec_8d1e2f3a9b0c4e5fa2b7/legal-hold" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "hold": true,
    "reason": "Dispute case #48211 — preserve until resolved"
  }'

Node.js

await fetch(
  `https://api.orbit.devotel.io/api/v1/recordings/${recordingId}/legal-hold`,
  {
    method: "PUT",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      hold: true,
      reason: "Dispute case #48211 — preserve until resolved",
    }),
  },
);

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "legal_hold": true,
    "reason": "Dispute case #48211 — preserve until resolved",
    "updated_by": "usr_3f2a1b9c4d",
    "updated_at": "2026-09-12T09:18:44Z"
  },
  "meta": {
    "request_id": "req_hold1",
    "timestamp": "2026-09-12T09:18:44Z"
  }
}

Recording under hold — the branch to code

The hold is a sweep exemption, not a write gate: while legal_hold is true, redaction-region writes and share revocation still succeed at the HTTP layer. The branch a compliance integration must code is therefore client-side — gate any destructive call on a GET /{id}/legal-hold read, and treat legal_hold: true as “do not touch until released.” If media under a seal does change, the integrity verify flips to valid: false with mismatched hashes:

{
  "data": {
    "recording_id": "rec_8d1e2f3a9b0c4e5fa2b7",
    "sealed": true,
    "valid": false,
    "reason": "content_changed",
    "current_hash": "7e1d4b9a2c6f0e3d8a5c1b7f4e2d9a6c3b8e0f5d2a7c4e1b6f9d3a0c5e8b2f7d",
    "expected_hash": "8c3f9a2e7b5d1c4a6f0e9b3d2c8a5e1f7b4d0a6c9e2a5f8b1d4c7a0e3f6b9c2d"
  },
  "meta": {
    "request_id": "req_hold2",
    "timestamp": "2026-09-14T10:02:51Z"
  }
}

Release with hold: false and the next sweep pass may reclaim the row once it is past the window — the expired-404 above resumes applying from that point. Place holds before the window closes, not after the sweep has run.

Worked sequence: use a recording id end-to-end

The blocks above document each operation on its own; this sequence runs one recording, rec_01J8ZC3NPA, through the post-call pipeline in the order a regulated operation usually runs it, matching the post-call pipeline guide. Every response below uses the same { data, meta } envelope as the rest of this page. For the registry reads (list, media, transcript segments) pair this sequence with the /api-reference/recordings surface; once share links go out, pair it with recording view analytics.

1. Confirm the recording exists

GET /api/v1/recordings/{id}

Fetch the row before anything else. status: ready means finalize completed and the media is addressable; while the uploader is still attaching, the fetch returns the RECORDING_FILE_NOT_READY 404 from Errors worth branching on, so retry with backoff instead of treating it as a missing call. Response

{
  "data": {
    "id": "rec_01J8ZC3NPA",
    "conversation_id": "conv_04H9T2",
    "status": "ready",
    "duration_ms": 187000,
    "container": "mp3",
    "size_bytes": 1498461,
    "content_url_expires_at": "2026-08-29T15:00:00Z"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-29T14:00:00.000Z"
  }
}

content_url_expires_at is when the signed playback URL lapses; request the row again to mint a fresh one rather than caching it.

2. QC verdict

GET /api/v1/recordings/{id}/qc

Read the verdict the post-call pipeline persisted at finalize. A failed check names the defect in checks[].message; failed_count / passed_count summarize the run. Response

{
  "data": {
    "recording_id": "rec_01J8ZC3NPA",
    "qc_status": "failed",
    "qc_report": {
      "failed_count": 1,
      "passed_count": 4,
      "checks": [
        { "name": "duration_drift", "passed": false, "message": "recorded duration is 38% shorter than the call" },
        { "name": "file_size", "passed": true, "message": null },
        { "name": "finalize_latency", "passed": true, "message": null }
      ]
    },
    "classification": null
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-29T14:02:11.000Z"
  }
}

POST /api/v1/recordings/{id}/qc/run

Re-run QC synchronously after re-processing the media. The call persists the new verdict and returns it; a failure also fans out the recording.qc_failed webhook, while a pass on an already-passed recording returns the same verdict and emits nothing, which makes the re-run safe to retry. Response

{
  "data": {
    "recording_id": "rec_01J8ZC3NPA",
    "qc_status": "failed",
    "qc_report": {
      "failed_count": 1,
      "passed_count": 4,
      "checks": [
        { "name": "duration_drift", "passed": false, "message": "recorded duration is 38% shorter than the call" },
        { "name": "file_size", "passed": true, "message": null }
      ]
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-29T14:05:37.000Z"
  }
}

3. Legal hold + integrity

PUT /api/v1/recordings/{id}/legal-hold

Place the hold before exporting anything: it exempts the media object and the row from age-based retention sweeps. Send "hold": false to release; reason is optional and capped at 512 characters. Request

curl -X PUT "https://api.orbit.devotel.io/api/v1/recordings/rec_01J8ZC3NPA/legal-hold" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "hold": true,
  "reason": "Matter 2026-118 — customer dispute"
}'

Response

{
  "data": {
    "recording_id": "rec_01J8ZC3NPA",
    "legal_hold": true,
    "reason": "Matter 2026-118 — customer dispute",
    "updated_by": "user_2Wq8",
    "updated_at": "2026-08-29T14:10:55.000Z"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-29T14:10:55.000Z"
  }
}

POST /api/v1/recordings/{id}/integrity/seal

Seal the held recording to anchor its content into the tenant hash chain. The response returns the seal hash triplet plus digest_url, the signed provenance bundle to ship alongside any exported media; GET /api/v1/recordings/{id}/integrity/export-digest downloads it, and GET /api/v1/recordings/{id}/integrity/verify re-hashes the seal on demand. Response

{
  "data": {
    "recording_id": "rec_01J8ZC3NPA",
    "sealed": true,
    "seal": {
      "content_sha256": "0abc…f9",
      "prev_hash": "71fe…",
      "current_hash": "9d2c…",
      "canonicalization_version": 1,
      "kms_provider": "aws-kms",
      "encryption_algorithm": "AES-256-GCM",
      "sealed_by": "user_2Wq8",
      "sealed_at": "2026-08-29T14:20:01.000Z"
    },
    "digest_url": "https://api.orbit.devotel.io/api/v1/recordings/rec_01J8ZC3NPA/integrity/export-digest"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-29T14:20:01.000Z"
  }
}

Sealing before finalize returns RECORDING_INTEGRITY_MISSING_CONTENT_HASH; wait for finalize or pass content_sha256 (64-char hex) in the request body.

4. Caption export and clips

GET /api/v1/recordings/{id}/transcript/export?format=vtt&pseudonymize=true

The export streams the caption file itself, not a JSON envelope. With pseudonymize=true, email, phone, and long-ID tokens are replaced by [EMAIL], [PHONE], and [ID] before rendering, and X-Pseudonymized-Count reports what was scrubbed; raw output never sets the header. Request

curl -i "https://api.orbit.devotel.io/api/v1/recordings/rec_01J8ZC3NPA/transcript/export?format=vtt&pseudonymize=true" \
  -H "X-API-Key: dv_live_sk_your_key_here" -o transcript-redacted.vtt

Response

HTTP/2 200
Content-Type: text/vtt; charset=utf-8
Content-Disposition: attachment; filename="transcript-pseudonymized-rec_01J8ZC3NPA.vtt"
X-Pseudonymized-Count: email=2;phone=1

WEBVTT

00:00:02.160 --> 00:00:06.400
<v Agent> Thanks for calling, this call is recorded. Could I get the number on your account?</v>

00:00:06.640 --> 00:00:09.880
<v Caller> Sure, it is [ID], and the email on file is [EMAIL].</v>

POST /api/v1/recordings/{id}/clips

Cut a named clip by range; the 201 response returns the clip with a media_fragment your player appends to the recording URL to seek straight to the window. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/recordings/rec_01J8ZC3NPA/clips" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Disclosure language",
  "start_ms": 61200,
  "end_ms": 74400
}'

Response

{
  "data": {
    "recording_id": "rec_01J8ZC3NPA",
    "clip": {
      "id": "clip_3f6a81c2d4e5471a9b0c2d5e4f8c100a",
      "label": "Disclosure language",
      "start_ms": 61200,
      "end_ms": 74400,
      "duration_ms": 13200,
      "media_fragment": "#t=61.2,74.4",
      "created_by": "user_2Wq8",
      "created_at": "2026-08-29T14:26:03.000Z"
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-29T14:26:03.000Z"
  }
}

POST /api/v1/recordings/{id}/highlights/detect

Detection scans the transcript and returns the proposal set in the same call; re-running replaces the prior set. Review the persisted proposals afterwards with GET /api/v1/recordings/{id}/highlights (the poll URL for later review), promote with POST /api/v1/recordings/{id}/highlights/{momentId}/clip, and drop noise with DELETE /api/v1/recordings/{id}/highlights/{momentId}. Response

{
  "data": {
    "recording_id": "rec_01J8ZC3NPA",
    "moments": [
      {
        "id": "hl_7d2a1c9e4f8b3d06a5f2e8c1b9d40732",
        "kind": "question",
        "label": "Pricing question",
        "start_ms": 61200,
        "end_ms": 74400,
        "score": 0.87,
        "reason": "caller asks about plan pricing after the disclosure",
        "detected_at": "2026-08-29T14:27:19.000Z",
        "duration_ms": 13200,
        "media_fragment": "#t=61.2,74.4"
      }
    ],
    "total": 1
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-29T14:27:19.000Z"
  }
}

Detection needs a completed transcript; without one it returns RECORDING_HIGHLIGHT_NOT_TRANSCRIBED.

POST /api/v1/recordings/{id}/share

Mint a time-limited public link for an external auditor or counsel. Lifetimes clamp between 5 minutes and 30 days; omit expires_in_seconds for the 7-day default. The examples below request 72 hours. Request

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

Response

{
  "data": {
    "recording_id": "rec_01J8ZC3NPA",
    "share_url": "https://orbit.devotel.io/share/eyJyb2NrcyI6InJlY18wMUo4WkMzTlBBIn0.Zm9vYmFyMTIz",
    "token": "eyJyb2NrcyI6InJlY18wMUo4WkMzTlBBIn0.Zm9vYmFyMTIz",
    "expires_at": "2026-09-01T14:30:00.000Z",
    "revocable": true
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-29T14:30:00.000Z"
  }
}

DELETE /api/v1/recordings/{id}/share

Revoke every outstanding link in one write; prior links fail immediately and new links can be minted afterwards. Public playback of a live link still registers in view analytics, so you can confirm the auditor watched before closing the matter. Response

{
  "data": {
    "ok": true
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-29T14:35:12.000Z"
  }
}

​Errors worth branching on

​401 — Unauthorized

​403 — Forbidden

​422 — Schema

​429 — Rate

​404 — Not found

​404 — Expired

​60-second retry matrix

​Worked request and response samples

​1. List recordings for a call

​2. Fetch the file

​3. Conversation chain

​4. Ship to BYO storage

​5. Tenant-owned retention posture

​6. Share a recording

​Per-operation success envelopes (concrete shapes)

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Sample

​Worked operator samples — QC score, view analytics, hold lifecycle

​7. Score a recording programmatically

​8. Views and view analytics

​9. Legal hold lifecycle

​Recording under hold — the branch to code

​Worked sequence: use a recording id end-to-end

​1. Confirm the recording exists

​2. QC verdict

​3. Legal hold + integrity

​4. Caption export and clips

​5. Public share links

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

404 — Not found

404 — Expired

60-second retry matrix

Worked request and response samples

1. List recordings for a call

2. Fetch the file

3. Conversation chain

4. Ship to BYO storage

5. Tenant-owned retention posture

6. Share a recording

Per-operation success envelopes (concrete shapes)

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Sample

Worked operator samples — QC score, view analytics, hold lifecycle

7. Score a recording programmatically

8. Views and view analytics

9. Legal hold lifecycle

Recording under hold — the branch to code

Worked sequence: use a recording id end-to-end

1. Confirm the recording exists

2. QC verdict

3. Legal hold + integrity

4. Caption export and clips

5. Public share links