---
title: "Start recording a leg to a WAV file"
method: POST
path: "/legs/{id}/record"
tags: ["Legs"]
---

# Start recording a leg to a WAV file

`POST /legs/{id}/record`

For SIP legs, recording is stereo (left=incoming, right=outgoing). For legs in a room, stereo at 16kHz (left=participant audio, right=mixed-minus-self).

## Request body

- RecordingRequest
  - `storage` 'file' | 's3' | 'gcs', required — "file" (default) — local disk, "s3" — upload to S3 after recording stops, "gcs" — upload to Google Cloud Storage via the native GCS API (Application Default Credentials / Workload Identity)
  - `multi_channel` boolean, required — When true, record each participant to a separate mono WAV file in addition to the full mix. Only applies to room recordings.
  - `s3_bucket` string, required — S3 bucket name. Overrides S3_BUCKET env var. Required if env var is not set.
  - `s3_region` string, required — AWS region. Overrides S3_REGION env var. Default us-east-1.
  - `s3_endpoint` string, required — Custom S3 endpoint (MinIO, etc.). Overrides S3_ENDPOINT env var.
  - `s3_prefix` string, required — Key prefix (e.g. recordings/). Overrides S3_PREFIX env var.
  - `s3_access_key` string, required — AWS access key ID. Overrides default credential chain.
  - `s3_secret_key` string, required — AWS secret access key. Must be set together with s3_access_key.
  - `gcs_bucket` string, required — GCS bucket name. Overrides GCS_BUCKET env var. Required if env var is not set when storage=gcs.
  - `gcs_object_name_prefix` string, required — Object name prefix (e.g. recordings or recordings/). Overrides GCS_OBJECT_NAME_PREFIX env var. A trailing slash is added automatically when missing.
  - `filename` string, required — Optional output basename for the WAV file. A .wav suffix is added when missing. Must be a single path segment (no directories). Dots inside the name are preserved (only a trailing .wav is treated as the extension). Rejected with 409 if the file already exists or another recording is using the same name. When omitted, a timestamped name is generated.

## Response `200`

Recording started

- StatusResponse
  - `instance_id` string — Instance identifier
  - `status` string, required

## Other responses

- `400` — Invalid storage type, S3 not configured, or invalid S3 credentials
- `404` — Leg not found
- `409` — Leg has no audio reader or room not found
- `500` — Failed to create recording file

## Changes

- **2026-08-03** `955190a7fb6d` — 1 breaking
  - added the new required request property `filename`
- **2026-07-29** `73b13634e11f` — 2 breaking, 1 info
  - added the new required request property `gcs_bucket`
  - added the new required request property `gcs_object_name_prefix`
  - added the new `gcs` enum value to the request property `storage`
- **2026-03-31** `70d3addada94` — 1 info
  - the request property `multi_channel` with a default value became required
- **2026-03-26** `8d385fec9a6f` — 1 info
  - added the new optional request property `multi_channel`
- **2026-03-26** `d09c97c6ca8c` — 1 warning, 8 info
  - removed the request property `multi_channel`
  - the request property `s3_access_key` became optional
  - the request property `s3_bucket` became optional
  - the request property `s3_endpoint` became optional
  - …5 more

[Full history](https://skmtc.dev/voiceblender/apis/voiceblender-api/changes/legs/:id/record/post.md)

---

[API](https://skmtc.dev/voiceblender/apis/voiceblender-api.md) · [All operations](https://skmtc.dev/voiceblender/apis/voiceblender-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/voiceblender/voiceblender-api/revisions/89ff267f0958/schema)