---
title: "Transcribe a recording"
method: POST
path: "/v3/organizations/{orgId}/transcribe"
tags: ["Transcription"]
---

# Transcribe a recording

`POST /v3/organizations/{orgId}/transcribe`

## Request

- Base URL: `https://api.reasonmachines.com`
- URL: `https://api.reasonmachines.com/v3/organizations/{orgId}/transcribe`
- Auth: HTTP bearer

Requires run. Turns a short voice recording into text, as the app's dictation does. Send the audio itself as the request body with its type in Content-Type (audio/wav, audio/webm, audio/ogg, audio/mpeg, audio/mp4, audio/aac or audio/flac), at most 10 MiB. Optional `language` (a BCP 47 tag, or `multi`) sets the spoken language. Returns the transcript, the recognizer's confidence and each word's timing. Charged to the workspace's credits per second of audio; a workspace that cannot pay is refused with 402 before the audio is heard. Requests are rate-limited per person (429 with Retry-After).

<sub>Scope: `run`</sub>

## Query parameters

- `language` string

## Request body `audio/wav`

- string, binary

## Response `200`

The transcript.

- object
  - `transcript` string, required: What was said; empty when nothing was recognized.
  - `confidence` number, nullable: The recognizer's confidence from 0 to 1.
  - `words` object[]: Each recognized word with its start and end in seconds, in spoken order.
    - `word` string, required
    - `start` number, required
    - `end` number, required

## Other responses

- `400`: Invalid request.
- `401`: Missing, invalid, or expired key.
- `402`: The workspace is out of credits; nothing was transcribed (`credit_exhausted`).
- `403`: The key lacks the required scope or role.
- `413`: The recording is larger than 10 MiB.
- `415`: The recording's Content-Type is not a supported audio type.
- `429`: Too many voice requests; retry after the Retry-After seconds.
- `503`: Speech-to-text is not available on this deployment.

## Changes

- **2026-10-26** `bef3f286922a`: 1 info
  - added the optional property `words` to the response with the `200` status
- **2026-10-15** `aa622274c253`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ara/apis/reason-api/changes/v3/organizations/:orgId/transcribe/post.md)

---

[API](https://skmtc.dev/ara/apis/reason-api.md) - [All operations](https://skmtc.dev/ara/apis/reason-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ara/apis/reason-api/revisions/e97c8704807c?raw)