API Reference

API Reference

Start the server with make serve (default http://127.0.0.1:8000). CORS is open for local dashboard development. Interactive docs are served at /docs.

Method	Path	Description
GET	/health	{status, engine_version, schema_version, config_hash}
GET	/references	List of {id, title, transcript, provenance, license, recording_type}
GET	/rubric	{rubric_version, rules, limitations} for tooltips and help text
POST	/analyze	Analyze one recording

POST /analyze

Multipart form fields:

Field	Type	Notes
audio	file	WAV, MP3, M4A and other formats ffmpeg can decode; 2 s to 600 s
reference_id	text	An id from /references
transcript	text	Must contain the same words as the reference text

curl -X POST http://127.0.0.1:8000/analyze \
  -F audio=@my_speech.wav -F reference_id=gettysburg -F "transcript=$(cat transcript.txt)"

Responses

Code	Meaning
200	Body is a result with status = ok or insufficient_evidence (see Result Schema)
404	unknown_reference
422	Invalid input; body has messages[] with code and human-readable text

Message codes

Level	Codes
error	file_not_found, unsupported_audio, corrupt_audio, sample_rate_too_low, audio_too_short, audio_too_long, silent_audio, transcript_too_short, transcript_too_long, transcript_mismatch, alignment_failed, reference_alignment_failed, transcript_audio_mismatch_suspected, low_snr (returns insufficient_evidence)
warning	noisy_audio, clipping, pitch_insufficient
info	approximate_alignment

The dashboard should always display warnings and the approximate_alignment notice, and must never show scores when status is insufficient_evidence.