Skip to content

Uploading Recordings

The API upload endpoint is the same one the web app uses. Dropping a file onto the Files tab and POSTing it to /api/files/ run through exactly the same server-side path, so a recording uploaded by a script is transcribed — and, in a call project with automatic analysis, analyzed — exactly as if it had been uploaded by hand. There is nothing API-specific to turn on.

Three resources are involved:

  • File (/api/files/) — the recording or transcript you upload. Once uploaded, transcription starts automatically.
  • Transcript (/api/transcripts/) — the result, with metadata (language, duration, word count) and download links for SRT and DOCX.
  • Task (/api/tasks/) — the background job that did the work (useful for retry).

All endpoints require either a session cookie or an API key — see Authentication. Every request needs the project’s numeric ID; Projects shows how to find it.


Transcription — any project:

  1. POST /api/files/ — upload the recording. The response gives you a file.id, and transcription is enqueued automatically.
  2. Poll GET /api/files/{id}/ until status becomes transcribed (success) or failed.
  3. GET /api/transcripts/?uploaded_file={id} — read the resulting transcript record.
  4. GET /api/transcripts/{id}/download/?type=srt|docx — fetch a time-limited download URL for the file.

Automatic analysis — call projects:

  1. Configure the project once — enable automatic analysis and choose the analysis types. See Call projects: automatic analysis.
  2. POST /api/files/ — upload each recording with its agent, or send a CSV manifest first.
  3. Poll GET /calls/api/analysis-status/?project_id=… until in_progress is false.
  4. Read the results from the Call Reports API.

Steps 2–4 are all you repeat day to day.


Upload a recording or a transcript. Recordings are transcribed automatically when the caller’s subscription has remaining minutes.

Auth: API key or session.

Content-Type: multipart/form-data

Form fields:

FieldRequiredDescription
projectyesID of the project the file belongs to. Must be visible to the caller — see Projects for how to look the ID up.
fileyesThe recording (mp3, wav, m4a, flac, ogg, mp4, …), or an srt / vtt transcript you already have.
file_typeyesaudio for recordings, or srt / vtt for transcripts, which skip transcription. (csv and xlsx are used for survey uploads.)
agent_id, agent_name, agent_emailrecommended in call projectsWho handled the call. With automatic analysis, leaving out all three returns a warning unless a manifest already lists the file. See Call Metadata.
call_datetime, direction, ended_by, caller_number, campaignnoThe rest of the call metadata. Call projects only.

Response (201 Created):

{
"id": 4217,
"project": 312,
"original_filename": "interview.wav",
"file_type": "audio",
"status": "transcribing",
"duration_seconds": 1834.2,
"error_reason": "",
"asr_engine": "",
"uploaded_at": "2026-05-17T14:02:11Z"
}

On call projects with automatic analysis on, the response can also include a warnings list.

Example:

Terminal window
curl -X POST https://app.uspeech.io/api/files/ \
-H "Authorization: Api-Key $USPEECH_KEY" \
-F "project=312" \
-F "file_type=audio" \
-F "file=@./interview.wav"

In call projects, the same request can carry the call’s metadata — the agent, date and time, direction and campaign. Supplying metadata is what makes the report groupable by agent, direction, campaign and date. For bulk loads, send a CSV manifest before the recordings instead of per-file fields: rows are matched to files by name, including files uploaded later.

Example with call metadata:

Terminal window
curl -X POST https://app.uspeech.io/api/files/ \
-H "Authorization: Api-Key $USPEECH_KEY" \
-F "project=312" \
-F "file_type=audio" \
-F "file=@./call_001.mp3" \
-F "call_datetime=2026-06-15T09:12:00Z" \
-F "agent_id=A-06" \
-F "agent_name=Ana Diaz" \
-F "direction=inbound" \
-F "campaign=Retention"

A file uploaded under a name the project already has is treated as the same call — the new record replaces its predecessor rather than adding a second one. This makes retries safe: if a batch upload fails halfway, re-running it will not double-count calls in the report.


Read a single file, including its current status.

Auth: API key or session.

Response (200 OK): same shape as the POST response above.

