REST API and webhooks

Transcription API Recordings In, Text Out

Connect Transcrify to the tools where your recordings already are. Send a file or a link, get a call back when the transcript is ready, and read it as plain text or as timed segments with speakers. One HTTP request is enough to start.

The API uses the same transcription hours as the panel. A free account includes 10 recordings and 5 hours, enough to build and test an integration. See the plans

1

Send a recording

Give us a link to the file, upload it, or pass a YouTube address. You get an id back at once.

2

Get told when it is done

We call your webhook when the transcript is ready, usually a few minutes later. No polling needed.

3

Read the result

Fetch the text in one piece, or as timed segments with speakers to build subtitles and notes.

Quick start

This script takes the address of a recording, has it transcribed and prints the text. It is the whole loop in under forty lines: send, wait, read. You need curl, jq and a key with the scopes files.write and files.read.

transcribe-url.sh
#!/usr/bin/env bash
# Transcribe a recording that is reachable by URL and print the text.
#
#   export TRANSCRIFY_KEY=trk_...
#   ./transcribe-url.sh https://example.com/calls/2026-11-20.mp3
#
# Needs curl and jq. The key needs the scopes files.write and files.read.
set -euo pipefail

API="https://api.transcrify.com"
URL="$1"

# 1. Hand over the URL. Transcrify downloads the file itself.
id=$(jq -n --arg url "$URL" '{url: $url}' \
  | curl -fsS -X POST "$API/api/v1/files/url" \
      -H "X-Api-Key: $TRANSCRIFY_KEY" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq -r .id)
echo "Accepted as file $id" >&2

# 2. Wait. A webhook is the better way in production; polling is fine for a script.
while true; do
  file=$(curl -fsS "$API/api/v1/files/$id" -H "X-Api-Key: $TRANSCRIFY_KEY")
  status=$(jq -r .statusLabel <<<"$file")
  case "$status" in
    transcribed)
      # 3. Print the text.
      jq -r .transcriptionText <<<"$file"
      exit 0
      ;;
    *failed)
      echo "Could not be transcribed: $status" >&2
      exit 1
      ;;
  esac
  echo "  $status..." >&2
  sleep 20
done

The base address is https://api.transcrify.com and every call lives under /api/v1/. Requests and answers are JSON, except file uploads, which are multipart forms.

Keys

Create a key in the panel under API keys. It looks like trk_a1b2c3d4e5f6_9f2c… and is shown once, so copy it then. Send it with every request in the X-Api-Key header. It does not work as a Bearer token.

A key carries scopes, and it can do only what its scopes allow. Make one key per tool, with the narrowest set that does the job: a key that leaks from one integration can then be revoked without touching the others.

ScopeWhat it allows
files.writeSend recordings in. Reads nothing back.
files.readStatus, transcripts, summaries and the list of recordings.
webhooks.manageRegister and inspect webhook addresses.
files.downloadCreate expiring links to the recording or its text.

Treat a key like a password: it reads a customer's recordings. Keep it on a server or in your automation tool's secret store, never in a web page or a mobile app.

Send a recording

There are three ways in, and all of them put the recording through the same processing and answer with the same acknowledgement. Keep the id from it: every later call uses it.

By URL: the easiest for automations

Pass the address of the file and we download it ourselves, up to 2 GB. Nothing has to flow through your tool, which is why this is the route to use from Zapier, Make and n8n. The address must be reachable without signing in, for example a signed link from your storage or the recording link a telephony service provides.

curl
curl -X POST https://api.transcrify.com/api/v1/files/url \
  -H "X-Api-Key: $TRANSCRIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/calls/2026-11-20.mp3"}'
Response
{
  "id": 1300,
  "uid": "url673e1c0a5b2f41.90210",
  "statusLabel": "downloading"
}

By upload

Send the file itself as a multipart form, up to 50 MB in one request. For larger files, split them and send the parts in order; the folder example on the examples page does exactly that.

curl
curl -X POST https://api.transcrify.com/api/v1/files \
  -H "X-Api-Key: $TRANSCRIFY_KEY" \
  -F "[email protected]"
curl, a large file in parts
# First part: the normal upload, plus your own uid and the number of parts
curl -X POST https://api.transcrify.com/api/v1/files \
  -H "X-Api-Key: $TRANSCRIFY_KEY" \
  -F "[email protected]" -F "uid=call-2026-11-20" -F "totalChunks=3"

# Every further part, in order
curl -X POST https://api.transcrify.com/api/v1/files/chunk \
  -H "X-Api-Key: $TRANSCRIFY_KEY" \
  -F "[email protected]" -F "uid=call-2026-11-20" -F "currentChunk=2"

From YouTube

Pass the link to a video; the title and length are read from it.

curl
curl -X POST https://api.transcrify.com/api/v1/files/youtube \
  -H "X-Api-Key: $TRANSCRIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"link":"https://www.youtube.com/watch?v=a7_WFUlFS94"}'

You do not need to know how long the recording is

Leave the length out and we measure it once the file has arrived, then take that much from the account's hours. If you do know it, send totalDuration in seconds: the allowance is then checked right away, and a recording the account cannot afford is refused immediately with 402 instead of failing a little later. Optional fields on every route: fileName and catalogId (a folder in the account).

Status

Ask for the recording at any time. Read statusLabel, not the numeric status: the labels are the stable contract. When it says transcribed, the text is in the same answer.

curl
curl https://api.transcrify.com/api/v1/files/1300 \
  -H "X-Api-Key: $TRANSCRIFY_KEY"
