Reference

Generated from components.schemas and components.headers. Descriptions are the schema text.

Operations

GET /health getHealth Ready check
POST /v1/tutor scoreTutor Score a Koine word or short verse
POST /mcp callMcp MCP Streamable HTTP (JSON, not SSE)
PUT /v1/uploads/{id} putUpload Store one WAV on the create_upload slot
GET /v1/uploads/{id} getUpload Read a stored WAV

Examples

Name	Target	IPA	proximity	real_edits
`exactLogos`	λόγος	`l o g o s`	1.0	0
`stressShift`	λόγος	`l o g ˈo s`	0.9	0
`thetaAsS`	θεός	`s e o s`	0.75	1
`acceptableTheta`	θεός	`tʰ e o s`	0.988187	0
`verseArche`	ἐν ἀρχῇ	`e n a r x i`	1.0	0

Full responses are the matching examples on POST /v1/tutor in openapi.json.

TutorRequest

Field	Type	Required	Description
`target`	string	yes	Greek word or short verse.
`ipa`	string / array of string		Learner phones. A string is tokenized. Explicit ipa wins over audio_base64 and audio_url.
`audio_base64`	string		WAV bytes, base64. At most 256 KiB decoded. Larger clips use create_upload and audio_url. Resampled to 16 kHz mono. Under 0.12 s is unscored.
`audio_url`	string		audio_url from the MCP tool create_upload, or an https URL. An upload id is read from this process. Other URLs must be https. The worker rejects userinfo, IP literals that are private, loopback, link-local, or otherwise non-public, and names such as localhost. It follows at most 3 redirects and checks each hop the same way. The body is read until 256 KiB, the same cap as audio_base64, then aborted. Content-Type must be audio/wav, audio/x-wav, audio/wave, or audio/vnd.wave. Failures are problem+json with a stable `code` (`audio-url-not-https`, `audio-url-host`, `audio-url-redirects`, `audio-url-too-large`, `audio-url-type`, `audio-url-timeout`).
`scheme`	string
`different_word`	boolean
`calibrate`	boolean
`thresholds`	object		Map of name to minimum, or a list of minimums.
`posteriors`	array of array of number		CTC frame log-probabilities. With vocab, each target phone gets a confidence.
`vocab`	array of string
`blank_id`	integer
`recognizer`	string

TutorResponse

Field	Type	Required	Description
`api`	enum	yes
`scheme`	string	yes
`target_text`	string
`target_words`	array of object
`observed_phones`	array of string
`proximity`	number	yes	Calibrated score after the stress penalty. Unchanged by coaching and heard_as.
`lenient_similarity`	number
`strict_similarity`	number
`real_edits`	integer	yes	Count of phones whose scoring status is incorrect, missing, or extra.
`phones`	array of `ScoredPhone`	yes
`different_word`	`DifferentWord`
`stress`	object	yes	Scoring stress object. The penalty is already inside proximity.
`gop`	object		Present when the request carried posteriors.
`thresholds`	array of object
`coaching`	`Coaching`	yes
`heard_as`	`HeardAs`	yes
`input_quality`	object		Present when the request carried audio. Measured before resampling. Does not change proximity. Absent on IPA examples.

ScoredPhone

Field	Type	Required	Description
`target`	string or null
`observed`	string or null
`status`	enum	yes	Scoring label. This is what real_edits counts. It is not the learner label.
`cost`	number	yes
`confidence`	number or null		Calibrated GOP confidence. Null when the request has no posteriors.
`uncertain`	boolean		True when confidence is below 0.75 or alignment failed.

Coaching

Field	Type	Required
`summary`	`CoachingSummary`	yes
`sounds`	array of `CoachingSound`	yes
`stress`	`CoachingStress`	yes

CoachingSummary

Field	Type	Required	Description
`proximity`	number	yes	Same rounded value as the response proximity.
`fixes`	array of `CoachingFix`	yes	Repairs with score_gain above 0, at most three. Ranked by score_gain descending, then a sound fix before a stress fix, then sound_index.

CoachingFix