StatusMeaning
uploadedFile saved, transcription not started — transcripts and other non-audio uploads, or audio uploaded when the subscription had no minutes left.
transcribingTranscription is in progress.
transcribedTranscription completed successfully. A Transcript record now exists.
failedTranscription failed. The error_reason field in this same response tells you why (audio_too_short, hallucinated_transcript, private_transcription_unavailable, or empty for other errors) — see Status Codes & Errors.
analyzing, completedSet when downstream analysis is running or finished (not relevant for the transcription-only flow).
Terminal window
file_id=4217
while :; do
resp=$(curl -sS "https://app.uspeech.io/api/files/${file_id}/" \
-H "Authorization: Api-Key $USPEECH_KEY")
status=$(echo "$resp" | jq -r .status)
echo "$(date -u +%H:%M:%S) status=$status"
case "$status" in
transcribed) break ;;
failed)
echo "failed, reason: $(echo "$resp" | jq -r '.error_reason // "unknown"')"
break ;;
esac
sleep 10
done

In call projects, the file also carries auto_analysis_error, the reason automatic analysis was skipped for it — for example quota_exceeded when the subscription ran out of minutes.


If a file ends up in failed, you can retry it via the Task API.

  1. Find the transcription Task for the file at GET /api/tasks/?task_type=transcription (or follow the link from the web app).
  2. Call POST /api/tasks/{task_id}/retry/ to re-queue it.

Don’t retry on terminal failures like audio_too_short — see Status Codes & Errors for the full list of error_reason values. Retrying is the right move for private_transcription_unavailable and for failures with an empty error_reason.


List transcripts visible to the caller (scoped to projects they can see).

Auth: API key or session.

Response (200 OK): paginated list. Each item:

{
"id": 901,
"uploaded_file": 4217,
"language": "en",
"duration_seconds": 1834.2,
"word_count": 3120,
"srt_path": "tenant/312/results/transcripts/interview.srt",
"docx_path": "tenant/312/results/transcripts/interview.docx",
"status": "completed",
"error_reason": "",
"asr_engine": "external",
"created_at": "2026-05-17T14:05:33Z",
"updated_at": "2026-05-17T14:08:47Z"
}

status here is queued → processing → completed | failed. When status is failed, error_reason holds a machine-readable cause (audio_too_short, hallucinated_transcript, private_transcription_unavailable) or is empty for other errors — see Status Codes & Errors.

asr_engine records which speech recognition service produced the transcript: external (the default provider) or private (USpeech-operated infrastructure, used when the project requires private transcription). It is also returned on the file resource, and stays empty until transcription completes.


Retrieve a single transcript by ID. Same field shape as the list response.

Terminal window
curl https://app.uspeech.io/api/transcripts/901/ \
-H "Authorization: Api-Key $USPEECH_KEY"

If the transcript exists but isn’t visible to the caller, the response is 404 Not Found.


Return a time-limited URL for the transcript artefact (SRT or DOCX). The URL points at private storage — use it from the same machine that received the response.

Auth: API key or session.

Query parameters:

ParamRequiredDescription
typenosrt (default) or docx.

Response (200 OK):

{
"download_url": "https://…/interview.srt?X-Amz-Signature=…"
}

If the requested artefact hasn’t been generated (e.g. the transcript failed), the response is 404 Not Found.

Example:

Terminal window
# Get the URL …
url=$(curl -sS "https://app.uspeech.io/api/transcripts/901/download/?type=srt" \
-H "Authorization: Api-Key $USPEECH_KEY" | jq -r .download_url)
# … then download.
curl -o interview.srt "$url"

When a call project has automatic analysis enabled, every recording is analyzed as soon as it finishes transcribing — no separate “run analysis” call is needed. Uploads work exactly as described above; the sections below cover configuring the project, how calls are batched, and how to follow progress and read the results.

Automatic analysis is configured on the project, via PATCH /api/projects/{id}/. You can do this from the web app’s analysis wizard instead — the settings are the same either way.

Fields:

FieldTypeDescription
auto_analysis_enabledboolMaster switch. Analysis only happens when this is true.
auto_analysis_typeslistWhich analyses to run per call. One or more of calls_analysis_copc, calls_analysis_no_protocol, custom_questions.
auto_analysis_questionslist of stringsThe question set answered per call. Required when custom_questions is enabled.
evaluation_rubricintID of the rubric to score against. Required when calls_analysis_copc is enabled.
auto_analysis_batch_sizeintDispatch a batch once this many calls are waiting. Default 20, allowed range 1–20.
auto_analysis_max_wait_secondsintFlush a partial batch once its oldest waiting call is this old. Default 300.

