Search by a spoken request

POST /v1/voice-search

Takes a spoken request of up to 30 seconds and 10 MB as the request body, with its type, and returns what was heard and the same results as a search. The audio is not kept.

When nothing could be heard, the response holds an empty transcript and no results.

Billed per second of audio, at least one second. Limited to 60 a minute per key.

Authentication

Send Authorization: Bearer $KEY from your server. Create or rotate keys.

Example request

bash
curl 'https://play.fellowverse.app/v1/voice-search?limit=5' \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: audio/webm' \
  --data-binary @request.webm

Example IDs are placeholders. Use the upload or job ID returned by your own request.

Parameters

Name In Required Type Description and constraints
limit query No integer How many passages to return. Default: 20. Minimum: 1. Maximum: 50.

Request body

The recording itself as the body, with its type in Content-Type. MP3, WAV, M4A, OGG, WebM and FLAC are read.

Accepted content types: audio/mpeg, audio/mp3, audio/wav, audio/x-wav, audio/wave, audio/webm, audio/ogg, audio/mp4, audio/x-m4a, audio/aac, audio/flac, application/octet-stream.

Send the raw audio bytes as the entire request body, with the matching Content-Type. Do not wrap the recording in multipart form data or JSON.

Responses

Status Meaning
200 What was heard, and the passages found for it.
400 The request could not be used. invalid_request when a field is missing or has the wrong type; bad_request when the audio or a value could not be read.
401 The key is missing, wrong, revoked, or past the end of its grace period after a roll. The code is api_unauthorized, and the reason says which.
403 The account is suspended (api_suspended), or a live key was used on an account that has test keys only (api_live_locked).
413 The body is over the limit: 200 MB for an upload, 10 MB for voice search. The code is request_error.
415 The Content-Type is not one of the audio types read. The code is request_error.
429 A per-key limit for the minute was reached (api_rate_limited; the reason names the limit), or a test key used up its account's daily allowance (api_test_quota; the fix says when it resets).
500 Something went wrong on our side. The code is internal.
503 Voice search cannot be served right now; typed search keeps working. The code is api_stt_off.

200: application/json

Field Type Required Description and constraints
transcript string Yes What was heard. Empty when nothing was, and then there are no results.
kind string No reference when the query named a passage, search otherwise. One of search, reference.
title string No For a reference, the chapter it names, such as "Psalm 23". Absent for a search.
method string No How a search was matched: rrf blends meaning and wording, text is wording only. Absent for a reference. One of rrf, text, vector.
degraded string No Present when a search fell back to wording only, saying why.
results object[] Yes
results[].id string Yes A stable id for the passage.
results[].reference string Yes
results[].book string Yes The book's name in English.
results[].chapter integer Yes Minimum: 1.
results[].firstVerse integer Yes Minimum: 1.
results[].lastVerse integer Yes Minimum: 1.
results[].heroVerse integer Yes The verse that carries the passage, for a short quote. Minimum: 1.
results[].contextLine string Yes Where the passage sits and who is speaking.
results[].verses object[] Yes
results[].verses[].verse integer Yes Minimum: 1.
results[].verses[].text string Yes
results[].reason string Yes Why this passage was returned.
translation string No Always World English Bible (public domain).

“Required” is relative to the containing object. Optional success results and failure errors depend on the job state.

Errors and limits

JSON errors contain error.code, error.problem, error.reason and error.fix. Handle errors and retries and check test and live limits.

Need the contract? Download OpenAPI. Manage keys and account access in the developer console.

Start here · Guides · API reference