> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryopencomputer.com/llms.txt > Use this file to discover all available pages before exploring further. # Workflow recordings > Upload reusable audio, transcribe it, and select it in a voice workflow. Workflow recordings are reusable audio clips for workflow prompts. They are different from a run recording, which is media produced by one execution; see [Calls, runs, and results](/guides/runs.md). Add recordings in the dashboard or through the authenticated API, then select library items in the workflow editor. For API examples, set `ATHENA_BASE_URL` and `ATHENA_API_KEY` as described in the [API quickstart](/guides/api.md). ## Upload in the dashboard Open **Recordings → Uploaded recordings → Upload Recording**. Choose an audio file up to 5 MiB, select its language or leave **Multilingual (Auto-detect)**, and wait for transcription. Review and edit the transcript, then choose **Upload 1 Recording** (the count changes for multiple files). The saved entry shows its recording ID, filename, and transcript. Use **Edit ID** to give the clip a useful descriptive ID. The separate **TTS cache** tab is distinct from your uploaded library and from recordings produced by individual runs. The dialog also offers **Record** for microphone capture. Allow microphone access before using that control. File upload and automatic transcription were verified separately from microphone recording. ## Prepare and transcribe a clip Record or export an audio file before uploading it. The upload API accepts up to 20 files per request, with each file at most 5,242,880 bytes (5 MiB). The transcript is required when creating a recording. You can transcribe the file with Athena or provide and review the transcript yourself. ```bash theme={null} curl --fail-with-body "$ATHENA_BASE_URL/api/v1/workflow-recordings/transcribe" \ -H "X-API-Key: $ATHENA_API_KEY" \ -F "file=@welcome.wav" \ -F "language=en" ``` Review the returned `transcript` before using it. Correct names, numbers, pronunciation, and punctuation so the transcript matches the audio. This endpoint returns transcription output; it does not add the file to the library. ## Upload and create a library item The upload uses two separate requests: first ask Athena for a short-lived storage URL, then send the file bytes directly to that URL. Creating the metadata record is a third request. 1. Request a presigned upload URL. Set `file_size` to the file's actual size in bytes. ```bash theme={null} curl --fail-with-body "$ATHENA_BASE_URL/api/v1/workflow-recordings/upload-url" \ -H "X-API-Key: $ATHENA_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "files": [{ "filename": "welcome.wav", "mime_type": "audio/wav", "file_size": 123456 }] }' ``` Copy the returned `upload_url`, `recording_id`, and `storage_key`. The signed URL expires after 30 minutes. Treat it as temporary access and do not log or share it. 2. Upload the exact file bytes with `PUT`. Keep the `Content-Type` consistent with the MIME type used in the URL request. ```bash theme={null} curl --fail-with-body -X PUT "$UPLOAD_URL" \ -H "Content-Type: audio/wav" \ --data-binary @welcome.wav ``` 3. Create the library record after the PUT succeeds. Use the short `recording_id` and `storage_key` returned in step 1. `transcript` is required; the TTS fields are optional in the API. ```bash theme={null} curl --fail-with-body "$ATHENA_BASE_URL/api/v1/workflow-recordings/" \ -H "X-API-Key: $ATHENA_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "recordings": [{ "recording_id": "", "transcript": "Welcome to Example Support.", "storage_key": "", "tts_provider": null, "tts_model": null, "tts_voice_id": null, "metadata": { "original_filename": "welcome.wav", "file_size_bytes": 123456, "mime_type": "audio/wav", "language": "en" } }] }' ``` Replace the angle-bracket values and example transcript and file size with the values for your clip. The TTS fields are optional; if you include them, use the configuration selected for your workflow. ## List and select recordings List the active recordings available to your organization: ```bash theme={null} curl --fail-with-body "$ATHENA_BASE_URL/api/v1/workflow-recordings/" \ -H "X-API-Key: $ATHENA_API_KEY" ``` The response includes a numeric `id`, a descriptive `recording_id`, the transcript, and metadata. Optional query filters include `workflow_id`, `tts_provider`, `tts_model`, and `tts_voice_id`. In the workflow editor, select an existing recording in the relevant field: * Edit the **Start Call** node and set its greeting type to **Pre-recorded Audio**. * Set a transition's speech type to **Audio** to play a clip before moving to the next node. * Use a recording selector in a node property or in **Settings → Voicemail & Screening**. * In prompt fields that support recording mentions, type `@` and choose a library item. The editor inserts a `RECORDING_ID: [ transcript ]` marker. The selectors search the library ID, transcript, and filename; they also offer a preview. A selector stores the numeric database `id` in its workflow field, even where the field name ends in `recording_id`. Prompt markers instead use the descriptive `recording_id` string. Keep these identifier forms distinct when editing workflow JSON or calling APIs directly. | Value | Meaning | Used for | | - | - | - | | `id` | Immutable numeric primary key returned by the library API | Editor selections and `recording_pk` fields | | `recording_id` | Organization-unique descriptive string returned by the API | `RECORDING_ID:` prompt markers and library rename/delete routes | | Run recording URL | Media artifact for one workflow run | Previewing or downloading that run in the Runs view; it is not a library item | ## Rename or deactivate a recording Rename the descriptive string by passing the numeric `id` in the URL: ```bash theme={null} curl --fail-with-body -X PATCH "$ATHENA_BASE_URL/api/v1/workflow-recordings/123" \ -H "X-API-Key: $ATHENA_API_KEY" \ -H "Content-Type: application/json" \ --data '{"recording_id":"welcome_message"}' ``` The new ID may contain letters, numbers, hyphens, or underscores, up to 64 characters. The rename route updates matching `RECORDING_ID: old-id` markers in non-legacy workflow definitions. Numeric editor references keep pointing to the same recording. Deactivate a library item using its descriptive `recording_id` string, not its numeric `id`: ```bash theme={null} curl --fail-with-body -X DELETE \ "$ATHENA_BASE_URL/api/v1/workflow-recordings/welcome_message" \ -H "X-API-Key: $ATHENA_API_KEY" ``` This is a soft delete: it marks the record inactive. The route does not delete the stored object or remove references from workflows. Inactive items no longer appear in active library lists and may not resolve when a workflow tries to play them. Update or remove those workflow references before deactivating a clip that is still in use. ## Voicemail and screening messages In **Settings → Voicemail & Screening**, the workflow editor can select a text or recording for the screening message and, when **Leave a message** is selected, the voicemail message. The screening message introduces the caller and waits for the person to respond; the UI offers a 1–60 second wait, defaulting to 30 seconds. Leaving the screening message empty ends screened calls. A voicemail message is played and the call then disconnects. These settings are intended for workflows using separate speech and language models. The UI states that they do not apply to realtime speech-to-speech models. Library-audio playback in native realtime sessions has not been verified; use text greetings and messages for those models. A successful library upload does not establish playback compatibility. The Start Call node's **Delayed Start** setting controls the initial listening window for a silent answer; the default is 1.2 seconds. A brief human greeting can end the wait sooner. Delayed Start is distinct from the post-screening wait. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.