Validation — the request is rejected with 400 when the configuration would produce unusable runs:

  • The project’s audio_type is not call — automatic analysis is call-projects only.
  • auto_analysis_types is empty.
  • calls_analysis_copc is requested without an evaluation_rubric.
  • custom_questions is requested without any auto_analysis_questions.
  • auto_analysis_batch_size is outside 1–20.

Example — enable per-call analysis with no protocol plus two custom questions:

Terminal window
curl -X PATCH https://app.uspeech.io/api/projects/312/ \
-H "Authorization: Api-Key $USPEECH_KEY" \
-H "Content-Type: application/json" \
-d '{
"auto_analysis_enabled": true,
"auto_analysis_types": ["calls_analysis_no_protocol", "custom_questions"],
"auto_analysis_questions": ["Was a callback offered?", "Was the discount mentioned?"],
"auto_analysis_batch_size": 20,
"auto_analysis_max_wait_seconds": 300
}'

GET /api/projects/{id}/ returns the same fields, so you can check the current configuration before changing it.

Calls are not analyzed one at a time — they are analyzed in small batches, which is why results appear in groups rather than one by one.

A batch for a given analysis type is dispatched when either condition is met:

  • auto_analysis_batch_size calls are waiting — the batch goes immediately.
  • The oldest waiting call reaches auto_analysis_max_wait_seconds — the partial batch is flushed by a sweep that runs every 60 seconds.

So a partial batch is never stranded: with the defaults, a lone call uploaded at the end of the day is analyzed within about five minutes. If you upload in large runs, lower auto_analysis_max_wait_seconds only if you need results sooner than that — smaller batches cost more per call.

Two levels of visibility:

Per file — GET /api/files/{id}/ reports the transcription status (transcribing → transcribed | failed) and an auto_analysis_error field that surfaces the reason automatic analysis was skipped for that file, e.g. quota_exceeded when the subscription ran out of minutes.

Per project — GET /calls/api/analysis-status/?project_id={id} is the endpoint the dashboard itself polls:

{
"analysis_status": {
"calls_analysis_no_protocol": { "completed": 57, "queued": 3 }
},
"analyzed_calls": 57,
"duplicate_uploads": 2,
"in_progress": true,
"reclustering": false,
"last_analyzed_at": "2026-07-29T02:50:11.127124+00:00"
}

Poll it until in_progress is false, then fetch the report. See Call Reports for the full field reference.

Terminal window
while :; do
resp=$(curl -sS "https://app.uspeech.io/calls/api/analysis-status/?project_id=312" \
-H "Authorization: Api-Key $USPEECH_KEY")
in_progress=$(echo "$resp" | jq -r .in_progress)
echo "$(date -u +%H:%M:%S) analyzed=$(echo "$resp" | jq -r .analyzed_calls) in_progress=$in_progress"
[ "$in_progress" = "false" ] && break
sleep 30
done

Once in_progress is false, the analyzed calls are available through the Call Reports API:

  • GET /calls/api/report/?project_id={id} — the aggregated QA report
  • GET /calls/api/calls/?project_id={id} — the per-call explorer
  • GET /calls/api/custom-questions/?project_id={id} — per-call answers to your custom questions
  • GET /calls/api/report/pdf/?project_id={id} — the PDF export

Transcribe a recording and download the SRT

Section titled “Transcribe a recording and download the SRT”
Terminal window
# 1. Upload
resp=$(curl -sS -X POST https://app.uspeech.io/api/files/ \
-H "Authorization: Api-Key $USPEECH_KEY" \
-F "project=312" -F "file_type=audio" \
-F "file=@./interview.wav")
file_id=$(echo "$resp" | jq -r .id)
# 2. Poll
while :; do
resp=$(curl -sS "https://app.uspeech.io/api/files/${file_id}/" \
-H "Authorization: Api-Key $USPEECH_KEY")
status=$(echo "$resp" | jq -r .status)
[ "$status" = "transcribed" ] && break
[ "$status" = "failed" ] && {
echo "transcription failed: $(echo "$resp" | jq -r '.error_reason // "unknown"')"
exit 1
}
sleep 10
done
# 3. Find the transcript and download SRT
transcript_id=$(curl -sS "https://app.uspeech.io/api/transcripts/?uploaded_file=${file_id}" \
-H "Authorization: Api-Key $USPEECH_KEY" | jq -r '.results[0].id')
url=$(curl -sS "https://app.uspeech.io/api/transcripts/${transcript_id}/download/?type=srt" \
-H "Authorization: Api-Key $USPEECH_KEY" | jq -r .download_url)
curl -o interview.srt "$url"

