# POST /transcripts/transcribe

**Resource:** [Transcripts](./transcripts.md)  
**Scopes:** `transcripts:write`  
**Write operation:** yes

Kick off an audio transcription via TrustPager AI (Whisper). Pass a publicly fetchable recording URL or a Twilio recording URL plus recording_auth. The transcript lands in /inbox/phone-calls (type=phone_call or legacy alias type=call) or /inbox/meetings (type=meeting) and auto-links to contacts and opportunities matching participant email or phone number. Files over 25 MB are automatically chunked at MP3 frame boundaries. Requires transcripts:write scope. Costs 12 credits per minute.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `recording_url` | body | string | yes | Publicly fetchable audio URL (https), or a private R2 URL for recordings already rehosted by TrustPager. For raw Twilio recording URLs also pass recording_auth. |
| `title` | body | string | yes | Display title for the transcript, e.g. "Outbound call - Edward Anderson". |
| `type` | body | string | yes | Transcript type: phone_call (or legacy alias call) lands in /inbox/phone-calls; meeting lands in /inbox/meetings; voicemail lands in /inbox. |
| `source` | body | string | no | Producer label for filtering (e.g. manual-upload, twilio-call, field-memo). Defaults to api. |
| `source_id` | body | string | no | Foreign key in the producer system (Twilio call_sid, bot_id, etc.). Stored on metadata. |
| `occurred_at` | body | string | no | ISO timestamp when the audio was captured. Defaults to now. |
| `recording_auth` | body | string | no | Basic-auth credentials formatted USER:PASSWORD. Required for raw Twilio recording URLs (pass ACCOUNT_SID:AUTH_TOKEN). |
| `participants` | body | array | no | Participant objects with email, phone, name, and optional role (caller or callee). Used for entity matching and activity creation. role=caller/callee is used by the phone_call_groups view to identify the external phone on outbound calls. |
| `model` | body | string | no | Override the workspace transcription model: whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe. whisper-1 is used internally regardless (required for verbose_json diarization). |
| `metadata` | body | object | no | Free-form metadata attached to the transcript row. |
| `created_by` | body | string | no | User UUID for activity attribution when calling from a service-role context. |
| `existing_transcript_id` | body | string | no | UUID of an existing transcript to overwrite. Use for fallback or retry flows. |

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`