Set Call Recording Log

Endpoint

POST /calls/{call_id}/recording-log
Base URL: https://api.example-ai.com/v1

Description

Attach or update a recording log for a completed call.
Use this endpoint to store recording URLs, durations, transcription status, and related metadata for compliance and analytics.

Authentication

Authorization: Bearer sk_test_51_fakeapikey123456

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>
Content-Type	string	Yes	application/json
Idempotency-Key	string	No	Optional key to make the request idempotent.

Request Parameters

Path Parameters

Name	Type	Required	Description
call_id	string	Yes	Unique call ID, e.g. call_1j2kd9.

Body Parameters

Name	Type	Required	Description
recording_id	string	Yes	Unique recording ID, e.g. rec_8sj29a.
recording_url	string	Yes	HTTPS URL to the call recording file.
duration_seconds	integer	Yes	Length of the recording in seconds.
transcription_id	string	No	ID of the transcription job, if applicable.
transcription_status	string	No	Status of transcription: pending, completed, or failed.
started_at	string	No	ISO timestamp when recording started.
ended_at	string	No	ISO timestamp when recording ended.
metadata	object	No	Free-form key/value metadata (e.g. tags, labels, compliance flags).

Example Request

curl

curl -X POST "https://api.example-ai.com/v1/calls/call_1j2kd9/recording-log" \
  -H "Authorization: Bearer sk_test_51_fakeapikey123456" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rec-log-2026-03-15-01" \
  -d '{
    "recording_id": "rec_8sj29a",
    "recording_url": "https://cdn.example-ai.com/recordings/call_1j2kd9_rec_8sj29a.mp3",
    "duration_seconds": 642,
    "transcription_id": "tr_92kd82",
    "transcription_status": "completed",
    "started_at": "2026-03-15T13:40:29Z",
    "ended_at": "2026-03-15T13:51:11Z",
    "metadata": {
      "direction": "outbound",
      "agent_id": "usr_82hd92",
      "labels": ["vip", "renewal"]
    }
  }'

Example Response

{
  "status": "success",
  "message": "Call recording log saved successfully.",
  "data": {
    "call_id": "call_1j2kd9",
    "recording_id": "rec_8sj29a",
    "recording_url": "https://cdn.example-ai.com/recordings/call_1j2kd9_rec_8sj29a.mp3",
    "duration_seconds": 642,
    "transcription_id": "tr_92kd82",
    "transcription_status": "completed",
    "started_at": "2026-03-15T13:40:29Z",
    "ended_at": "2026-03-15T13:51:11Z",
    "metadata": {
      "direction": "outbound",
      "agent_id": "usr_82hd92",
      "labels": ["vip", "renewal"]
    },
    "created_at": "2026-03-15T14:22:11Z",
    "updated_at": "2026-03-15T14:22:11Z"
  }
}

Error Responses

400 Bad Request

{
  "status": "error",
  "message": "Field 'recording_url' must be a valid HTTPS URL.",
  "data": null
}

401 Unauthorized

{
  "status": "error",
  "message": "Invalid API token.",
  "data": null
}

404 Not Found

{
  "status": "error",
  "message": "Call not found: call_1j2kd9.",
  "data": null
}

500 Server Error

{
  "status": "error",
  "message": "Could not persist recording log. Please retry.",
  "data": null
}

Code Examples

curl

curl -X POST "https://api.example-ai.com/v1/calls/call_1j2kd9/recording-log" \
  -H "Authorization: Bearer sk_test_51_fakeapikey123456" \
  -H "Content-Type: application/json" \
  -d '{
    "recording_id": "rec_8sj29a",
    "recording_url": "https://cdn.example-ai.com/recordings/call_1j2kd9_rec_8sj29a.mp3",
    "duration_seconds": 642
  }'

JavaScript (fetch)

const body = {
  recording_id: 'rec_8sj29a',
  recording_url:
    'https://cdn.example-ai.com/recordings/call_1j2kd9_rec_8sj29a.mp3',
  duration_seconds: 642
};

const response = await fetch(
  'https://api.example-ai.com/v1/calls/call_1j2kd9/recording-log',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk_test_51_fakeapikey123456',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  }
);

const result = await response.json();
console.log(result);

TypeScript (axios)

import axios, { AxiosResponse } from 'axios';

interface CallRecordingLog {
  call_id: string;
  recording_id: string;
  recording_url: string;
  duration_seconds: number;
  transcription_id?: string;
  transcription_status?: 'pending' | 'completed' | 'failed';
  started_at?: string;
  ended_at?: string;
  metadata?: Record<string, unknown>;
}

interface RecordingLogResponse {
  status: 'success' | 'error';
  message: string;
  data: CallRecordingLog | null;
}

const payload = {
  recording_id: 'rec_8sj29a',
  recording_url:
    'https://cdn.example-ai.com/recordings/call_1j2kd9_rec_8sj29a.mp3',
  duration_seconds: 642
};

const res: AxiosResponse<RecordingLogResponse> = await axios.post(
  'https://api.example-ai.com/v1/calls/call_1j2kd9/recording-log',
  payload,
  {
    headers: {
      Authorization: 'Bearer sk_test_51_fakeapikey123456'
    }
  }
);

console.log(res.data.data);

Notes

• Use Idempotency-Key for retried requests to prevent duplicate recording logs.
• You can safely call this endpoint multiple times for the same call_id and recording_id to update metadata.