Field	Type	Required	Description
`rank`	integer	yes
`kind`	enum	yes
`sound_index`	integer		Present when kind is sound. Index into coaching.sounds and phones.
`word`	string or null
`letters`	string or null
`target`	string or null
`heard`	string or null
`status`	`LearnerStatus`
`target_syllable`	integer or null		Present when kind is stress.
`detected_syllable`	integer or null
`target_letters`	string or null		Greek letters of the target syllable. Present when kind is stress.
`detected_letters`	string or null
`error_code`	string	yes	Same code as the sound, or stress_shift.
`score_gain`	number	yes	Proximity restored by fixing this one sound, or by clearing the stress penalty.

CoachingSound

Field	Type	Required	Description
`index`	integer	yes
`word`	string or null
`letters`	string or null		Greek letters that produced the target phone. Accents stay. Null on an extra.
`syllable`	integer or null		Syllable index inside the word. The stress object uses the verse-level index.
`target`	string or null		Lexicon phone, IPA.
`heard`	string or null		Aligned attempt phone, IPA. Null when the target phone is missing.
`status`	`LearnerStatus`	yes
`closeness`	number	yes	Articulatory closeness. Exact is 1. Missing and extra are 0. Vowels: 1 - min(1, height/6 + 0.5·backness/2 + 0.5·	rounding	). Consonants: 1 - min(1, place/8 + 0.5·manner/7 + 0.5·	voice	). A vowel against a consonant is 0. Length alone is 0.9. Aspiration alone is 0.85. Rounded to 6 decimal places. Low confidence does not change this number.
`low_confidence`	boolean	yes	True when the aligned phone row has uncertain true, or confidence is a number below 0.75. An IPA-only phone with null confidence is false. When this is true and the feature label would be far, status is close. The error code and the feature diff stay on the phones. An exact phone stays exact.
`error_code`	string or null	yes	Stable code for this phone difference. Null when status is exact. A consonant substitution names place and manner. Fricatives s, z, ʃ, and ʒ use sibilant in the code, so θ→s is dental_fricative_to_alveolar_sibilant. Voice, aspiration, and length words appear only when that feature differs. A vowel substitution names height, backness, and rounding on both sides. Missing and extra prefix the same token. Low confidence does not change the code.
`feature_diff`	array of `FeatureDiff`	yes	Features that differ, in order: kind, place, manner, voicing, aspiration, rounding, height, backness, length. Empty when status is exact.

FeatureDiff

Field	Type	Required	Description
`feature`	enum	yes
`target`	string or null	yes	Label on the lexicon phone. Null on an extra, or when that side has no such feature.
`heard`	string or null	yes	Label on the attempt phone. Null when the target phone is missing.

CoachingStress

Field	Type	Required	Description
`target_syllable`	integer or null	yes	Accented syllable, same index as stress.target_syllable.
`detected_syllable`	integer or null	yes	Attempt syllable, same index as stress.attempt_syllable.
`match`	boolean or null	yes	Null when stress abstains or the attempt has no accent mark.
`target_letters`	string or null	yes	Greek letters of the target syllable, accents kept. Null when the index is null.
`detected_letters`	string or null	yes	Greek letters of the detected syllable. Null when the index is null.
`error_code`	string or null	yes	stress_shift when match is false. Null when match is true or null.

LearnerStatus

exact matches scoring status correct. acceptable_variant matches scoring status "acceptable variant" (the 0.02 taught-versus-historical pairs). close is scoring status acceptable, or an incorrect substitution whose closeness is at least 0.5, or a far substitution whose low_confidence flag is true. far is an incorrect substitution whose closeness is below 0.5 and whose confidence is not low. missing and extra match those scoring statuses.

Enum: exact, acceptable_variant, close, far, missing, extra

HeardAs

