> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Murph dictation

> Turn a short voice recording into text for the Murph message box

Dictation turns one short recording into text. The web app's microphone button
uses it: the transcript goes back into the message box for the user to review
and send. Dictation does not send a message to Murph, start a turn, or store
the recording. For how dictation looks and behaves in the app, see
[Dictate a message](/v2/ui-guide#dictate-a-message).

## Transcribe a recording

`POST /api/v2/murph/dictation`

```bash curl theme={null}
curl https://api.apostra.com/api/v2/murph/dictation \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio": {"base64": "<base64 audio>", "mimeType": "audio/webm"}, "language": "en"}'
```

### Request

| Field | Type | Notes |
| - | - | - |
| `audio.base64` | string | Required. The recording, base64-encoded. At most 7 MB once decoded |
| `audio.mimeType` | enum | Required. One of `audio/webm`, `audio/mp4`, `audio/mpeg`, `audio/wav` |
| `language` | enum | Optional. The speaker's usual chat language, used as a hint. Speech in another language is still transcribed |

### Response

```json theme={null}
{
  "data": {
    "transcript": "Shift the Summer Sizzle budget to CTV."
  },
  "error": null
}
```

| Field | Type | Notes |
| - | - | - |
| `data.transcript` | string | The spoken words as plain text. Empty when the recording held no intelligible speech |

Errors use the same envelope with `data: null` and an `error` object carrying
`code` and `message`.

### How names are spelled

The recording is transcribed by Google Cloud Speech-to-Text in the United
States, in the language given by `language` (English when it is omitted). To
spell names correctly, the request includes common advertising terms, Apostra
product terms, and the names of the caller's own account's advertisers,
campaigns and storefront as spelling hints. Names from one account are never
included in another account's request. A recording with no recognizable speech
returns an empty `transcript`.

### Limits

Dictation is refused with `429` once the caller has reached their daily Murph
usage limit, the same limit chat turns use.

### Errors

| Status | Code | When |
| - | - | - |
| `400` | `VALIDATION_ERROR` | The body is malformed, the format is not one of the four accepted types, or the recording is empty or larger than 7 MB |
| `401` | — | The request is not authenticated |
| `429` | `RATE_LIMITED` | The caller's daily Murph usage limit is reached. `details.resetAt` gives the reset time when known |
| `503` | `SERVICE_UNAVAILABLE` | Transcription is unavailable or failed for this recording. Retrying later may succeed |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.