Response
{
  "id": 1300,
  "fileName": "2026-11-20",
  "statusLabel": "transcribed",
  "duration": 156,
  "language": "en",
  "addDate": "2026-11-20 12:00:00",
  "transcriptionText": "Good morning, let's start. …",
  "summary": null
}
statusLabelMeaning
uploadingWe are still receiving or assembling the file
downloadingWe are fetching it from your URL or from YouTube
processingPreparing the audio
transcribingTranscription in progress
transcribedDone; the text is available
transcription_failedA transcript could not be produced
download_failed, youtube_download_failedWe could not fetch the URL or the video
audio_extraction_failed, upload_failedThe file is not usable media, did not arrive whole, or is longer than the allowance covers

Read the transcript

For the plain text, transcriptionText in the status answer is all you need. For subtitles, speaker-by-speaker notes or a quote with its time, read the timed segments. Long recordings come in pages: follow nextOffset until it is null, or ask for a stretch with from and to in seconds.

curl
curl "https://api.transcrify.com/api/v1/files/1300/transcript?offset=0&limit=200" \
  -H "X-Api-Key: $TRANSCRIFY_KEY"
Response
{
  "speakers": [
    { "label": "SPEAKER_00", "talkTime": 81.5, "segments": 22 },
    { "label": "SPEAKER_01", "talkTime": 63.0, "segments": 19 }
  ],
  "totalSegments": 41, "offset": 0, "limit": 200, "nextOffset": null,
  "segments": [
    { "id": 0, "start": 0.0, "end": 4.2, "text": "Good morning, let's start.", "speaker": "SPEAKER_00" }
  ]
}

speaker is filled in when speakers were recognised for the recording, with anonymous labels in order of first appearance. On plans with summaries, POST /api/v1/files/{id}/summary returns the AI summary and writes it first if there is none yet.

Webhooks

Register an https address once and we call it when something happens to a recording. The answer to the registration contains a secret (whsec_…), shown only then; you need it to check that a call really came from us.

curl
curl -X POST https://api.transcrify.com/api/v1/webhooks \
  -H "X-Api-Key: $TRANSCRIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://hooks.example.com/transcrify",
        "events": ["file.transcription.completed", "file.transcription.failed"]
      }'
EventWhen it fires
file.transcription.completedThe transcript is finished and readable. The one most integrations want.
file.transcription.failedTranscription ran but produced nothing.
file.processing.failedIt failed before transcription: bad media, a download that did not complete, or no allowance for its length.
file.summary.completedThe AI summary is ready (plans with summaries).

What we send

The transcript itself is not in the call, on purpose: bodies stay small and your request logs stay clean. Fetch the text with the fileId when the call arrives.

Webhook request
POST https://hooks.example.com/transcrify
X-Transcrify-Event: file.transcription.completed
X-Transcrify-Delivery: 88412
X-Transcrify-Signature: t=1795000251,v1=5f8c2d…

{
  "event": "file.transcription.completed",
  "occurredAt": "2026-11-20T12:04:11+00:00",
  "data": {
    "fileId": 1300,
    "uid": "url673e1c0a5b2f41.90210",
    "fileName": "2026-11-20",
    "duration": 156,
    "language": "en",
    "status": "transcribed",
    "hasTranscription": true
  }
}

Check the signature

Anyone can post to your address. The signature is an HMAC-SHA256 of the timestamp, a dot and the raw body, made with your secret. Compare it with a timing-safe function and reject calls older than five minutes.

Node.js
import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody: the request body exactly as received, before JSON.parse
function verified(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map(p => p.split('=')))
  const expected = createHmac('sha256', secret).update(parts.t + '.' + rawBody).digest('hex')
  const given = Buffer.from(parts.v1 ?? '')

  const genuine = given.length === expected.length && timingSafeEqual(Buffer.from(expected), given)
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300 // stops replays

  return genuine && fresh
}
  • Answer with any 2xx within 10 seconds and do the real work afterwards. Anything else counts as a failed delivery.
  • A failed delivery is retried up to 6 times with growing pauses. After 20 failures in a row the address is switched off.
  • A call can arrive twice. Use the X-Transcrify-Delivery header to ignore repeats.
  • No-code tools give you such an address ready-made: "Webhooks by Zapier", a Make custom webhook, the n8n Webhook node.

Errors and limits

Every error has the same shape. Branch on code; the message is for people and may be reworded.

Error
{ "error": { "code": "insufficient_permissions", "message": "Not enough permission to upload this file" } }
HTTPCodeMeaning
401invalid_api_keyThe key is wrong, revoked or expired.
402insufficient_permissionsThe account has no transcription time left. Top up; the request itself was fine.
403—The key does not have the scope this call needs.
400invalid_urlNot a public http(s) address, or it has a login embedded.
409transcript_not_readyThe recording is not transcribed yet.
429rate_limitedOver 120 requests a minute for this key. Wait the number of seconds in Retry-After.
One upload request
50 MB; larger files go in chunks or by URL
File fetched from a URL
2 GB
Request rate
120 per minute per key
Webhook answer
within 10 seconds, any 2xx
Webhook retries
6 attempts over roughly two hours
Polling, if you must
every 15 to 30 seconds

Want an AI assistant to use your transcripts instead?

There is no code to write for that. Transcrify has an MCP server that connects Claude, ChatGPT and Cursor to your recordings.

About the MCP server

Build it this afternoon

Four ready programs cover the usual cases: a folder of recordings, a webhook that posts to Slack, a podcast feed and a one-line script.