> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.telekesher.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.telekesher.dev/_mcp/server. # Start recording POST https://api.telekesher.dev/v1/sessions/{uuid}/recording/start Content-Type: application/json **Rate limit: Per command** · **Burst:** 4 · **Refill:** 1 req/s Start a [Recording](/api/recording) of the call via the gateway recording service. The accepted [Operation](/api) is returned immediately; use its `operation_uuid` to correlate the command lifecycle. Once `command.recording.start.accepted` supplies `recording_uuid`, use that identifier to correlate the Recording's complete webhook lifecycle. Requires recording to be enabled on this gateway. Each request opens a stream, and recording normally starts once per call. Output is 8 kHz mono mixed WAV (both legs combined). Format is not configurable. **Triggered webhooks:** - `command.recording.start.accepted` (immediate, when recording begins; carries `recording_uuid`, the signed public `pull_url`, and the `operation_uuid` of this `recording/start` command). Actual recording errors surface later as `recording.failed`. - `recording.became_available` (once the gateway confirms the recording is durably ingested; carries the explicit `pull_url` and `live_url` signed links) — or `recording.failed` if it never confirms within the validation window. - When `enable_voice_activity_events` is true, `recording.speech.started` and `recording.speech.ended` report customer speech transitions for the lifetime of this recording. Sensitivity and speech/silence confirmation durations are configurable. The signed `pull_url` carried by `command.recording.start.accepted` is immediately fetchable — the recording can be streamed while it is still in progress. `pull_url` fetches the whole recording so far. Treat the complete URL as an opaque, time-bounded bearer capability and use it exactly as emitted; do not construct, parse, or modify its host, path, or token. Its default 24-hour window starts when `command.recording.start.accepted` is emitted, not when recording stops. Reference: https://docs.telekesher.dev/api/recording/start ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: voice-api version: 1.0.0 paths: /v1/sessions/{uuid}/recording/start: post: operationId: startRecording summary: Start recording description: >- **Rate limit: Per command** · **Burst:** 4 · **Refill:** 1 req/s Start a [Recording](/api/recording) of the call via the gateway recording service. The accepted [Operation](/api) is returned immediately; use its `operation_uuid` to correlate the command lifecycle. Once `command.recording.start.accepted` supplies `recording_uuid`, use that identifier to correlate the Recording's complete webhook lifecycle. Requires recording to be enabled on this gateway. Each request opens a stream, and recording normally starts once per call. Output is 8 kHz mono mixed WAV (both legs combined). Format is not configurable. **Triggered webhooks:** - `command.recording.start.accepted` (immediate, when recording begins; carries `recording_uuid`, the signed public `pull_url`, and the `operation_uuid` of this `recording/start` command). Actual recording errors surface later as `recording.failed`. - `recording.became_available` (once the gateway confirms the recording is durably ingested; carries the explicit `pull_url` and `live_url` signed links) — or `recording.failed` if it never confirms within the validation window. - When `enable_voice_activity_events` is true, `recording.speech.started` and `recording.speech.ended` report customer speech transitions for the lifetime of this recording. Sensitivity and speech/silence confirmation durations are configurable. The signed `pull_url` carried by `command.recording.start.accepted` is immediately fetchable — the recording can be streamed while it is still in progress. `pull_url` fetches the whole recording so far. Treat the complete URL as an opaque, time-bounded bearer capability and use it exactly as emitted; do not construct, parse, or modify its host, path, or token. Its default 24-hour window starts when `command.recording.start.accepted` is emitted, not when recording stops. tags: - recording parameters: - name: uuid in: path description: '[Session](/api/sessions) UUID (format `{5-char-prefix}-{uuid}`).' required: true schema: type: string - name: Authorization in: header description: >- Application auth. Send `Authorization: Bearer :`. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details. required: true schema: type: string - name: Idempotency-Key in: header description: >- Optional client-generated key for a mutating endpoint. It identifies one method, route, query, content type, and exact raw body within the authenticated app. Reusing it for a different request returns 422. While its record exists, a retry replays the original accepted response when available. Keys are valid for 1 hour. Allowed characters: letters, digits, dot, hyphen, underscore; max 128 characters. See the Idempotency guide. required: false schema: type: string responses: '202': description: Command accepted for async execution content: application/json: schema: $ref: '#/components/schemas/AsyncCommandResponse' '400': description: >- Missing `Authorization`, malformed Bearer credentials, or invalid request parameters. A syntactically valid credential with an invalid API key returns `401` instead. content: application/json: schema: $ref: '#/components/schemas/StartRecordingRequestBadRequestError' '401': description: >- The Bearer credential is syntactically valid but its API key is invalid. Missing `Authorization` or malformed Bearer credentials return `400`. content: application/json: schema: $ref: '#/components/schemas/StartRecordingRequestUnauthorizedError' '404': description: >- The requested resource was not found or is not owned by the authenticated app. content: application/json: schema: $ref: '#/components/schemas/StartRecordingRequestNotFoundError' '409': description: >- The request cannot be completed because of state conflict — typically the session is terminating, or the resource (room, recording) is in a state incompatible with this command. On an operation that accepts `Idempotency-Key`, this status can also mean the original request with that key is still in progress; wait for its result rather than sending a different request with the same key. content: application/json: schema: $ref: '#/components/schemas/StartRecordingRequestConflictError' '413': description: Request body exceeds the endpoint's size limit. content: application/json: schema: $ref: '#/components/schemas/StartRecordingRequestContentTooLargeError' '415': description: >- A request with a JSON body must use `Content-Type: application/json`. content: application/json: schema: $ref: >- #/components/schemas/StartRecordingRequestUnsupportedMediaTypeError '422': description: >- The `Idempotency-Key` was reused with a different request body. A key maps to one request; use a new key. See the Idempotency guide. content: application/json: schema: $ref: >- #/components/schemas/StartRecordingRequestUnprocessableEntityError '429': description: >- Rate limit exceeded — a per-command, per-room, or per-app token bucket was empty. The `retry_after` field gives the integer seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/StartRecordingRequestTooManyRequestsError' '500': description: Internal gateway error. content: application/json: schema: $ref: '#/components/schemas/StartRecordingRequestInternalServerError' '503': description: |- Recording is not enabled on this gateway, or an `Idempotency-Key` was supplied and its store is unavailable. In either case no recording side effect is started and no webhook is emitted; retry an idempotency-store outage with the same key. content: application/json: schema: $ref: >- #/components/schemas/StartRecordingRequestServiceUnavailableError requestBody: content: application/json: schema: type: object properties: operation_uuid: type: string format: uuid description: >- Optional caller-supplied per-command correlation id, a bare lowercase RFC-4122 v4 UUID (no prefix). Echoed back as `operation_uuid` in the 202 ack. A later lifecycle webhook carries it only when the gateway can unambiguously associate that event with this command; the field is correlation, not proof of causation. When omitted, the gateway mints one. Not an idempotency key — request deduplication is the `Idempotency-Key` header. Invalid input (not a v4 UUID) is rejected with `400 invalid_request`. enable_voice_activity_events: type: boolean default: false description: >- When true, emit `recording.speech.started` and `recording.speech.ended` while this session recording is active. Detection is passive and does not alter recorded audio. Not supported for standalone `type: ws` sessions or room recordings. voice_activity_config: $ref: >- #/components/schemas/V1SessionsUuidRecordingStartPostRequestBodyContentApplicationJsonSchemaVoiceActivityConfig description: >- Required tuning when voice activity events are enabled. Supplying this object requires `enable_voice_activity_events: true`; otherwise the request is rejected. servers: - url: https://api.telekesher.dev description: Gateway server components: schemas: V1SessionsUuidRecordingStartPostRequestBodyContentApplicationJsonSchemaVoiceActivityConfig: type: object properties: sensitivity: type: integer description: |- Detection sensitivity. Lower values are more resistant to background noise but can miss quiet speech. Higher values detect quieter or more distant speech but increase the chance that background noise is classified as speech. Start around 25 for noisy environments, 50 for ordinary calls, or 75 for quiet or distant speakers. silence_duration_ms: type: integer description: |- Continuous silence, in milliseconds, before `recording.speech.ended`. Lower values end faster but can split natural pauses; higher values preserve pauses but delay the end event. Durations are evaluated at media-frame granularity, so transitions can take roughly one additional frame plus webhook delivery. speech_duration_ms: type: integer description: |- Minimum continuous speech, in milliseconds, before `recording.speech.started`. Lower values react faster but admit short noises; higher values reject transient sounds but delay the start event. required: - sensitivity - silence_duration_ms - speech_duration_ms description: |- Required tuning when voice activity events are enabled. Supplying this object requires `enable_voice_activity_events: true`; otherwise the request is rejected. title: >- V1SessionsUuidRecordingStartPostRequestBodyContentApplicationJsonSchemaVoiceActivityConfig AsyncCommandResponseStatus: type: string enum: - in_progress - completed title: AsyncCommandResponseStatus AsyncCommandResponse: type: object properties: operation_uuid: type: string format: uuid status: $ref: '#/components/schemas/AsyncCommandResponseStatus' already_ended: type: boolean enum: - true description: >- Optional. Set to `true` on idempotent terminal commands when the session was already in a terminal state at the time the request was received. Absent otherwise. required: - operation_uuid - status description: >- 202 Accepted body for an async command. The command's success/failure is delivered later as a domain lifecycle webhook (e.g. `playback.started`/`stopped`/`failed`, `command.recording.start.accepted`, `digits.collected`, `session.answered`/`session.ended`). A lifecycle event carries `operation_uuid` only when it can be unambiguously associated with the submitted command — not as a generic ack on this response. title: AsyncCommandResponse V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode: type: string enum: - invalid_request - payload_too_large - result_set_too_large - unauthorized - forbidden - not_found - conflict - recording_not_active - room_full - rate_limited - unavailable - internal description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. title: >- V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode StartRecordingRequestBadRequestError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: StartRecordingRequestBadRequestError StartRecordingRequestUnauthorizedError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: StartRecordingRequestUnauthorizedError StartRecordingRequestNotFoundError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: StartRecordingRequestNotFoundError StartRecordingRequestConflictError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: StartRecordingRequestConflictError StartRecordingRequestContentTooLargeError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: StartRecordingRequestContentTooLargeError StartRecordingRequestUnsupportedMediaTypeError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: StartRecordingRequestUnsupportedMediaTypeError StartRecordingRequestUnprocessableEntityError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: StartRecordingRequestUnprocessableEntityError StartRecordingRequestTooManyRequestsError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - retry_after - success title: StartRecordingRequestTooManyRequestsError StartRecordingRequestInternalServerError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: StartRecordingRequestInternalServerError StartRecordingRequestServiceUnavailableError: type: object properties: code: $ref: >- #/components/schemas/V1SessionsUuidRecordingStartPostResponsesContentApplicationJsonSchemaCode description: >- Stable, machine-readable error class from a closed set of twelve values. Branch on this for programmatic handling. New codes are only added with a documented API change. Maps to the HTTP status as follows: `invalid_request` (400/415/422), `payload_too_large` and `result_set_too_large` (413), `unauthorized` (401), `forbidden` (403), `not_found` (404), `recording_not_active` (400); `conflict` and `room_full` (409), `rate_limited` (429), `unavailable` (502/503/529), `internal` (500). Note: `413` is the only status shared by two codes — `payload_too_large` means the request body exceeded its size cap, while `result_set_too_large` means a list response exceeded the system result ceiling (narrow the query with filters and retry). Note: `unavailable` is the only code that maps to multiple HTTP statuses, which represent different retry conditions: `502` means a command dependency could not accept the request, `503` means a required service (including the idempotency store) is temporarily unavailable, and `529` means the gateway is overloaded with no spare capacity. Use the HTTP status and operation description, not just `code`, to distinguish them. error: type: string description: >- Human-readable, English-only error message. For display only — phrasing may change without notice, so branch on `code`, not on this string. retry_after: type: integer description: >- Integer seconds to wait before retrying. Present on `429` (the time until the denying token bucket refills by one token) and on `529` (overload back-off hint). Mirrors the `Retry-After` response header. success: type: boolean required: - code - error - success title: StartRecordingRequestServiceUnavailableError securitySchemes: bearerAppAuth: type: http scheme: bearer description: >- Application auth. Send `Authorization: Bearer :`. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details. ``` ## Examples **Request** ```json {} ``` **Response** ```json { "operation_uuid": "550e8400-e29b-41d4-a716-446655440000", "status": "in_progress" } ``` **SDK Code** ```python Recording_startRecording_example import requests url = "https://api.telekesher.dev/v1/sessions/uuid/recording/start" payload = {} headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Recording_startRecording_example const url = 'https://api.telekesher.dev/v1/sessions/uuid/recording/start'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Recording_startRecording_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.telekesher.dev/v1/sessions/uuid/recording/start" payload := strings.NewReader("{}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Recording_startRecording_example require 'uri' require 'net/http' url = URI("https://api.telekesher.dev/v1/sessions/uuid/recording/start") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java Recording_startRecording_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.telekesher.dev/v1/sessions/uuid/recording/start") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php Recording_startRecording_example request('POST', 'https://api.telekesher.dev/v1/sessions/uuid/recording/start', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Recording_startRecording_example using RestSharp; var client = new RestClient("https://api.telekesher.dev/v1/sessions/uuid/recording/start"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Recording_startRecording_example import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.telekesher.dev/v1/sessions/uuid/recording/start")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```