Finalize Streaming Recording

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123xyz/finalize \
  -H "Authorization: Bearer dtok_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "total_chunks": 12,
    "final_duration_ms": 3595420,
    "checksum_md5": "5d41402abc4b2a76b9719d911017c592"
  }'

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123xyz/finalize \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "total_chunks": 12,
    "final_duration_ms": 3595420
  }'

const result = await bota.recordings.finalizeStreaming('rec_abc123xyz', {
  total_chunks: 12,
  final_duration_ms: 3595420,
  checksum_md5: '5d41402abc4b2a76b9719d911017c592'
});

console.log(result.status); // "uploaded"
console.log(result.transcription_status); // "queued"

result = bota.recordings.finalize_streaming('rec_abc123xyz', {
  'total_chunks': 12,
  'final_duration_ms': 3595420,
  'checksum_md5': '5d41402abc4b2a76b9719d911017c592'
})

print(result['status'])  # "uploaded"
print(result['transcription_status'])  # "queued"

{
  "id": "rec_abc123xyz",
  "status": "uploaded",
  "transcription_status": "queued",
  "chunks_received": 12,
  "stitching_job_id": "job_stitcher_abc123"
}

{
  "error": {
    "type": "recording_not_found",
    "message": "Streaming recording not found"
  }
}

{
  "error": {
    "type": "invalid_operation",
    "message": "Recording was not created with streaming enabled"
  }
}

{
  "error": {
    "type": "chunk_mismatch",
    "message": "Expected 12 chunks, but only 10 were uploaded",
    "details": {
      "expected_chunks": 12,
      "received_chunks": 10,
      "missing_chunks": [7, 11]
    }
  }
}

{
  "error": {
    "type": "already_finalized",
    "message": "Recording has already been finalized"
  }
}

POST

recordings

{id}

finalize

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123xyz/finalize \
  -H "Authorization: Bearer dtok_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "total_chunks": 12,
    "final_duration_ms": 3595420,
    "checksum_md5": "5d41402abc4b2a76b9719d911017c592"
  }'

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123xyz/finalize \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "total_chunks": 12,
    "final_duration_ms": 3595420
  }'

const result = await bota.recordings.finalizeStreaming('rec_abc123xyz', {
  total_chunks: 12,
  final_duration_ms: 3595420,
  checksum_md5: '5d41402abc4b2a76b9719d911017c592'
});

console.log(result.status); // "uploaded"
console.log(result.transcription_status); // "queued"

result = bota.recordings.finalize_streaming('rec_abc123xyz', {
  'total_chunks': 12,
  'final_duration_ms': 3595420,
  'checksum_md5': '5d41402abc4b2a76b9719d911017c592'
})

print(result['status'])  # "uploaded"
print(result['transcription_status'])  # "queued"

{
  "id": "rec_abc123xyz",
  "status": "uploaded",
  "transcription_status": "queued",
  "chunks_received": 12,
  "stitching_job_id": "job_stitcher_abc123"
}

{
  "error": {
    "type": "recording_not_found",
    "message": "Streaming recording not found"
  }
}

{
  "error": {
    "type": "invalid_operation",
    "message": "Recording was not created with streaming enabled"
  }
}

{
  "error": {
    "type": "chunk_mismatch",
    "message": "Expected 12 chunks, but only 10 were uploaded",
    "details": {
      "expected_chunks": 12,
      "received_chunks": 10,
      "missing_chunks": [7, 11]
    }
  }
}

{
  "error": {
    "type": "already_finalized",
    "message": "Recording has already been finalized"
  }
}

Finalizes a streaming recording after all chunks have been uploaded. This endpoint marks the recording as complete, queues a background job to stitch audio chunks into a single file, and triggers transcription once stitching is complete.

Authentication

Requires a valid device token or API key with recordings:write scope.

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123xyz/finalize \
  -H "Authorization: Bearer dtok_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "total_chunks": 12,
    "final_duration_ms": 3595420,
    "checksum_md5": "5d41402abc4b2a76b9719d911017c592"
  }'

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123xyz/finalize \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "total_chunks": 12,
    "final_duration_ms": 3595420
  }'

const result = await bota.recordings.finalizeStreaming('rec_abc123xyz', {
  total_chunks: 12,
  final_duration_ms: 3595420,
  checksum_md5: '5d41402abc4b2a76b9719d911017c592'
});

console.log(result.status); // "uploaded"
console.log(result.transcription_status); // "queued"

result = bota.recordings.finalize_streaming('rec_abc123xyz', {
  'total_chunks': 12,
  'final_duration_ms': 3595420,
  'checksum_md5': '5d41402abc4b2a76b9719d911017c592'
})

print(result['status'])  # "uploaded"
print(result['transcription_status'])  # "queued"

Path Parameters

string

required

Recording ID from the initial streaming recording creation (e.g., rec_abc123xyz)

Request Body

total_chunks

integer

required

Total number of chunks uploaded (must match actual chunk count)

final_duration_ms

integer

required

Actual recording duration in milliseconds

checksum_md5

string

MD5 checksum of the complete audio (optional, for integrity verification)

content_sha256

string

SHA-256 of the complete audio bytes as a 64-character lowercase hex string (optional). When supplied, the server recomputes the SHA-256 of the assembled object after chunk stitching and marks the recording status=integrity_failure on mismatch.

trailer_base64

string

Optional base64-encoded bytes to append to the assembled audio after all chunks. Use this if your encoder writes bytes at close that were not captured in the chunk stream — for example, the final-page flush and EOS page that OGG/Opus encoders emit during fclose(). Without this, those bytes are absent from the assembled S3 object and content_sha256 verification will fail even though the audio was transmitted correctly. Max 16384 base64 characters (≈12KB raw).

