{
  "openapi": "3.1.0",
  "info": {
    "title": "Axad REST API",
    "version": "1.0.0",
    "summary": "The learner's lessons, flash cards, speech and account, over HTTPS and JSON.",
    "description": "Axad is an AI language tutor. This is the REST API behind its Mac app and its MCP server (https://mcp.axad.ai/mcp), for a client that acts for one learner.\n\n**Auth.** OAuth 2.1 authorization code with PKCE (S256), for public clients, scope `axad`. Register a client with `POST /oauth/register`, or use a Client ID Metadata Document as the `client_id`. Send the access token as `Authorization: Bearer <token>`. An access token lives 1 hour; a refresh token 60 days, once. Every call acts for the learner who signed in.\n\n**Credit.** Amounts are micro-dollars (USD × 10⁶). Only Axad's own paid calls spend credit: speech and new drawings. Cards and active lessons are capped by the plan; a call past a cap answers 402 `LimitReached`, and nothing is deleted.\n\n**Errors.** A body of `{\"error\", \"detail\"}`. 429 `too many` / `email_tries` / `gift_tries`: slow down; the limits are per address, network or account and hour. Ids are strings with a prefix that names the kind.\n\n`x-access` on an operation is `read`, `write` or `sensitive` (deletes the learner's data, or starts a payment).",
    "contact": {
      "name": "Axad",
      "email": "support@axad.ai",
      "url": "https://axad.ai/developers"
    },
    "termsOfService": "https://axad.ai/terms"
  },
  "externalDocs": {
    "description": "Axad for developers",
    "url": "https://axad.ai/developers"
  },
  "servers": [
    {
      "url": "https://api.axad.ai/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "oauth2": [
        "axad"
      ]
    }
  ],
  "tags": [
    {
      "name": "Profile",
      "description": "The learner's languages, levels and settings."
    },
    {
      "name": "Lessons and materials",
      "description": "The learner's own lessons, texts and exams."
    },
    {
      "name": "Library",
      "description": "Axad's library of lessons and practice exams."
    },
    {
      "name": "Runbooks",
      "description": "Step-by-step courses of action and the learner's place in them."
    },
    {
      "name": "Cards",
      "description": "Flash cards and their spaced-repetition reviews."
    },
    {
      "name": "Speech and pictures",
      "description": "Speech, and the shared library of pictures."
    },
    {
      "name": "Account and billing",
      "description": "The account, its plan and credit."
    },
    {
      "name": "OAuth",
      "description": "Sign-in for clients: registration, tokens and revocation."
    }
  ],
  "paths": {
    "/profile": {
      "get": {
        "operationId": "getProfile",
        "tags": [
          "Profile"
        ],
        "summary": "The learner's profile: their languages and levels",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Profile"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      },
      "put": {
        "operationId": "putProfile",
        "tags": [
          "Profile"
        ],
        "summary": "Replace the learner's profile",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Profile"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Profile"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/settings": {
      "get": {
        "operationId": "getSettings",
        "tags": [
          "Profile"
        ],
        "summary": "The learner's settings",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Settings"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      },
      "put": {
        "operationId": "putSettings",
        "tags": [
          "Profile"
        ],
        "summary": "Replace the learner's settings",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Settings"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Settings"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/materials": {
      "get": {
        "operationId": "listMaterials",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "The learner's library: their lessons, texts and exams",
        "parameters": [
          {
            "name": "exams",
            "in": "query",
            "required": false,
            "description": "1: include materials of kind \"exam\".",
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "true"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Library"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      },
      "post": {
        "operationId": "createMaterial",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "Add a text, web page or file as a material",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MaterialNew"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Material"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "402": {
            "description": "The plan's limit is reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LimitReached"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/materials/{id}": {
      "get": {
        "operationId": "getMaterial",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "One material with its passages, questions and chats",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Material"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      },
      "patch": {
        "operationId": "patchMaterial",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "Rename or change a material",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MaterialPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Material"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      },
      "delete": {
        "operationId": "deleteMaterial",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "Delete a material",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Done; no body."
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "sensitive"
      }
    },
    "/materials/{id}/page": {
      "put": {
        "operationId": "putMaterialPage",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "Set the page the learner is on",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PageAt"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Done; no body."
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/materials/{id}/close": {
      "post": {
        "operationId": "closeLesson",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "Close a lesson: it keeps its place and cards and frees an active-lesson slot",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MaterialSummary"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/materials/{id}/open": {
      "post": {
        "operationId": "openLesson",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "Reopen a closed lesson",
        "description": "402 `LimitReached` when the plan's active lessons are full.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MaterialSummary"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "402": {
            "description": "The plan's limit is reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LimitReached"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/materials/{id}/sentences": {
      "get": {
        "operationId": "readSentences",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "Sentences of a material, numbered from 1 across its passages (at most 40)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "First sentence number, at least 1.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "Last sentence number, at least `from`.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "only",
            "in": "query",
            "required": false,
            "description": "`untouched`: only the sentences the learner has not asked about.",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "untouched"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SentencesRead"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      }
    },
    "/materials/{id}/handin": {
      "post": {
        "operationId": "handInExam",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "Hand in the answers of an exam",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HandIn"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Material"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/materials/{id}/passages/{passage}/transcript": {
      "post": {
        "operationId": "transcribePassage",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "The words of one recorded fragment of an exam passage, as speech to text heard them",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "passage",
            "in": "path",
            "required": true,
            "description": "The passage's id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "media",
            "in": "query",
            "required": true,
            "description": "Index into the passage's `media`.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "The recording.",
          "content": {
            "audio/*": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Passage"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/exams": {
      "post": {
        "operationId": "createExam",
        "tags": [
          "Lessons and materials"
        ],
        "summary": "Create an exam material from cases and questions",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExamNew"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Material"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/catalog": {
      "get": {
        "operationId": "browseCatalog",
        "tags": [
          "Library"
        ],
        "summary": "Axad's library of lessons and practice exams",
        "description": "Without `lang`, the languages Axad teaches; with it, that language's sections and lessons.",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "BCP 47 code of the language to browse.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      }
    },
    "/catalog/{id}": {
      "post": {
        "operationId": "addCatalogLesson",
        "tags": [
          "Library"
        ],
        "summary": "Add a lesson of the library to the learner's own",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Material"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "402": {
            "description": "The plan's limit is reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LimitReached"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/runbooks": {
      "get": {
        "operationId": "listRunbooks",
        "tags": [
          "Runbooks"
        ],
        "summary": "Axad's runbooks: step-by-step courses of action, with the learner's place in each",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "BCP 47 code of the language of the runbooks.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunbookList"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      }
    },
    "/runbooks/{id}/start": {
      "post": {
        "operationId": "startRunbook",
        "tags": [
          "Runbooks"
        ],
        "summary": "Start a runbook",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunbookStart"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunbookPlace"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/runbooks/{id}/record": {
      "post": {
        "operationId": "recordRunbookStep",
        "tags": [
          "Runbooks"
        ],
        "summary": "Record the outcome of the current step",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunbookRecord"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunbookPlace"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/cards": {
      "get": {
        "operationId": "listCards",
        "tags": [
          "Cards"
        ],
        "summary": "The learner's flash cards, filtered, with the bag's counts",
        "parameters": [
          {
            "name": "due",
            "in": "query",
            "required": false,
            "description": "1: only the cards due for review.",
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "true"
              ]
            }
          },
          {
            "name": "hard",
            "in": "query",
            "required": false,
            "description": "1: only the cards the learner finds hard.",
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "true"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Text to search in the cards.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "material",
            "in": "query",
            "required": false,
            "description": "Only the cards of this material.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "BCP 47 code of the language of the cards.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bag"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      }
    },
    "/cards/{id}": {
      "get": {
        "operationId": "getCard",
        "tags": [
          "Cards"
        ],
        "summary": "One card with its examples and review history",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardDetail"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      },
      "delete": {
        "operationId": "deleteCard",
        "tags": [
          "Cards"
        ],
        "summary": "Delete a card",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Done; no body."
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "sensitive"
      }
    },
    "/cards/{id}/review": {
      "post": {
        "operationId": "reviewCard",
        "tags": [
          "Cards"
        ],
        "summary": "Record a review of a card; its next due date follows",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReviewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReviewResponse"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/speech": {
      "post": {
        "operationId": "speak",
        "tags": [
          "Speech and pictures"
        ],
        "summary": "Speech for a text, with each word's time",
        "description": "Spends the account's credit; 402 `AllowanceSpent` when there is none.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpeechRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpeechResponse"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "402": {
            "description": "The account's credit is spent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AllowanceSpent"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/audio/{hash}": {
      "get": {
        "operationId": "getAudio",
        "tags": [
          "Speech and pictures"
        ],
        "summary": "A recording that `POST /speech` made",
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "required": true,
            "description": "The recording's hash, from `audio_url`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file.",
            "content": {
              "audio/mpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      }
    },
    "/images": {
      "get": {
        "operationId": "findImages",
        "tags": [
          "Speech and pictures"
        ],
        "summary": "Pictures of the shared library that show a concept",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The concept to find: \"apple\", \"doctor's practice\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": true,
            "description": "BCP 47 code of the language of the learner.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImageMatches"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      },
      "post": {
        "operationId": "nominateImage",
        "tags": [
          "Speech and pictures"
        ],
        "summary": "Nominate a picture for a concept; a new drawing spends credit",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImageNomination"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NominationResult"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "402": {
            "description": "The account's credit is spent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AllowanceSpent"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/images/{id}": {
      "get": {
        "operationId": "getImage",
        "tags": [
          "Speech and pictures"
        ],
        "summary": "One picture of the library",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The id: a prefix that says the kind, then a ULID (\"m_12\", \"c_41\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Image"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      }
    },
    "/image-files/{file}": {
      "get": {
        "operationId": "getImageFile",
        "tags": [
          "Speech and pictures"
        ],
        "summary": "A picture's file (`<sha256>.webp`)",
        "parameters": [
          {
            "name": "file",
            "in": "path",
            "required": true,
            "description": "The file's name, `<sha256>.webp`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file.",
            "content": {
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      }
    },
    "/account": {
      "get": {
        "operationId": "getAccount",
        "tags": [
          "Account and billing"
        ],
        "summary": "The account: plan, limits, use and credit",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountUsage"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "read"
      },
      "delete": {
        "operationId": "deleteAccount",
        "tags": [
          "Account and billing"
        ],
        "summary": "Delete the account and every row of it",
        "responses": {
          "204": {
            "description": "Done; no body."
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "sensitive"
      }
    },
    "/billing/checkout": {
      "post": {
        "operationId": "startCheckout",
        "tags": [
          "Account and billing"
        ],
        "summary": "A Stripe Checkout page URL to save a card, subscribe to a plan or buy credit",
        "description": "A link for the learner to open; Axad takes no card data over the API. 503 while the server takes no payments.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutResponse"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "sensitive"
      }
    },
    "/billing/portal": {
      "post": {
        "operationId": "openBillingPortal",
        "tags": [
          "Account and billing"
        ],
        "summary": "Stripe's page to change or cancel the plan",
        "description": "409 without a Stripe plan.",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortalResponse"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "sensitive"
      }
    },
    "/billing/redeem": {
      "post": {
        "operationId": "redeemGift",
        "tags": [
          "Account and billing"
        ],
        "summary": "Redeem a gift code for credit",
        "description": "429 `gift_tries` after too many wrong codes in an hour.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GiftRedeem"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GiftRedeemed"
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is expired or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "An error: `error` names it, `detail` says more.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "x-access": "write"
      }
    },
    "/oauth/register": {
      "post": {
        "operationId": "registerClient",
        "tags": [
          "OAuth"
        ],
        "summary": "Dynamic client registration (RFC 7591), public clients only",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OAuthRegistration"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthClient"
                }
              }
            }
          },
          "400": {
            "description": "RFC 6749 §5.2's error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthError"
                }
              }
            }
          }
        },
        "security": [],
        "x-access": "write"
      }
    },
    "/oauth/token": {
      "post": {
        "operationId": "token",
        "tags": [
          "OAuth"
        ],
        "summary": "Trade an authorization code (with its PKCE verifier) or a refresh token for tokens",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/OAuthTokenRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthTokens"
                }
              }
            }
          },
          "400": {
            "description": "RFC 6749 §5.2's error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthError"
                }
              }
            }
          }
        },
        "security": [],
        "x-access": "write"
      }
    },
    "/oauth/revoke": {
      "post": {
        "operationId": "revokeToken",
        "tags": [
          "OAuth"
        ],
        "summary": "Revoke an access or refresh token (RFC 7009)",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/OAuthRevokeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Revoked, or the token was none (RFC 7009)."
          },
          "400": {
            "description": "RFC 6749 §5.2's error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthError"
                }
              }
            }
          }
        },
        "security": [],
        "x-access": "write"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1, PKCE S256, public clients. Metadata: https://axad.ai/.well-known/oauth-authorization-server (RFC 8414).",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://axad.ai/oauth/authorize",
            "tokenUrl": "https://axad.ai/v1/oauth/token",
            "refreshUrl": "https://axad.ai/v1/oauth/token",
            "scopes": {
              "axad": "Everything the learner's Axad account can do."
            }
          }
        }
      }
    },
    "schemas": {
      "Account": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Id"
          },
          "email": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": false
      },
      "AccountUsage": {
        "type": "object",
        "properties": {
          "account": {
            "$ref": "#/components/schemas/Account"
          },
          "providers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "\"apple\" | \"google\" | \"local\", each identity once."
          },
          "replies_this_month": {
            "$ref": "#/components/schemas/Int",
            "description": "Tutor replies since the 1st of this month, UTC."
          },
          "materials": {
            "$ref": "#/components/schemas/Int",
            "description": "The learner's own materials, not starter texts."
          },
          "cards": {
            "$ref": "#/components/schemas/Int"
          },
          "reviews": {
            "$ref": "#/components/schemas/Int"
          },
          "images_nominated": {
            "$ref": "#/components/schemas/Int"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "billing": {
            "$ref": "#/components/schemas/Billing",
            "description": "Absent while the server takes no payments (no Stripe key)."
          },
          "entitlements": {
            "$ref": "#/components/schemas/Entitlements"
          }
        },
        "required": [
          "account",
          "providers",
          "replies_this_month",
          "materials",
          "cards",
          "reviews",
          "images_nominated",
          "usage",
          "entitlements"
        ],
        "additionalProperties": false,
        "description": "GET /account, with the app's token or the site's cookie: the signed-in account, how it signs in, what it keeps, what it spent. DELETE /account removes it all; pictures it nominated stay in the shared library, and its credit grants stay on record with no link to it.\n\nGET /account/events, with the app's token: a `text/event-stream` that sends the account's whole state as it is now, at once and after every change to it from any source (a credit grant, a turn's usage, a profile or plan change, an SQL insert by hand): each event is `event: account` with `data:` this object's JSON. A comment line every 20 s keeps it open. On a lost connection the app connects again, and the first event brings it up to date."
      },
      "AllowanceSpent": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "spent": {
            "$ref": "#/components/schemas/Int"
          },
          "allowance": {
            "$ref": "#/components/schemas/Int"
          }
        },
        "required": [
          "allowance",
          "error",
          "spent"
        ],
        "additionalProperties": false,
        "description": "402 from POST /model/messages, POST /speech and POST /images once the account has spent its allowance. `error` is \"allowance_spent\"."
      },
      "AnswerResult": {
        "type": "object",
        "properties": {
          "given": {
            "type": "string"
          },
          "correct": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "null: free text, the tutor checks it."
          },
          "answer": {
            "$ref": "#/components/schemas/Int",
            "description": "The right option, for choice questions."
          }
        },
        "required": [
          "given",
          "correct"
        ],
        "additionalProperties": false
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "Bag": {
        "type": "object",
        "properties": {
          "cards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CardSummary"
            }
          },
          "due": {
            "$ref": "#/components/schemas/Int"
          },
          "hard": {
            "$ref": "#/components/schemas/Int"
          },
          "all": {
            "$ref": "#/components/schemas/Int"
          }
        },
        "required": [
          "cards",
          "due",
          "hard",
          "all"
        ],
        "additionalProperties": false,
        "description": "GET /cards?due=1&hard=1&q=…&material=…&lang=…"
      },
      "Billing": {
        "type": "object",
        "properties": {
          "card_trial": {
            "$ref": "#/components/schemas/Int",
            "description": "What the trial becomes once the learner saves a valid card, in micro-dollars."
          },
          "card_added": {
            "type": "boolean",
            "description": "A saved card raised this account's trial; it does so once per account and once per card."
          },
          "plans": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Plan"
            }
          },
          "topups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TopUp"
            },
            "description": "Credit bought once, beside a plan: `TopUp.id` in POST /billing/checkout {kind: \"topup\"}."
          }
        },
        "required": [
          "card_trial",
          "card_added",
          "plans",
          "topups"
        ],
        "additionalProperties": false
      },
      "CardCheckout": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "const": "card"
          }
        },
        "required": [
          "kind"
        ],
        "additionalProperties": false,
        "description": "Save a card, charged nothing, for the card trial."
      },
      "CardDetail": {
        "type": "object",
        "properties": {
          "card": {
            "$ref": "#/components/schemas/CardSummary"
          },
          "chat": {
            "$ref": "#/components/schemas/Id",
            "description": "This card's own chat."
          },
          "examples": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Example"
            }
          },
          "next": {
            "$ref": "#/components/schemas/NextDue",
            "description": "The next due time for each grade."
          }
        },
        "required": [
          "card",
          "chat",
          "examples",
          "next"
        ],
        "additionalProperties": false,
        "description": "GET /cards/:id"
      },
      "CardSummary": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Id"
          },
          "lang": {
            "type": "string",
            "description": "BCP 47 code of the card's language."
          },
          "kind": {
            "type": "string"
          },
          "key": {
            "type": "string"
          },
          "front": {
            "type": "string"
          },
          "back": {
            "type": "string"
          },
          "due": {
            "$ref": "#/components/schemas/Time"
          },
          "state": {
            "type": "string",
            "enum": [
              "new",
              "learning",
              "review",
              "relearning"
            ]
          },
          "seen": {
            "$ref": "#/components/schemas/Int",
            "description": "Number of examples."
          },
          "hard": {
            "type": "boolean",
            "description": "A hard example newer than the last review."
          },
          "known": {
            "type": "boolean",
            "description": "FSRS stability of 21 days or more."
          },
          "image": {
            "$ref": "#/components/schemas/Id",
            "description": "A library image that shows the card's meaning."
          }
        },
        "required": [
          "id",
          "lang",
          "kind",
          "key",
          "front",
          "back",
          "due",
          "state",
          "seen",
          "hard",
          "known"
        ],
        "additionalProperties": false
      },
      "Catalog": {
        "type": "object",
        "properties": {
          "languages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogLanguage"
            },
            "description": "Every language the library has, for the language choice of the Library and New Lesson."
          },
          "levels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogLevel"
            },
            "description": "The levels a learner can set as a goal, in order, as the library data names them."
          },
          "lessons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogLesson"
            },
            "description": "The lessons of the asked language (of every language without `lang`), each with the learner's copy."
          },
          "exams": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExamGoal"
            },
            "description": "The exams of the asked language; empty without `lang`."
          },
          "sections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogSection"
            },
            "description": "The parents of the asked language's Library tree below the language, each with its English subtitle: every parent that a lesson's `path` or an exam part's `path` makes has one. Empty without `lang`."
          }
        },
        "required": [
          "languages",
          "levels",
          "lessons",
          "exams",
          "sections"
        ],
        "additionalProperties": false,
        "description": "GET /catalog?lang=<BCP 47> → Catalog: Axad's global library for that language, the same for every learner: its lessons, its exams with their parts and official practice exams, and the levels the goal chip offers. Without `lang`: the lessons of every language, no exams. The server reads all of it from its library data (the repository's `library/`, loaded with `axad-server library load`), never from code: a new lesson, exam, official link or language is new data alone. POST /catalog/:id → Material: that lesson in the learner's library, added now or the copy it has (a starter material with the lesson's title). 404 for no such lesson."
      },
      "CatalogLanguage": {
        "type": "object",
        "properties": {
          "lang": {
            "type": "string",
            "description": "BCP 47 code: \"nl\"."
          },
          "name": {
            "type": "string",
            "description": "Its English name, as the library data names it."
          },
          "subtitle": {
            "type": "string",
            "description": "What it is, in English: \"Spoken in the Netherlands and Flanders\"."
          },
          "lessons": {
            "$ref": "#/components/schemas/Int"
          },
          "exams": {
            "$ref": "#/components/schemas/Int"
          }
        },
        "required": [
          "lang",
          "name",
          "subtitle",
          "lessons",
          "exams"
        ],
        "additionalProperties": false
      },
      "CatalogLesson": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The lesson's id in the library data: its file name without \".md\"."
          },
          "title": {
            "type": "string"
          },
          "subtitle": {
            "type": "string",
            "description": "What it is, in English, under its title: \"Axad practice exam, Reading A2\"."
          },
          "lang": {
            "type": "string",
            "description": "BCP 47 code of the lesson's language."
          },
          "level": {
            "type": "string",
            "description": "\"A2\"."
          },
          "path": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Its place in the index, as `MaterialSummary.path`."
          },
          "kind": {
            "$ref": "#/components/schemas/MaterialKind",
            "description": "\"text\", or \"listening\" for a listening practice exam."
          },
          "exam": {
            "type": "string",
            "description": "As `MaterialSummary.exam`: the exam part a practice exam is for."
          },
          "material": {
            "$ref": "#/components/schemas/Id",
            "description": "The learner's copy, when their library has one."
          }
        },
        "required": [
          "id",
          "title",
          "subtitle",
          "lang",
          "level",
          "path",
          "kind"
        ],
        "additionalProperties": false
      },
      "CatalogLevel": {
        "type": "object",
        "properties": {
          "level": {
            "type": "string",
            "description": "As `LanguageGoal.level` stores it: \"A2\"."
          },
          "name": {
            "type": "string",
            "description": "What the learner reads, in English: \"Elementary (A2)\"."
          }
        },
        "required": [
          "level",
          "name"
        ],
        "additionalProperties": false
      },
      "CatalogSection": {
        "type": "object",
        "properties": {
          "path": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Below the language: [\"Inburgering\", \"A2\", \"Lezen\"]."
          },
          "subtitle": {
            "type": "string",
            "description": "What it is, in English, for a learner who does not read the language yet: \"Reading\"."
          }
        },
        "required": [
          "path",
          "subtitle"
        ],
        "additionalProperties": false
      },
      "ChatTab": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Id"
          },
          "title": {
            "type": "string",
            "description": "The learner's name for it; absent: the app names it by its first action or \"New tab\"."
          },
          "at": {
            "$ref": "#/components/schemas/Time"
          }
        },
        "required": [
          "id",
          "at"
        ],
        "additionalProperties": false
      },
      "CheckoutRequest": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/CardCheckout"
          },
          {
            "$ref": "#/components/schemas/PlanCheckout"
          },
          {
            "$ref": "#/components/schemas/TopUpCheckout"
          }
        ],
        "description": "POST /billing/checkout, with the site's cookie or the app's token. 503 while the server takes no payments."
      },
      "CheckoutResponse": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "additionalProperties": false,
        "description": "The Stripe Checkout page; it sends the browser back to /account."
      },
      "Digest": {
        "type": "object",
        "properties": {
          "cards": {
            "$ref": "#/components/schemas/Int"
          },
          "known": {
            "$ref": "#/components/schemas/Int"
          },
          "progress": {
            "type": "number"
          },
          "touched": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TouchedSentence"
            }
          }
        },
        "required": [
          "cards",
          "known",
          "progress",
          "touched"
        ],
        "additionalProperties": false,
        "description": "How far the learner has digested the material, from its cards alone: the cards with an example anchored in it. `known` = FSRS stability of 21 days or more. `progress` = the mean over those cards of min(stability ÷ 21 days, 1), 0 for a card never reviewed: from 0 to 1, it grows with each good review and is 1 when every card is known. The learner sets nothing."
      },
      "Entitlements": {
        "type": "object",
        "properties": {
          "tier": {
            "$ref": "#/components/schemas/Tier"
          },
          "limits": {
            "$ref": "#/components/schemas/Limits"
          },
          "bag": {
            "$ref": "#/components/schemas/Int",
            "description": "What the account holds now: cards in the bag, active lessons."
          },
          "lessons": {
            "$ref": "#/components/schemas/Int"
          },
          "subscription": {
            "$ref": "#/components/schemas/Subscription",
            "description": "The account's plan, while it has one."
          }
        },
        "required": [
          "tier",
          "limits",
          "bag",
          "lessons"
        ],
        "additionalProperties": false,
        "description": "GET /account `entitlements`, and every GET /account/events event."
      },
      "ExamBand": {
        "type": "object",
        "properties": {
          "min": {
            "$ref": "#/components/schemas/Int"
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "min",
          "text"
        ],
        "additionalProperties": false
      },
      "ExamCaseNew": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "description": "A reading case's text, or what a listening case prints (its scene): plain text, paragraphs split by a blank line, list items starting \"• \", table rows as cells split by \" | \". At most 20,000 characters."
          },
          "media": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Media"
            }
          },
          "questions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExamQuestionNew"
            }
          }
        },
        "required": [
          "text",
          "media",
          "questions"
        ],
        "additionalProperties": false,
        "description": "One case of an exam: a text or a recording, and the 1–4 questions about it."
      },
      "ExamGoal": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "As the learner names it, and as `LanguageGoal.exam` stores it."
          },
          "subtitle": {
            "type": "string",
            "description": "What it is, in English: \"Dutch civic integration exam, level A2\"."
          },
          "level": {
            "type": "string",
            "description": "Its CEFR level, stored in `LanguageGoal.level`."
          },
          "parts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExamPart"
            },
            "description": "The parts Axad offers practice for: its own practice exams (lessons whose `exam` names the part) and the official ones."
          }
        },
        "required": [
          "name",
          "subtitle",
          "level"
        ],
        "additionalProperties": false
      },
      "ExamNew": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "`OfficialPractice.name`."
          },
          "source": {
            "type": "string",
            "description": "`OfficialPractice.url`."
          },
          "exam": {
            "type": "string",
            "description": "The exam part, as `MaterialSummary.exam` names it."
          },
          "lang": {
            "type": "string",
            "description": "BCP 47 code of the exam's language."
          },
          "level": {
            "type": "string"
          },
          "notice": {
            "type": "string",
            "description": "The maker's notice of its rights, which the exam shows on its start screen, word for word."
          },
          "cases": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExamCaseNew"
            }
          }
        },
        "required": [
          "title",
          "source",
          "exam",
          "lang",
          "level",
          "cases"
        ],
        "additionalProperties": false,
        "description": "POST /exams → Material of kind \"exam\": an official practice exam that the learner's Axad fetched from its maker's site. The learner's library has one per `source`: posting a source again replaces that material's cases and keeps its chat. 400 for no case, a question with fewer than 2 options, or an `answer` outside its options."
      },
      "ExamPart": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The part's name in the exam's language, as `MaterialSummary.exam` ends."
          },
          "subtitle": {
            "type": "string",
            "description": "What it is, in English: \"Reading\"."
          },
          "skill": {
            "type": "string",
            "description": "What it tests, as the library data says it: \"reading\", \"listening\", \"writing\", \"speaking\"; the app shows any word."
          },
          "minutes": {
            "$ref": "#/components/schemas/Int",
            "description": "The time the real exam gives for this part."
          },
          "path": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Where its official practice exams sit in the Library tree, below the language: [\"Inburgering\", \"A2\", \"Lezen\"]. The data gives it for every part with `official`."
          },
          "official": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OfficialPractice"
            },
            "description": "The free official practice exams of this part: New Lesson fetches one into the learner's library (POST /exams)."
          },
          "bands": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExamBand"
            },
            "description": "What a result means for the real exam, by the number of questions right: the band with the highest `min` that the count reaches. Axad's own words, after the maker's bands."
          }
        },
        "required": [
          "name",
          "subtitle",
          "skill",
          "minutes"
        ],
        "additionalProperties": false
      },
      "ExamQuestionNew": {
        "type": "object",
        "properties": {
          "ask": {
            "type": "string"
          },
          "ask_media": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Media"
            }
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "2–4 options; a picture option's text may be empty."
          },
          "option_media": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Media"
              }
            }
          },
          "answer": {
            "$ref": "#/components/schemas/Int",
            "description": "The index of the right option: the maker's key."
          }
        },
        "required": [
          "ask",
          "options",
          "answer"
        ],
        "additionalProperties": false
      },
      "ExamResult": {
        "type": "object",
        "properties": {
          "right": {
            "$ref": "#/components/schemas/Int",
            "description": "The questions answered right."
          },
          "total": {
            "$ref": "#/components/schemas/Int"
          },
          "answered": {
            "$ref": "#/components/schemas/Int",
            "description": "The questions answered at all."
          },
          "seconds": {
            "$ref": "#/components/schemas/Int"
          },
          "at": {
            "$ref": "#/components/schemas/Time"
          }
        },
        "required": [
          "right",
          "total",
          "answered",
          "seconds",
          "at"
        ],
        "additionalProperties": false
      },
      "Example": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Id"
          },
          "say": {
            "type": "string",
            "description": "The source sentence."
          },
          "mark": {
            "$ref": "#/components/schemas/Span",
            "description": "[start, end) of the card's form in `say`; absent when the server cannot place it."
          },
          "material": {
            "$ref": "#/components/schemas/MaterialRef"
          },
          "hard": {
            "type": "boolean"
          },
          "at": {
            "$ref": "#/components/schemas/Time"
          }
        },
        "required": [
          "id",
          "say",
          "material",
          "hard",
          "at"
        ],
        "additionalProperties": false
      },
      "GiftRedeem": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          }
        },
        "required": [
          "code"
        ],
        "additionalProperties": false,
        "description": "POST /billing/redeem, with the app's token or the site's cookie: a gift code the owner made gives its credit to this account at once (a `credit_grant` of kind \"gift\" whose `source` holds the code), once per account. The code is read without regard to case, spaces or dashes. 400 `ApiError.error`: \"gift_unknown\" (no such code), \"gift_used\" (this account redeemed it, or it has no uses left), \"gift_expired\", \"gift_disabled\"; 429 \"gift_tries\" after too many wrong codes from this account in an hour."
      },
      "GiftRedeemed": {
        "type": "object",
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/Int",
            "description": "Micro-dollars of credit added."
          }
        },
        "required": [
          "amount"
        ],
        "additionalProperties": false,
        "description": "What a redeemed gift code gave."
      },
      "HandIn": {
        "type": "object",
        "properties": {
          "answers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HandInAnswer"
            }
          },
          "seconds": {
            "$ref": "#/components/schemas/Int",
            "description": "The seconds the learner took, from start to hand-in."
          }
        },
        "required": [
          "answers",
          "seconds"
        ],
        "additionalProperties": false,
        "description": "POST /materials/:id/handin → Material, with `result` and each question's `answered`: the learner hands in an \"exam\". Each answer replaces the one before; a question with no `option` stays unanswered and counts as wrong. 409 for a material that is not an exam. The learner may hand in again: a new try replaces the result."
      },
      "HandInAnswer": {
        "type": "object",
        "properties": {
          "question": {
            "$ref": "#/components/schemas/Id"
          },
          "option": {
            "$ref": "#/components/schemas/Int",
            "description": "The chosen option's index, or absent for no answer."
          }
        },
        "required": [
          "question"
        ],
        "additionalProperties": false
      },
      "Id": {
        "type": "string",
        "description": "\"m_12\", \"c_41\", \"p_1\": a prefix that says the kind, then a ULID."
      },
      "Image": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Id"
          },
          "title": {
            "type": "string",
            "description": "A literal English description of the scene, 8–40 words: what search reads."
          },
          "concept": {
            "type": "string",
            "description": "The language element it teaches, in its language: \"de wachtkamer\", \"afzeggen\"."
          },
          "lang": {
            "type": "string",
            "description": "BCP 47 code of `concept` and of `text`."
          },
          "text": {
            "type": "string",
            "description": "The words drawn in the image, exactly. Absent: the image holds no text and serves every language."
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Themes from the fixed list in harness/images/rules.md: \"health\", \"time\"."
          },
          "status": {
            "type": "string",
            "enum": [
              "drawing",
              "ready",
              "failed"
            ]
          },
          "url": {
            "type": "string",
            "description": "GET it with the same token: \"/v1/image-files/<hash>.webp\". Absent until ready."
          },
          "width": {
            "$ref": "#/components/schemas/Int"
          },
          "height": {
            "$ref": "#/components/schemas/Int"
          }
        },
        "required": [
          "id",
          "title",
          "concept",
          "lang",
          "topics",
          "status"
        ],
        "additionalProperties": false
      },
      "ImageMatches": {
        "type": "object",
        "properties": {
          "images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Image"
            }
          },
          "unjudged": {
            "type": "string",
            "description": "Set when the order is by words or vectors only, and why: the judge or the vectors did not answer."
          }
        },
        "required": [
          "images"
        ],
        "additionalProperties": false,
        "description": "GET /images?q=…&lang=…: the find_images tool. Full text and vectors make a shortlist of up to 100; the judge keeps those that fit `q`, most likely first, at most 8. An image with `text` in another language than `lang` is left out."
      },
      "ImageNomination": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "concept": {
            "type": "string"
          },
          "canon": {
            "type": "string",
            "description": "The generic English concept the picture shows, 1–4 words, dictionary form, with no names, numbers or words of one sentence: \"doctor's practice\", \"apple\", \"train platform\". The library keeps one picture per concept. The tool schema (harness/tools.md) requires it; the wire leaves it optional for apps that predate it, and the server then uses `concept`."
          },
          "lang": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "prompt": {
            "type": "string",
            "description": "What to draw, 40–200 words: the scene, its objects and where they are. No style words: the server adds the house style."
          }
        },
        "required": [
          "title",
          "concept",
          "lang",
          "prompt"
        ],
        "additionalProperties": false,
        "description": "POST /images: the nominate_image tool. 503 while the judge or the drawing key is missing; 429 past the daily cap; 402 (`AllowanceSpent`) once the allowance is spent. Each drawing is paid from the nominating account's allowance."
      },
      "Int": {
        "type": "integer"
      },
      "LanguageGoal": {
        "type": "object",
        "properties": {
          "lang": {
            "type": "string"
          },
          "level": {
            "type": "string",
            "description": "\"A2\", or any level words the learner uses. Absent: the tutor writes at the material's own level."
          },
          "exam": {
            "type": "string",
            "description": "An exam's name, as `ExamGoal.name` of the catalog says it."
          }
        },
        "required": [
          "lang"
        ],
        "additionalProperties": false,
        "description": "The learner in one language."
      },
      "Library": {
        "type": "object",
        "properties": {
          "materials": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MaterialSummary"
            }
          }
        },
        "required": [
          "materials"
        ],
        "additionalProperties": false,
        "description": "GET /materials?exams=1 → Library. Without `exams=1` the list leaves out materials of kind \"exam\", which app versions from before that kind cannot read."
      },
      "LimitReached": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "limit": {
            "type": "string",
            "enum": [
              "bag",
              "lessons"
            ]
          },
          "max": {
            "$ref": "#/components/schemas/Int"
          },
          "count": {
            "$ref": "#/components/schemas/Int"
          },
          "upgrade_url": {
            "type": "string",
            "description": "https://axad.ai/account?upgrade=<limit>: the plans, one tap each."
          }
        },
        "required": [
          "count",
          "error",
          "limit",
          "max",
          "upgrade_url"
        ],
        "additionalProperties": false,
        "description": "402 when an add or an open would pass the tier's limit: a card into a full bag, a lesson opened while the active lessons are full. Nothing is deleted; the learner closes a lesson, deletes cards, or upgrades. `error` is \"limit_reached\"."
      },
      "Limits": {
        "type": "object",
        "properties": {
          "bag": {
            "$ref": "#/components/schemas/Int",
            "description": "Cards in the bag."
          },
          "lessons": {
            "$ref": "#/components/schemas/Int",
            "description": "Lessons open at the same time (`MaterialSummary.closed_at`)."
          }
        },
        "additionalProperties": false,
        "description": "What a tier allows. An absent limit is unlimited."
      },
      "Material": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Id"
          },
          "chat": {
            "$ref": "#/components/schemas/Id",
            "description": "This material's first chat: the one its first turn runs in."
          },
          "chats": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatTab"
            },
            "description": "Every chat of the material, its first `chat` first, then the scratchpad tabs the learner opened, oldest first. POST /materials/:id/chats {title?} → ChatTab opens one; PATCH /chats/:id {title} renames it; DELETE /chats/:id closes it: it leaves this list, and its messages stay for the cards made in it (400 for the first chat)."
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PassageLink"
            },
            "description": "The parts of the text the learner dug into (the actions whose `links` is true in harness/actions.md), each with the last tutor message about it, across all the material's chats; the newest per part."
          },
          "title": {
            "type": "string"
          },
          "kind": {
            "$ref": "#/components/schemas/MaterialKind"
          },
          "path": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "starter": {
            "type": "boolean",
            "description": "As `MaterialSummary.starter`: from Axad's global library. The Library shows the learner's own texts under their own parent."
          },
          "source": {
            "type": "string"
          },
          "app": {
            "type": "string"
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "level": {
            "type": "string"
          },
          "image": {
            "$ref": "#/components/schemas/Id"
          },
          "exam": {
            "type": "string"
          },
          "result": {
            "$ref": "#/components/schemas/ExamResult",
            "description": "An \"exam\" after its hand-in: the result; absent before."
          },
          "notice": {
            "type": "string",
            "description": "An \"exam\": its maker's notice of its rights, which its start screen shows word for word (`ExamNew.notice`)."
          },
          "passages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Passage"
            }
          },
          "questions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Question"
            }
          },
          "digest": {
            "$ref": "#/components/schemas/Digest"
          },
          "pages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Page"
            },
            "description": "The material's pages, in order: the learner studies one at a time, with the tutor beside it. Empty: one page, the whole material. A material is paged when its data says so (a library lesson's `pages: questions`; every exam the app fetched): one page per question, with the passage it asks about."
          },
          "page": {
            "$ref": "#/components/schemas/Int",
            "description": "The page the learner was last on, from 0 (0 without pages). PUT /materials/:id/page {page} → 204 moves it."
          },
          "starters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Starter"
            },
            "description": "The buttons at the start of the material's chat (of each page's start when it has pages: `page_starters`)."
          },
          "page_starters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Starter"
            },
            "description": "The buttons at the start of each page's part of the chat; empty without pages."
          }
        },
        "required": [
          "id",
          "chat",
          "chats",
          "links",
          "title",
          "kind",
          "path",
          "starter",
          "languages",
          "passages",
          "questions",
          "digest",
          "pages",
          "page",
          "starters",
          "page_starters"
        ],
        "additionalProperties": false,
        "description": "GET /materials/:id"
      },
      "MaterialKind": {
        "type": "string",
        "enum": [
          "text",
          "web",
          "chat",
          "file",
          "question",
          "listening",
          "exam"
        ],
        "description": "\"question\": a lesson the learner started with a question on New Lesson; its one passage is the question. \"chat\": a chat the learner captured from another app (its passages are the chat's lines); or, with no passage at all, a free-form talk with the tutor that New Lesson's \"Free-form chat with Tutor\" started (`MaterialNew.kind` \"talk\"): the chat is the lesson, and the tutor names it with describe_material from the talk. \"listening\": a lesson to hear, one of Axad's listening practice exams: the reader plays each passage and hides its text until the learner shows it. Each line starts with a speaker label of its language's library data (the narrator, who sets the scene, then the people who speak), as exam transcripts write them; a line with none is the speaker's before it. `SpeechRequest.speakers` says it with those voices. \"exam\": one of the free official practice exams (`OfficialPractice`), which the learner's own Axad fetched from its maker's site with POST /exams. The reader shows it as the real exam does: its cases one question at a time, the exam's clock, then a hand-in (POST /materials/:id/handin), the result and a review. Its recorded media and pictures stay on the learner's Mac (`Media.file`); the server keeps its text and its key."
      },
      "MaterialNew": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "The file name, the page title, or absent: the tutor's describe_material names it."
          },
          "kind": {
            "type": "string",
            "enum": [
              "text",
              "web",
              "file",
              "question",
              "talk"
            ],
            "description": "\"talk\": New Lesson's free-form chat with the tutor: no text (`pages` empty), stored as kind \"chat\" with no passage."
          },
          "source": {
            "type": "string",
            "description": "The URL or file name."
          },
          "via": {
            "type": "string",
            "enum": [
              "paste",
              "file",
              "url",
              "ocr"
            ]
          },
          "lang": {
            "type": "string",
            "description": "The language the learner chose to learn on New Lesson, BCP 47: \"nl\". The material starts with it as its `languages`, and the server adds it to `Profile.languages` as describe_material would; the tutor corrects it with describe_material when the text is in another language. Absent: the tutor detects it."
          },
          "pages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "One entry per page for a PDF, else one entry (none for \"talk\"). Each at most 200,000 characters; at most 400 pages."
          }
        },
        "required": [
          "kind",
          "via",
          "pages"
        ],
        "additionalProperties": false,
        "description": "POST /materials → Material: a lesson the learner starts on New Lesson, 1 passage per entry of `pages`. A paste: kind \"text\", via \"paste\", 1 page. A file: kind \"file\", via \"file\", the file name as `title` and `source`, 1 page per PDF page, else 1. A question: kind \"question\", via \"paste\", 1 page of at most 500 characters, in any language."
      },
      "MaterialPatch": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "level": {
            "type": "string"
          },
          "image": {
            "$ref": "#/components/schemas/Id",
            "description": "A library image id: 400 when no such image."
          },
          "path": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The material's place in the index, 1–5 parts of at most 60 characters each."
          }
        },
        "additionalProperties": false,
        "description": "PATCH /materials/:id → Material. The learner's choice of the text's language, and the tutor's `describe_material` tool. The server adds each new language (other than the profile's `support`) to `Profile.languages`."
      },
      "MaterialRef": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Id"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "title"
        ],
        "additionalProperties": false
      },
      "MaterialSummary": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Id"
          },
          "title": {
            "type": "string"
          },
          "kind": {
            "$ref": "#/components/schemas/MaterialKind"
          },
          "path": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Where the material sits in the learner's index, broad to narrow, without its own title: [language, area, level], as its library data or the tutor names them. The reader shows it as a breadcrumb before the title; the library groups by it. Empty: not placed yet. Lessons of the global library take it from their data; the learner or the tutor (describe_material) sets it for the rest."
          },
          "starter": {
            "type": "boolean",
            "description": "Whether it came from Axad's global library: a `CatalogLesson`."
          },
          "source": {
            "type": "string",
            "description": "The domain, file path, app and chat."
          },
          "app": {
            "type": "string",
            "description": "App bundle id, for the icon."
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "BCP 47 codes of the languages in the material, the main one first. Empty until the tutor detects them."
          },
          "level": {
            "type": "string",
            "description": "The text's own level, \"A2\", as the tutor judged it. The level the learner studies at is their goal for the language (`Profile.languages`)."
          },
          "image": {
            "$ref": "#/components/schemas/Id",
            "description": "A library picture of what the text is about, set by the tutor with describe_material: the library shows it."
          },
          "exam": {
            "type": "string",
            "description": "The exam part this lesson practises: an `ExamGoal.name` of the catalog, \" · \", then one of its `ExamPart.name`s. Absent: not a practice exam."
          },
          "cards": {
            "$ref": "#/components/schemas/Int"
          },
          "known": {
            "$ref": "#/components/schemas/Int"
          },
          "touched": {
            "$ref": "#/components/schemas/Int",
            "description": "Sentences the learner touched, of all `sentences` in the material's passages."
          },
          "sentences": {
            "$ref": "#/components/schemas/Int"
          },
          "progress": {
            "type": "number",
            "description": "As `Digest.progress`."
          },
          "seen_at": {
            "$ref": "#/components/schemas/Time"
          },
          "closed_at": {
            "$ref": "#/components/schemas/Time",
            "description": "The learner closed it: it stays in the library with its chats, cards and pages, and counts no more against the plan's active lessons. POST /materials/:id/close closes it; POST /materials/:id/open opens it again (402 `LimitReached` with `limit` \"lessons\" when the plan's active lessons are full). A material is active from its first open (`seen_at`) until it is closed; GET /materials/:id of a material that is not active opens it, under the same 402."
          },
          "result": {
            "$ref": "#/components/schemas/ExamResult",
            "description": "An \"exam\" after its hand-in: its result, as `Material.result`."
          }
        },
        "required": [
          "id",
          "title",
          "kind",
          "path",
          "starter",
          "languages",
          "cards",
          "known",
          "touched",
          "sentences",
          "progress"
        ],
        "additionalProperties": false
      },
      "Media": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "audio",
              "video",
              "image"
            ]
          },
          "file": {
            "type": "string",
            "description": "Its file name in the material's media folder: the maker's id and an extension, \"3f2a….mp3\"."
          },
          "caption": {
            "type": "string",
            "description": "What the exam prints beside it: the scene that a listening case's first sound says."
          },
          "seconds": {
            "type": "number",
            "description": "Its length in seconds, for a sound or a video."
          }
        },
        "required": [
          "kind",
          "file"
        ],
        "additionalProperties": false,
        "description": "A recorded sound, a video or a picture of an exam. The file lives in the material's media folder on the learner's Mac, which the fetch filled; the server only names it."
      },
      "NextDue": {
        "type": "object",
        "properties": {
          "again": {
            "$ref": "#/components/schemas/Time"
          },
          "hard": {
            "$ref": "#/components/schemas/Time"
          },
          "good": {
            "$ref": "#/components/schemas/Time"
          },
          "easy": {
            "$ref": "#/components/schemas/Time"
          }
        },
        "required": [
          "again",
          "hard",
          "good",
          "easy"
        ],
        "additionalProperties": false
      },
      "NominationAccepted": {
        "type": "object",
        "properties": {
          "is": {
            "type": "string",
            "const": "accepted"
          },
          "image": {
            "$ref": "#/components/schemas/Image"
          }
        },
        "required": [
          "is",
          "image"
        ],
        "additionalProperties": false,
        "description": "Drawing starts now; GET /images/:id until `status` is \"ready\"."
      },
      "NominationExisting": {
        "type": "object",
        "properties": {
          "is": {
            "type": "string",
            "const": "existing"
          },
          "image": {
            "$ref": "#/components/schemas/Image"
          }
        },
        "required": [
          "is",
          "image"
        ],
        "additionalProperties": false,
        "description": "A library image already shows it: use that one."
      },
      "NominationResult": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/NominationAccepted"
          },
          {
            "$ref": "#/components/schemas/NominationExisting"
          },
          {
            "$ref": "#/components/schemas/NominationUnmet"
          }
        ]
      },
      "NominationUnmet": {
        "type": "object",
        "properties": {
          "is": {
            "type": "string",
            "const": "unmet"
          },
          "unmet": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RuleMiss"
            }
          }
        },
        "required": [
          "is",
          "unmet"
        ],
        "additionalProperties": false,
        "description": "The rules it does not meet yet; fix each and send it again."
      },
      "NumberedSentence": {
        "type": "object",
        "properties": {
          "n": {
            "$ref": "#/components/schemas/Int"
          },
          "say": {
            "type": "string"
          },
          "touched": {
            "type": "boolean"
          }
        },
        "required": [
          "n",
          "say",
          "touched"
        ],
        "additionalProperties": false
      },
      "OfficialPractice": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Its maker, then its maker's own name for it, so the learner sees whose it is."
          },
          "subtitle": {
            "type": "string",
            "description": "What it is, in English, under its name: \"Official DUO practice exam, Reading 1\"."
          },
          "url": {
            "type": "string"
          },
          "format": {
            "type": "string",
            "description": "How the app reads the exam from its maker's site, by the platform the maker uses: \"optimum-assessment\". A practice exam whose format the app does not know stays a link that opens in the browser."
          }
        },
        "required": [
          "name",
          "subtitle",
          "url"
        ],
        "additionalProperties": false
      },
      "Page": {
        "type": "object",
        "properties": {
          "n": {
            "$ref": "#/components/schemas/Int",
            "description": "From 1, in order."
          },
          "passage": {
            "$ref": "#/components/schemas/Id"
          },
          "question": {
            "$ref": "#/components/schemas/Id"
          },
          "seen": {
            "type": "boolean",
            "description": "The learner has opened this page."
          }
        },
        "required": [
          "n",
          "seen"
        ],
        "additionalProperties": false,
        "description": "One page of a material: a question with the passage it asks about."
      },
      "PageAt": {
        "type": "object",
        "properties": {
          "page": {
            "$ref": "#/components/schemas/Int"
          }
        },
        "required": [
          "page"
        ],
        "additionalProperties": false,
        "description": "PUT /materials/:id/page: the page the learner is on now; it counts as seen."
      },
      "Passage": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Id"
          },
          "seq": {
            "$ref": "#/components/schemas/Int"
          },
          "ref": {
            "type": "string",
            "description": "The page URL, file page or chat that the text came from."
          },
          "text": {
            "type": "string"
          },
          "sentences": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Span"
            },
            "description": "[start, end) of each sentence, by the server's Unicode sentence rules."
          },
          "media": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Media"
            },
            "description": "An exam case's recorded media and pictures, in the order the exam plays and shows them: for a listening case the spoken scene, the spoken instruction, then the fragment (a video, or a sound with its picture)."
          },
          "spoken": {
            "$ref": "#/components/schemas/PassageSpoken",
            "description": "An exam case's fragment as Axad transcribed it: its words, in `text`, timed in that media."
          }
        },
        "required": [
          "id",
          "seq",
          "text",
          "sentences"
        ],
        "additionalProperties": false
      },
      "PassageLink": {
        "type": "object",
        "properties": {
          "passage": {
            "$ref": "#/components/schemas/Id"
          },
          "start": {
            "$ref": "#/components/schemas/Int",
            "description": "[start, end) in UTF-16 units of the passage text."
          },
          "end": {
            "$ref": "#/components/schemas/Int"
          },
          "chat": {
            "$ref": "#/components/schemas/Id"
          },
          "message": {
            "$ref": "#/components/schemas/Id"
          }
        },
        "required": [
          "passage",
          "start",
          "end",
          "chat",
          "message"
        ],
        "additionalProperties": false,
        "description": "A span of a passage and the last tutor message about it: a click on the span shows that message."
      },
      "PassageSpoken": {
        "type": "object",
        "properties": {
          "media": {
            "$ref": "#/components/schemas/Int",
            "description": "The index into `Passage.media` of the fragment the words are timed in."
          },
          "words": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpokenWord"
            },
            "description": "Each word of the transcript: its place in `Passage.text`, and its time in that media."
          }
        },
        "required": [
          "media",
          "words"
        ],
        "additionalProperties": false,
        "description": "POST /materials/:id/passages/:passage/transcript?media=<index into Passage.media> with the sound of that media as the body (audio/mp4 or audio/mpeg, at most 25 MB) → Passage: Axad transcribes the fragment and appends its words to the passage's `text`, after a blank line. It is open before the exam's hand-in too: the transcript shows what was said, not the answers. The same passage again returns it as it is."
      },
      "Plan": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "tier": {
            "$ref": "#/components/schemas/Tier"
          },
          "price": {
            "$ref": "#/components/schemas/Int",
            "description": "US cents a month."
          },
          "credit": {
            "$ref": "#/components/schemas/Int",
            "description": "Micro-dollars of credit each paid month; the unspent part ends with the month."
          },
          "turns": {
            "$ref": "#/components/schemas/Int",
            "description": "About how many tutor turns on Axad's model the month's credit pays for."
          },
          "limits": {
            "$ref": "#/components/schemas/Limits"
          }
        },
        "required": [
          "id",
          "tier",
          "price",
          "credit",
          "turns",
          "limits"
        ],
        "additionalProperties": false,
        "description": "A monthly plan: a Stripe subscription."
      },
      "PlanCheckout": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "const": "plan"
          },
          "plan": {
            "type": "string",
            "description": "A `Plan.id`."
          }
        },
        "required": [
          "kind",
          "plan"
        ],
        "additionalProperties": false,
        "description": "Subscribe to a plan, or change to it from another plan (Stripe prorates)."
      },
      "PortalResponse": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "additionalProperties": false,
        "description": "POST /billing/portal, with the site's cookie or the app's token: Stripe's page to change or cancel the plan; 409 without a Stripe plan."
      },
      "Profile": {
        "type": "object",
        "properties": {
          "support": {
            "type": "string",
            "description": "The language the learner reads and thinks in."
          },
          "voice": {
            "type": "string",
            "description": "ElevenLabs voice id; one multilingual voice speaks every language."
          },
          "languages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LanguageGoal"
            },
            "description": "One entry per language the learner's materials hold, other than `support`. The server adds an entry when a material first gets a new language."
          }
        },
        "required": [
          "support",
          "voice",
          "languages"
        ],
        "additionalProperties": false,
        "description": "Data, not code: any language the model knows. Codes are BCP 47: \"nl\", \"en\". The learner sets no language to learn: each material has its own languages."
      },
      "Question": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Id"
          },
          "n": {
            "$ref": "#/components/schemas/Int"
          },
          "ask": {
            "type": "string"
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "passage": {
            "$ref": "#/components/schemas/Id",
            "description": "The passage it asks about: the reader shows it under that passage. Absent: under the last passage."
          },
          "ask_media": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Media"
            },
            "description": "An exam question read aloud: the exam plays it after its case, then each option's sound."
          },
          "option_media": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Media"
              }
            },
            "description": "By option index, that option's media: its sound read aloud, or the pictures that make a picture option."
          },
          "answered": {
            "$ref": "#/components/schemas/AnswerResult",
            "description": "Present only after the learner answered: the key never leaves the server before."
          }
        },
        "required": [
          "id",
          "n",
          "ask",
          "options"
        ],
        "additionalProperties": false
      },
      "ReviewRequest": {
        "type": "object",
        "properties": {
          "grade": {
            "$ref": "#/components/schemas/Int",
            "minimum": 1,
            "maximum": 4
          }
        },
        "required": [
          "grade"
        ],
        "additionalProperties": false,
        "description": "POST /cards/:id/review. 1 again, 2 hard, 3 good, 4 easy."
      },
      "ReviewResponse": {
        "type": "object",
        "properties": {
          "card": {
            "$ref": "#/components/schemas/CardSummary"
          }
        },
        "required": [
          "card"
        ],
        "additionalProperties": false
      },
      "RuleMiss": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "fix": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "fix"
        ],
        "additionalProperties": false
      },
      "RunbookInfo": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "subtitle": {
            "type": "string",
            "description": "What it is, in English, one line."
          },
          "icon": {
            "type": "string",
            "description": "SF Symbol name for the app."
          },
          "place": {
            "$ref": "#/components/schemas/RunbookPlace",
            "description": "The learner's place in it for this language, once started."
          }
        },
        "required": [
          "id",
          "title",
          "subtitle",
          "icon"
        ],
        "additionalProperties": false
      },
      "RunbookList": {
        "type": "object",
        "properties": {
          "runbooks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RunbookInfo"
            }
          }
        },
        "required": [
          "runbooks"
        ],
        "additionalProperties": false
      },
      "RunbookPlace": {
        "type": "object",
        "properties": {
          "runbook": {
            "type": "string"
          },
          "lang": {
            "type": "string"
          },
          "step": {
            "$ref": "#/components/schemas/Int",
            "description": "0-based index of the current step; equal to `steps` when finished."
          },
          "steps": {
            "$ref": "#/components/schemas/Int"
          },
          "current": {
            "$ref": "#/components/schemas/RunbookStep",
            "description": "The current step; absent when finished."
          },
          "started_at": {
            "$ref": "#/components/schemas/Time"
          },
          "finished_at": {
            "$ref": "#/components/schemas/Time"
          }
        },
        "required": [
          "runbook",
          "lang",
          "step",
          "steps",
          "started_at"
        ],
        "additionalProperties": false
      },
      "RunbookRecord": {
        "type": "object",
        "properties": {
          "lang": {
            "type": "string"
          },
          "step": {
            "type": "string",
            "description": "The step id the outcome is for; a stale id is 409."
          },
          "outcome": {
            "type": "string",
            "enum": [
              "done",
              "skipped",
              "struggled"
            ]
          },
          "note": {
            "type": "string"
          }
        },
        "required": [
          "lang",
          "step",
          "outcome"
        ],
        "additionalProperties": false
      },
      "RunbookStart": {
        "type": "object",
        "properties": {
          "lang": {
            "type": "string"
          }
        },
        "required": [
          "lang"
        ],
        "additionalProperties": false
      },
      "RunbookStep": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "say": {
            "type": "string",
            "description": "For the tutor or the agent: what to do in this step, in its own words."
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The tools and widgets this step uses."
          },
          "done_when": {
            "type": "string",
            "description": "When the step is done."
          }
        },
        "required": [
          "id",
          "title",
          "say",
          "tools",
          "done_when"
        ],
        "additionalProperties": false
      },
      "SentencesRead": {
        "type": "object",
        "properties": {
          "sentences": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NumberedSentence"
            }
          },
          "total": {
            "$ref": "#/components/schemas/Int"
          }
        },
        "required": [
          "sentences",
          "total"
        ],
        "additionalProperties": false,
        "description": "GET /materials/:id/sentences?from=&to=&only=all|untouched: the read_material tool. Numbers from 1, at most 40."
      },
      "Settings": {
        "type": "object",
        "properties": {
          "ignore": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Bundle ids and domains that never become materials."
          }
        },
        "required": [
          "ignore"
        ],
        "additionalProperties": false
      },
      "Span": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Int"
        },
        "minItems": 2,
        "maxItems": 2,
        "description": "[start, end) character offsets."
      },
      "SpeechRequest": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "speakers": {
            "type": "boolean",
            "description": "true: `text` is a listening passage (`MaterialKind` \"listening\"). Each line is said by its speaker's voice, the label unsaid, with a short pause where the speaker changes; one audio, whose `words` count in the whole `text`. The speakers' voices are the server's, the same for every learner, so one recording serves them all. Absent: the profile's voice says the whole text."
          },
          "lang": {
            "type": "string",
            "description": "BCP 47 code of the text. With `speakers`, whose speaker labels and voices of the library data apply; absent, the language whose labels start the text's lines (400 when none or several do)."
          }
        },
        "required": [
          "text"
        ],
        "additionalProperties": false,
        "description": "POST /speech. The voice and model come from the profile and the server. A new recording is paid from the allowance (402 `AllowanceSpent` once it is spent); a saved one is free."
      },
      "SpeechResponse": {
        "type": "object",
        "properties": {
          "audio_url": {
            "type": "string",
            "description": "GET it with the same token: /v1/audio/<hash>."
          },
          "words": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpokenWord"
            }
          }
        },
        "required": [
          "audio_url",
          "words"
        ],
        "additionalProperties": false
      },
      "SpokenWord": {
        "type": "object",
        "properties": {
          "start": {
            "$ref": "#/components/schemas/Int"
          },
          "end": {
            "$ref": "#/components/schemas/Int"
          },
          "t0": {
            "type": "number"
          },
          "t1": {
            "type": "number"
          }
        },
        "required": [
          "start",
          "end",
          "t0",
          "t1"
        ],
        "additionalProperties": false,
        "description": "[start, end) characters of the word in the text; t0 and t1 in seconds."
      },
      "Starter": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "prompt": {
            "type": "string",
            "description": "The learner's message it sends, about the page (or the material) on screen."
          },
          "action": {
            "type": "string",
            "description": "An action of harness/actions.md it runs instead, as its menu would."
          },
          "primary": {
            "type": "boolean",
            "description": "The one button drawn as the main one."
          },
          "icon": {
            "type": "string",
            "description": "An SF Symbol name the app draws beside the label."
          }
        },
        "required": [
          "label"
        ],
        "additionalProperties": false,
        "description": "A button at the start of a chat: a first thing the learner can ask. From the library data (a lesson's front matter, an exam part in library.yaml), else the library's defaults. Exactly one of `prompt` and `action`."
      },
      "Subscription": {
        "type": "object",
        "properties": {
          "plan": {
            "type": "string",
            "description": "A `Plan.id`."
          },
          "status": {
            "type": "string",
            "description": "Stripe's status (\"active\", \"past_due\", …), or \"granted\" for a plan given without Stripe."
          },
          "period_end": {
            "$ref": "#/components/schemas/Time",
            "description": "The end of the paid period: the next renewal, or the end when `cancel_at_period_end`."
          },
          "cancel_at_period_end": {
            "type": "boolean"
          }
        },
        "required": [
          "plan",
          "status",
          "period_end",
          "cancel_at_period_end"
        ],
        "additionalProperties": false
      },
      "Tier": {
        "type": "string",
        "enum": [
          "free",
          "card",
          "plan10",
          "plan30",
          "plan50"
        ]
      },
      "Time": {
        "type": "string",
        "description": "RFC 3339, UTC."
      },
      "TopUp": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "price": {
            "$ref": "#/components/schemas/Int",
            "description": "US cents."
          },
          "credit": {
            "$ref": "#/components/schemas/Int",
            "description": "Micro-dollars of credit."
          }
        },
        "required": [
          "id",
          "price",
          "credit"
        ],
        "additionalProperties": false,
        "description": "Credit bought once; it never ends."
      },
      "TopUpCheckout": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "const": "topup"
          },
          "topup": {
            "type": "string",
            "description": "A `TopUp.id`."
          }
        },
        "required": [
          "kind",
          "topup"
        ],
        "additionalProperties": false
      },
      "TouchedSentence": {
        "type": "object",
        "properties": {
          "passage": {
            "$ref": "#/components/schemas/Id"
          },
          "sentence": {
            "$ref": "#/components/schemas/Int",
            "description": "Index into Passage.sentences."
          }
        },
        "required": [
          "passage",
          "sentence"
        ],
        "additionalProperties": false
      },
      "Usage": {
        "type": "object",
        "properties": {
          "spent": {
            "$ref": "#/components/schemas/Int"
          },
          "allowance": {
            "$ref": "#/components/schemas/Int"
          }
        },
        "required": [
          "spent",
          "allowance"
        ],
        "additionalProperties": false,
        "description": "Micro-dollars (USD × 10⁶): what the account's paid calls cost (model, speech, drawings), and what it may spend: the sum of its credit grants (the trial, a saved card's trial, each plan bought)."
      },
      "OAuthRegistration": {
        "type": "object",
        "description": "RFC 7591 client metadata. Public clients only: `token_endpoint_auth_method` is `none`.",
        "properties": {
          "redirect_uris": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "https, or http to a loopback address; at most 2000 characters each."
          },
          "client_name": {
            "type": "string"
          },
          "client_uri": {
            "type": "string"
          },
          "logo_uri": {
            "type": "string"
          },
          "token_endpoint_auth_method": {
            "const": "none"
          },
          "grant_types": {
            "type": "array",
            "items": {
              "enum": [
                "authorization_code",
                "refresh_token"
              ]
            }
          },
          "response_types": {
            "type": "array",
            "items": {
              "const": "code"
            }
          }
        },
        "required": [
          "redirect_uris"
        ]
      },
      "OAuthClient": {
        "type": "object",
        "properties": {
          "client_id": {
            "type": "string"
          },
          "client_id_issued_at": {
            "type": "integer"
          },
          "client_name": {
            "type": "string"
          },
          "redirect_uris": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "token_endpoint_auth_method": {
            "const": "none"
          },
          "grant_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "response_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "client_uri": {
            "type": "string"
          },
          "logo_uri": {
            "type": "string"
          }
        },
        "required": [
          "client_id",
          "client_id_issued_at",
          "client_name",
          "redirect_uris",
          "token_endpoint_auth_method",
          "grant_types",
          "response_types"
        ]
      },
      "OAuthTokenRequest": {
        "type": "object",
        "description": "Form-encoded. `authorization_code` needs `code`, `redirect_uri`, `client_id` and `code_verifier`; `refresh_token` needs `refresh_token` and `client_id`.",
        "properties": {
          "grant_type": {
            "enum": [
              "authorization_code",
              "refresh_token"
            ]
          },
          "code": {
            "type": "string"
          },
          "redirect_uri": {
            "type": "string"
          },
          "client_id": {
            "type": "string"
          },
          "code_verifier": {
            "type": "string"
          },
          "refresh_token": {
            "type": "string"
          },
          "scope": {
            "type": "string",
            "description": "Only `axad`."
          },
          "resource": {
            "type": "string",
            "description": "RFC 8707: the MCP server's URL."
          }
        },
        "required": [
          "grant_type"
        ]
      },
      "OAuthTokens": {
        "type": "object",
        "properties": {
          "access_token": {
            "type": "string"
          },
          "token_type": {
            "const": "Bearer"
          },
          "expires_in": {
            "type": "integer",
            "description": "Seconds: an access token lives 1 hour. A refresh token lives 60 days and works once."
          },
          "refresh_token": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          }
        },
        "required": [
          "access_token",
          "token_type",
          "expires_in",
          "refresh_token",
          "scope"
        ]
      },
      "OAuthRevokeRequest": {
        "type": "object",
        "description": "Form-encoded. Only the client a token was given to may revoke it.",
        "properties": {
          "token": {
            "type": "string"
          },
          "client_id": {
            "type": "string"
          }
        },
        "required": [
          "token",
          "client_id"
        ]
      },
      "OAuthError": {
        "type": "object",
        "description": "RFC 6749 §5.2.",
        "properties": {
          "error": {
            "type": "string"
          },
          "error_description": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}
