> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myustadia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Changelog

> Notable changes to the MyUstadia API, newest first

This page tracks notable changes to the public MyUstadia API. The full source-of-truth lives in the FastAPI app and is mirrored to this site automatically.

The OpenAPI spec itself is regenerated on every push to the mahara backend's `main` branch and lands here as a PR titled `docs(api): refresh openapi spec from mahara@<sha>`. Browse the [API Reference](/api-reference/introduction) for current endpoint shapes.

## How to read this page

* **Breaking** entries change request or response shapes in ways that require client updates
* **Added** entries introduce new endpoints, fields, or behaviors
* **Changed** entries adjust behavior or wording without breaking existing clients
* **Fixed** entries are bug fixes that align actual behavior with documented behavior

## Versioning

The current API version is `v1` (path prefix `/api/v1/`). Breaking changes will introduce `/api/v2/` and the old version will remain operational for at least 12 months.

## History

Entries below are added at each notable backend release. The team will append to this page over time.

### 2026-07

#### Breaking

* **`is_unlimited` and `metered_billing_enabled` removed from `GET /api/v1/billing`.** Every account is now always metered; there is no unlimited plan and no enforcement flag. The `quota_seconds` block gains `over_quota` (boolean): `true` when remaining seconds are at or below the start floor, at which point new course launches and preset creation return `429 quota_exceeded` until the quota is raised. Clients reading the removed keys should switch to `over_quota` and `percent_consumed`.

#### Added

* **English questionnaire.** The preset questionnaire and course brief are now fully available in English at parity with French: pass `?language=en` (default `fr`) on the `questions/*` and `brief/*` endpoints. Question prompts, help text, answer option labels, and structured field labels all localize.

### 2026-06 (v2 launch)

#### Added

* **Preset terminology.** Courses are now created under a `preset` (one per client company or visual theme). The preset holds the brand, slide style, voice style, and the company sales-profile questionnaire. Two preset types are supported: `company` (default, full profile) and `theme` (branding only, no questionnaire).

* **Seconds-based billing quota.** `GET /api/v1/billing` returns a `quota_seconds` block with `quota_seconds`, `consumed_seconds`, `remaining_seconds`, `percent_consumed` (0-100), `is_unlimited`, and `metered_billing_enabled`. There is no free tier; all generation consumes from the seconds bucket. See [Billing](/billing).

* **Review checkpoints.** The generation pipeline now exposes fine-grained review gates: `source_review`, `outline_review`, `slide_review`, `audio_review`, `quiz_review`, `module_video_review`, `preset_source_review`, `brand_review`. Each can be set to auto-approve (skip) or left as a manual gate at account level (`PUT /api/v1/account/review-settings`) or per course (`GET /api/v1/courses/{id}/review-settings`). See [Review Checkpoints](/review-checkpoints).

* **Sandbox mode.** `sk_test_` keys enable a no-cost integration environment that returns pre-built demo data without running real generation. Sandbox courses never consume quota. See [Sandbox](/sandbox).

* **`external_ref` idempotency.** Providing the same `external_ref` on a second course-create returns the existing course rather than creating a duplicate.

* **Brief question skip.** Optional (non-blocking) brief questions can be skipped by setting `"skip": true` in the answers payload.

#### Changed

* **Preset `brand/generate` is synchronous.** Unlike `slide-style/generate` and `voice-style/generate` (which return `202` and require polling), `brand/generate` returns the artifact directly in the response. Do not poll `setup-status` after calling `brand/generate`.

* **`slide-style` and `voice-style` are optional.** A preset reaches `ready` on brand alone (plus questionnaire for `company` presets). Slide and voice style generation are refinements, not blockers.

#### Note

`GET /api/v1/courses/{id}/quiz/final` and `POST /api/v1/courses/{id}/quiz/grade-final` exist in the API but are not part of the v1 contract. Their behavior may change before the contract is finalized.