Configure the project, send the call metadata, upload a folder of recordings, wait for analysis, and fetch the report.

The metadata step comes first because automatic analysis needs each call’s agent as soon as the call arrives. There are two ways to supply it, and you can mix them freely:

  • Per file at upload, as extra form fields on POST /api/files/ — best when your system already knows the details of each call as it uploads it. This is what the call metadata example above shows.
  • Per project, as a CSV manifest on POST /api/projects/{id}/call-manifest/ — best for bulk loads. Rows are matched to files by name, and rows that don’t match anything yet are kept and applied to files uploaded later. Send it before the recordings, with an agent in every row.

The example below uses the manifest, since it suits uploading a whole folder at once. See Call Metadata for the full field reference, the accepted date formats, and how to correct metadata after the fact.

#!/usr/bin/env bash
set -euo pipefail
BASE_URL="https://app.uspeech.io"
AUTH="Authorization: Api-Key ${USPEECH_KEY}"
project_id=312
# 1. Enable automatic analysis
curl -sS -X PATCH "${BASE_URL}/api/projects/${project_id}/" \
-H "$AUTH" -H "Content-Type: application/json" \
-d '{"auto_analysis_enabled": true, "auto_analysis_types": ["calls_analysis_no_protocol"]}' \
> /dev/null
# 2. Send the call metadata for the whole batch first, so each upload finds its agent.
# calls_june.csv: filename,call_datetime,agent_id,agent_name,direction,campaign
curl -sS -X POST "${BASE_URL}/api/projects/${project_id}/call-manifest/" \
-H "$AUTH" -F "file=@./calls_june.csv" \
| jq -r '"\(.matched) matched, \(.unmatched | length) waiting for their file"'
# 3. Upload every recording in ./calls/
for path in ./calls/*.mp3; do
curl -sS -X POST "${BASE_URL}/api/files/" \
-H "$AUTH" \
-F "project=${project_id}" \
-F "file_type=audio" \
-F "file=@${path}" \
| jq -r '"uploaded \(.original_filename) -> \(.id)", (.warnings[]? | "warning: \(.code): \(.detail)")'
done
# 4. Wait for analysis to settle
while :; do
resp=$(curl -sS "${BASE_URL}/calls/api/analysis-status/?project_id=${project_id}" -H "$AUTH")
[ "$(echo "$resp" | jq -r .in_progress)" = "false" ] && break
sleep 30
done
# 5. Fetch the report
curl -sS "${BASE_URL}/calls/api/report/?project_id=${project_id}" -H "$AUTH" > report.json
echo "report written to report.json"

SymptomLikely cause
A file stays uploadedTranscription did not start, usually because the subscription had no minutes left at upload time.
A file ends up failederror_reason says why. Retry only when it is empty or private_transcription_unavailable — see Retrying a failed transcription.
File reaches transcribed but nothing is ever analyzedauto_analysis_enabled is false, or auto_analysis_types is empty. Check GET /api/projects/{id}/.
auto_analysis_error is quota_exceededThe subscription ran out of minutes. Analysis is skipped, not retried automatically.
The upload response has a warnings entry with code call_metadata_missingAutomatic analysis is on and the upload has no agent, so the report shows a guessed name. Send agent_id, agent_name or agent_email, or upload a manifest listing the file.
400 on the upload with a metadata field in the bodyThe project is not a call project, or file_type is not audio/srt/vtt.
400 when enabling automatic analysisA rubric is missing for COPC, questions are missing for custom_questions, or the batch size is outside 1–20.
Report call count is lower than the number of files uploadedRe-uploaded filenames replace the earlier call. duplicate_uploads in the analysis-status response counts them.
unanalyzed_calls in the report is above 0Those calls were transcribed while automatic analysis was off; enabling it does not reach back to them. Analyze them once with a manual analysis.

See Status Codes & Errors for the full list of response codes.