Field	Type	Required	Description
`scheme`	string	yes	The request scheme. Koine is the product path. The letter table also covers attic-greek, classical-latin, ecclesiastical-latin, living-koine, and lucian. The worker scores koine-greek.
`script`	enum	yes
`method`	enum	yes	posterior when at least one candidate received a CTC forward score from the request posteriors. distance-softmax otherwise. Both paths order candidates with the same softmax. Published confidence is the Platt map, not that mass.
`temperature`	number	yes	Softmax temperature used to order candidates. The shipped value is 0.1. Published confidence is a separate Platt map of the top-1 gap, the normalized tutor cost, and a non-word indicator.
`other_score`	number	yes	Rank score of the other bin before the softmax. The shipped value is 0.5.
`truncated`	boolean	yes	True when the one-edit neighborhood was capped at 1500 lexicon rows.
`candidates`	array of `HeardAsCandidate`	yes	Whole-string ranking. For one word this is that word's list. For a verse it is the spelling of the whole clause; read `words` for a lexicon hit on each target word.
`words`	array of `HeardAsWord`	yes	One ranking per target word, sliced by the tutor alignment.

HeardAsWord

Field	Type	Required	Description
`word`	string	yes
`lemma`	string	yes
`target_phones`	array of string	yes
`observed_phones`	array of string	yes	Heard phones aligned to this target word.
`truncated`	boolean	yes
`candidates`	array of `HeardAsCandidate`	yes

HeardAsCandidate

Field	Type	Required	Description
`rank`	integer	yes
`kind`	enum	yes
`is_word`	boolean	yes	True only for a lexicon row.
`word`	string or null		Lexicon orthography, or the generated spelling. Null for other.
`lemma`	string or null
`greek`	string or null		Greek spelling. The lexicon form for a word, the generated letters for a non-word. Null for Latin schemes and for other.
`latin`	string or null		ASCII transliteration of the candidate phones. Null for other.
`ipa`	string or null
`phones`	array or null
`similarity`	number or null		Guesser similarity of the candidate phones to the heard phones. A transliteration is one cheap edit below a perfect match (1 - 0.25/n - 0.01), not 1. Null for other.
`score`	number		Value that entered the softmax, before truncation of the confidence.
`ctc_log_prob`	number or null		CTC forward log-probability when method is posterior and this candidate was scored. Null otherwise.
`confidence`	number	yes	Platt confidence of the top row, truncated to 6 decimals. Later rows keep softmax proportions scaled to stay below it. The list sums to at most 1.

Problem

RFC 9457 problem details. type is a section of the errors guide. detail is the same sentence earlier plain-text errors used.

Field	Type	Required	Description
`type`	string	yes	Problem type. A section of /docs/errors.
`title`	string	yes	Short HTTP reason.
`status`	integer	yes	HTTP status code.
`detail`	string	yes	One sentence. No pronunciation advice.
`instance`	string		Request path.
`code`	string		Stable token on rate-limit, body-size, upload-slot, and audio_url failures. Examples include `rate-limit-exceeded`, `body-too-large`, `upload-slots-full`, `audio-url-host`.

UnscoredResponse

HTTP 200 when the trimmed audio is under 0.12 s. proximity is null. This is not a problem document.

Field	Type	Required	Description
`api`	`tutor-v1`	yes
`scheme`	string	yes
`target_text`	string	yes
`proximity`	null	yes
`unscored`	`too_short`	yes
`duration_s`	number	yes	Trimmed duration in seconds, 6 decimal places.
`input_quality`	object		Present on audio responses. Does not change proximity. Absent on IPA responses.

DifferentWord

Closest one-edit lexicon neighbor. detected does not change proximity. different_word: false on the request returns checked false and skips the search. A verse returns reason single-word targets only.

Field	Type	Required	Description
`checked`	boolean	yes
`detected`	boolean	yes
`reason`	string		Present when a verse skips the check.
`word`	string
`lemma`	string
`similarity`	number

JsonRpcRequest

Field	Type	Required	Description
`jsonrpc`	`2.0`	yes
`id`	string / integer / null		String or number. Omit for a notification.
`method`	string	yes
`params`	object

JsonRpcResponse

Field	Type	Required
`jsonrpc`	`2.0`	yes
`id`	string / integer / null
`result`	object
`error`	object

Headers

RateLimitPolicy

draft-ietf-httpapi-ratelimit-headers. Anonymous is "tutor";q=10;w=60. A key is "tutor";q=120;w=60. The Workers bindings TUTOR and TUTOR_KEY are authoritative when present. The in-memory window is the fallback.

RateLimit

Remaining requests r and whole seconds t until the oldest counted request leaves the window.

RetryAfter

Seconds to wait. Same value as RateLimit t, sent on 429.