Response

Returns the finalized recording status.

{
  "id": "rec_abc123xyz",
  "status": "uploaded",
  "transcription_status": "queued",
  "chunks_received": 12,
  "stitching_job_id": "job_stitcher_abc123"
}

{
  "error": {
    "type": "recording_not_found",
    "message": "Streaming recording not found"
  }
}

{
  "error": {
    "type": "invalid_operation",
    "message": "Recording was not created with streaming enabled"
  }
}

{
  "error": {
    "type": "chunk_mismatch",
    "message": "Expected 12 chunks, but only 10 were uploaded",
    "details": {
      "expected_chunks": 12,
      "received_chunks": 10,
      "missing_chunks": [7, 11]
    }
  }
}

{
  "error": {
    "type": "already_finalized",
    "message": "Recording has already been finalized"
  }
}

Response Fields

Field	Type	Description
`id`	string	Recording ID.
`status`	string	Recording status: `uploaded`, `stitching`, or `failed`.
`transcription_status`	string	Transcription status: `queued`, `processing`, `completed`, or `failed`.
`chunks_received`	integer	Number of chunks received by the backend.
`stitching_job_id`	string	Background job ID for chunk stitching (for debugging).

Background Processing

After calling /finalize, the following happens asynchronously: Typical Processing Times:

Chunk stitching: 5-30 seconds (depending on chunk count)
Transcription: 1-5 minutes (depending on duration)

Webhooks

You’ll receive webhooks for:

recording.uploaded - Fired immediately after finalization
transcription.queued - Transcription job queued
transcription.completed - Transcription finished successfully
transcription.failed - Transcription failed

Streaming Upload Example (Full Flow)

Step 1: Create Streaming Recording

POST /v1/recordings
Authorization: Bearer dtok_live_...

{
  "started_at": "2025-01-13T10:00:00Z",
  "estimated_duration_ms": 3600000,
  "codec": "opus",
  "streaming": true,
  "chunk_duration_ms": 300000
}

Note: When using device tokens (dtok_*), device_id and end_user_id are automatically extracted from the token. When using API keys (sk_*), include device_id and end_user_id in the request body.

Response:

{
  "id": "rec_abc123",
  "status": "streaming",
  "chunk_upload_url_template": "https://s3.../rec_abc123/chunk_{part}.opus?...",
  "max_chunks": 100,
  "expires_at": "2025-01-13T14:00:00Z"
}

Step 2: Upload Chunks (Device)

# Upload chunk 1 (0-5 minutes)
PUT https://s3.../rec_abc123/chunk_1.opus?...
[binary audio data]

# Upload chunk 2 (5-10 minutes)
PUT https://s3.../rec_abc123/chunk_2.opus?...
[binary audio data]

# ... continue uploading chunks ...

# Upload chunk 12 (55-60 minutes)
PUT https://s3.../rec_abc123/chunk_12.opus?...
[binary audio data]

Step 3: Finalize Recording

POST /v1/recordings/rec_abc123/finalize
{
  "total_chunks": 12,
  "final_duration_ms": 3595420,
  "checksum_md5": "5d41402abc4b2a76b9719d911017c592"
}

Response:

{
  "id": "rec_abc123",
  "status": "uploaded",
  "transcription_status": "queued",
  "chunks_received": 12
}

Step 4: Wait for Webhooks

// Webhook 1: recording.uploaded
{
  "type": "recording.uploaded",
  "data": {
    "id": "rec_abc123",
    "uploaded_at": "2025-01-13T11:00:15Z"
  }
}

// Webhook 2: transcription.completed
{
  "type": "transcription.completed",
  "data": {
    "id": "txn_def456",
    "recording_id": "rec_abc123",
    "status": "completed"
  }
}

Best Practices

Verify Chunk Count: Ensure total_chunks matches the number of chunks you actually uploaded. The backend will verify chunk existence before stitching.

Include Checksum: Provide an MD5 checksum for integrity verification, especially for critical recordings (e.g., medical, legal).

Don’t Finalize Early: Only call /finalize after all chunks are uploaded. Finalizing with missing chunks will result in an error.

Idempotency: Calling /finalize multiple times with the same parameters is safe (idempotent). Duplicate requests will return the same response without re-processing.

Troubleshooting

Problem: “Chunk count mismatch” error Solution: Check that all chunks were uploaded successfully. Use the error response to identify missing chunks.

{
  "error": {
    "type": "chunk_mismatch",
    "missing_chunks": [7, 11]  // Re-upload these chunks
  }
}

Problem: Stitching takes too long Solution: This is normal for recordings with many chunks (>50). Check stitching job status via webhooks or polling the recording endpoint.

Create Recording - Create streaming recording
Get Recording - Check stitching status
Create Transcription - Manual transcription trigger

Create Recording List Recordings

​Authentication

​Path Parameters

​Request Body

​Response

​Response Fields

​Background Processing

​Webhooks

​Streaming Upload Example (Full Flow)

​Step 1: Create Streaming Recording

​Step 2: Upload Chunks (Device)

​Step 3: Finalize Recording

​Step 4: Wait for Webhooks

​Best Practices

​Troubleshooting

​Related Endpoints

Authentication

Path Parameters

Request Body

Response

Response Fields

Background Processing

Webhooks

Streaming Upload Example (Full Flow)

Step 1: Create Streaming Recording

Step 2: Upload Chunks (Device)

Step 3: Finalize Recording

Step 4: Wait for Webhooks

Best Practices

Troubleshooting

Related Endpoints