docs(security): add guide for retrieving call artifacts from private storage (#1044)

Document how HIPAA-enabled orgs use the Private API Key to fetch
recordings, logs, and pcaps via authenticated, short-lived URLs now
that public storage URLs are no longer directly downloadable.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: stevenbdf

fern/docs.yml

@@ -737,6 +737,8 @@ navigation:
                 path: security-and-privacy/GDPR.mdx
               - page: HIPAA compliance
                 path: security-and-privacy/hipaa.mdx
+              - page: Retrieve call artifacts
+                path: security-and-privacy/retrieve-call-artifacts.mdx
               - page: PCI compliance
                 path: security-and-privacy/PCI.mdx
               - page: Proxy server guide

fern/security-and-privacy/hipaa.mdx

@@ -193,6 +193,10 @@ When HIPAA mode is enabled, Vapi does not store structured outputs by default. T
   </Accordion>
 </AccordionGroup>
 
+## Retrieving Call Artifacts from Private Storage
+
+For HIPAA-enabled organizations, call recordings and logs are stored in a private bucket and cannot be downloaded directly from the URLs returned in webhooks or API responses. To retrieve recordings, call logs, or other artifacts, call the Vapi API with your Private API Key — see [Retrieve call artifacts](/security-and-privacy/retrieve-call-artifacts) for the full list of endpoints and example requests.
+
 ## Need Further Assistance?
 
 If you have more questions about privacy, HIPAA compliance, or how to configure your Vapi assistant, our support team is here to help. Contact us at security@vapi.ai for personalized assistance and more information on how to make the most of Vapi's voice assistant platform while ensuring your data remains protected.

fern/security-and-privacy/retrieve-call-artifacts.mdx

@@ -0,0 +1,69 @@
+---
+title: Retrieve call artifacts
+subtitle: Download recordings and call logs from Vapi's private storage using authenticated, short-lived URLs.
+slug: security-and-privacy/retrieve-call-artifacts
+---
+
+## Overview
+
+For HIPAA-enabled organizations, call recordings and logs are stored in a private bucket. These URLs are not directly downloadable.
+
+To retrieve a recording or log file, call the Vapi API with your **Private API Key**. The API responds with a `302` redirect to a short-lived, authenticated download URL.
+
+<Warning>
+  Never expose your Private API Key in client-side code or commit it to version control. Store it as a secret in your backend environment.
+</Warning>
+
+## Get your Private API Key
+
+1. Open the [Vapi Dashboard](https://dashboard.vapi.ai/).
+2. Go to **Manage** → **API Keys**.
+3. Copy the value of your **Private API Key**.
+
+## Integration
+
+To download or retrieve a recording or log file, send your Private API Key in the `Authorization` header:
+
+```
+Authorization: Bearer <PRIVATE_API_KEY>
+```
+
+Each endpoint responds with a `302` redirect to a short-lived signed URL. Most HTTP clients follow redirects by default — for example, `curl -L` follows the redirect and downloads the artifact in a single command.
+
+## Available endpoints
+
+Base URL: `https://api.vapi.ai`
+
+| Endpoint | Returns |
+| --- | --- |
+| `GET /call/{id}/mono-recording` | Combined mono recording (WAV/MP3) |
+| `GET /call/{id}/stereo-recording` | Stereo recording, customer + assistant on separate channels (WAV/MP3) |
+| `GET /call/{id}/customer-recording` | Customer-only mono recording (WAV/MP3) |
+| `GET /call/{id}/assistant-recording` | Assistant-only mono recording (WAV/MP3) |
+| `GET /call/{id}/video-recording` | Video recording, when enabled (MP4) |
+| `GET /call/{id}/call-logs` | Structured call logs (gzipped JSONL) |
+| `GET /call/{id}/pcap` | Packet capture, when enabled (PCAP) |
+
+## Example
+
+Download a stereo recording for a given call:
+
+```bash
+curl -L \
+  -H "Authorization: Bearer $VAPI_PRIVATE_API_KEY" \
+  -o recording.wav \
+  https://api.vapi.ai/call/<CALL_ID>/stereo-recording
+```
+
+Download call logs:
+
+```bash
+curl -L \
+  -H "Authorization: Bearer $VAPI_PRIVATE_API_KEY" \
+  -o call-logs.jsonl.gz \
+  https://api.vapi.ai/call/<CALL_ID>/call-logs
+```
+
+<Note>
+  Signed URLs returned by these endpoints expire after a short period. Always request a fresh URL from the API rather than caching the redirect target.
+</Note>