What the ArticScore API returns

ArticScore takes a recording plus the word a child was asked to say, and returns one row per sound: a score from 0 to 100, the phoneme in ARPAbet and IPA, the millisecond span it occupied, the engine's best candidate for what was produced instead, a clinical error type, and a confidence tier. This page documents every field.

The request

One endpoint, one multipart POST. You do not send phonemes — the API derives the expected phoneme sequence from the target text and aligns it against the audio itself.

POST /articscore/v1/score
Authorization: Bearer <your key>
Content-Type: multipart/form-data

audio    = <file>        # the recording
text     = "rabbit"      # the word or phrase the child was asked to say
dialect  = "en-us"       # optional; en-us is the evaluated default

The response

A child saying “rabbit” as “wabbit”. The second phoneme is truncated for length; a real response contains a row for every sound in the word.

{
  "engine": "articscore",
  "model": "ft-epoch3",
  "text": "rabbit",
  "overall_score": 61.4,
  "words": [
    {
      "word": "rabbit",
      "score": 61.4,
      "phonemes": [
        {
          "phone": "R",
          "phone_ipa": "ɹ",
          "score": 41.2,
          "sound_most_like": "W",
          "sound_most_like_ipa": "w",
          "extent": [120, 260],
          "flagged": true,
          "error_type": "substitution",
          "tier": "flag"
        },
        {
          "phone": "AE",
          "phone_ipa": "æ",
          "score": 88.1,
          "sound_most_like": null,
          "sound_most_like_ipa": null,
          "extent": [260, 390],
          "flagged": false,
          "error_type": null,
          "tier": "clean"
        }
      ]
    }
  ],
  "timing": { "inference_s": 1.12, "total_s": 1.31 }
}

Top-level fields

Phoneme fields

This is the part of the response that distinguishes a scoring API from an explanation API. The three fields to pay attention to are sound_most_like, error_type, and tier.

The three confidence tiers

Rather than making every integrator pick their own score threshold and get it slightly wrong, the API collapses its signals into three tiers that map onto the three decisions a product actually makes.

Error types

The error_type field uses the vocabulary a clinical note is written in, because that is what makes the output useful to a therapist rather than only to a scoring loop.

Building on the output

Three patterns cover most of what teams actually do with this response.

Immediate practice feedback

Branch on tier === "flag" and use sound_most_liketo phrase the feedback concretely — “the R in rabbit came out as a W” instead of “try again”. Use extent to replay just that fragment. Keep review silent in a child-facing loop: at these precision levels an uncertain flag shown to a child is usually wrong, and being told you are wrong when you were right is the fastest way to lose a young user.

A clinician worklist

Rank recordings by score rather than thresholding them. In our clinical evaluation, reviewing only the worst-ranked productions recovered a disproportionate share of the clinician's error list — far more than reviewing the same number at random would have. That is, in our view, the highest-value thing you can build on this API today.

A rendering of all three

The ArticScore overview shows this exact response rendered three ways — a child-facing game screen, a practice summary, and a clinician's review row — so you can see which fields carry which part of each experience.

Progress tracking over time

Aggregate per-phoneme scores by sound and by word position across sessions. Because the API scores every phone in context, you can show that a child's initial /s/ improved while their /s/ in clusters did not — which is the shape of information an IEP goal is written in. Log the model field alongside the scores so a checkpoint change does not appear in your charts as clinical progress.