---
title: "A11Y Plain Language"
method: GET
path: "/v1/projects/{project_id}/a11y/plain-language"
tags: ["a11y"]
---

# A11Y Plain Language

`GET /v1/projects/{project_id}/a11y/plain-language`

## Request

- Base URL: `https://api.sonenta.dev`
- URL: `https://api.sonenta.dev/v1/projects/{project_id}/a11y/plain-language`
- Auth: none declared

Plain-language coverage + cognitive load (spec §4.5).

TWO AXES, deliberately not fused into one "remaining" number:
  - COVERAGE: the `plain_language` override per language over the keys whose
    type offers the treatment (text, heading, label, caption).
  - COGNITIVE: `cognitive_score` (0-100, higher = harder) against the project
    `threshold`; `above_threshold` = eligible keys scored at or over it;
    `pending_rewrites` = those that HAVE a suggestion and no source-language
    `plain_language` override yet (the rewrite exists, nobody applied it).
`reading_level_flagged` is a heuristic CANDIDATE count on the source value
(`reading_level_max_words`), not a formal WCAG reading-level test.

CAN vs MUST (task 1830). `eligible` = the key TYPES that CAN carry a rewrite;
only HARD-TO-READ keys NEED one, so eligible is never a backlog denominator.
Three compartments, mutually exclusive, summing EXACTLY to `eligible_keys`:
  - `candidates` (scored >= threshold) — THE primary number, what remains;
  - `scored_readable` — read and judged readable: DONE, nothing to rewrite;
  - `not_scored` — UNKNOWN. Nothing measured these keys yet; never show it as
    work (`unscored_reading_level_flagged` is its "score these first" queue).
`pct_candidates` (= candidates_rewritten / candidates) is the coverage number
to display — NOT `pct`, which spans the whole eligible pool and reads as a
backlog it is not. `measured_candidates=False` means nothing was identified as
hard to read; that is NOT 100% and must not be painted green.
`suggestions_count` is DEPRECATED: it counts keys that merely COULD carry a
rewrite (a potential), not a queue — use `candidates_remaining`.

## Path parameters

- `project_id` string, required

## Query parameters

- `version_id` string, nullable
- `reading_level_max_words` integer

## Response `200`

Successful Response

- A11yPlainLanguageOut
  - `project_uuid` string, required
  - `version_uuid` string, nullable, required
  - `languages` string[], required
  - `source_language` string, nullable, required
  - `eligible_keys` integer, required
  - `eligible_cells` integer, required
  - `present_cells` integer, required
  - `pct` integer, required
  - `measured` boolean, required
  - `by_language` A11yLangRow[], required
    - `code` string, required
    - `eligible` integer, required
    - `present` integer, required
    - `pct` integer, required
    - `is_source` boolean
  - `formula` object, required
  - `surface` string, required
  - `key_types` string[], required
  - `suggestions_count` integer, required
  - `threshold` number, required
  - `above_threshold` integer, required
  - `pending_rewrites` integer, required
  - `analyzed` integer, required
  - `unanalyzed` integer, required
  - `reading_level_max_words` integer, required
  - `reading_level_flagged` integer, required
  - `not_scored` integer
  - `scored_readable` integer
  - `candidates` integer
  - `candidates_rewritten` integer
  - `candidates_remaining` integer
  - `candidates_with_suggestion` integer
  - `pct_candidates` integer
  - `measured_candidates` boolean
  - `candidates_by_language` A11yLangRow[]
    - `code` string, required
    - `eligible` integer, required
    - `present` integer, required
    - `pct` integer, required
    - `is_source` boolean
  - `unscored_reading_level_flagged` integer

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/sonenta/apis/sonenta-api.md) · [All operations](https://skmtc.dev/sonenta/apis/sonenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sonenta/apis/sonenta-api/revisions/f853ea49fb05?raw)