openapi: '3.1.0'
info:
    title: deadair
    version: main
    description: "The HTTP API of a deadair station. Every station is self-hosted, so the address is your own: the API is served under /api on the station's one published port. This document follows the main branch."
servers:
    - url: 'http://localhost:8080/api'
      description: 'A station on its default port. Substitute your own address.'
paths:
    '/activity':
        get:
            operationId: readActivity
            summary: 'Read activity'
            description: 'The feed, newest first, one page at a time'
            parameters:
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 200
                - name: before
                  in: query
                  required: false
                  description: 'Where the previous page ended. Opaque, and a keyset rather than an offset because rows arrive at the head continuously: an offset would re-show a row on every page as the feed grew under it. Pass back whatever `nextBefore` said and nothing else'
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                      description: 'Where the previous page ended. Opaque, and a keyset rather than an offset because rows arrive at the head continuously: an offset would re-show a row on every page as the feed grew under it. Pass back whatever `nextBefore` said and nothing else'
                - name: module
                  in: query
                  required: false
                  schema:
                      '$ref': '#/components/schemas/ActivityModule'
                - name: minSeverity
                  in: query
                  required: false
                  description: 'The floor, not the exact match: `warn` answers with warnings and faults. Absent is everything'
                  schema:
                      '$ref': '#/components/schemas/ActivitySeverity'
                      description: 'The floor, not the exact match: `warn` answers with warnings and faults. Absent is everything'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ActivityPage'
    '/art/breaks':
        get:
            operationId: listBreaks
            summary: 'List break artwork'
            description: 'Every kind the station holds a picture for'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BreakArtworkList'
    '/art/breaks/{kind}':
        post:
            operationId: replaceBreak
            summary: 'Replace break artwork'
            description: "Puts an operator's own picture behind a kind of break. The id does not change, so a URL already on the wire keeps working and the ETag is what says the picture moved"
            parameters:
                - name: kind
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 64
            requestBody:
                required: true
                content:
                    'multipart/form-data':
                        schema:
                            '$ref': '#/components/schemas/BreakArtworkUpload'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BreakArtworkList'
                '400':
                    description: 'Bad request'
                '413':
                    description: 'Response 413'
                '415':
                    description: 'Response 415'
        delete:
            operationId: revertBreak
            summary: 'Revert break artwork'
            description: 'Puts the picture this repository ships back. The shipped file is read at this moment rather than copied at install, so an upgrade that improved it is what comes back'
            parameters:
                - name: kind
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 64
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BreakArtworkList'
                '404':
                    description: 'Not found'
    '/art/source/{token}':
        get:
            operationId: getSourceArt
            summary: 'Get source art'
            description: 'The bytes of a cover the station fetches on first ask, addressed by its sealed source'
            parameters:
                - name: token
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 24
                      maxLength: 4096
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'image/jpeg':
                            schema:
                                type: string
                                format: binary
                        'image/png':
                            schema:
                                type: string
                                format: binary
                        'image/webp':
                            schema:
                                type: string
                                format: binary
                        'image/gif':
                            schema:
                                type: string
                                format: binary
                    headers:
                        cache-control:
                            schema:
                                type: string
                        etag:
                            schema:
                                type: string
                '304':
                    description: 'Response 304'
    '/art/source/{token}/{filename}':
        get:
            operationId: getSourceArtFile
            summary: 'Get source art file'
            description: 'The bytes of a cover the station fetches on first ask, under any filename'
            parameters:
                - name: token
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 24
                      maxLength: 4096
                - name: filename
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 3
                      maxLength: 64
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'image/jpeg':
                            schema:
                                type: string
                                format: binary
                        'image/png':
                            schema:
                                type: string
                                format: binary
                        'image/webp':
                            schema:
                                type: string
                                format: binary
                        'image/gif':
                            schema:
                                type: string
                                format: binary
                    headers:
                        cache-control:
                            schema:
                                type: string
                        etag:
                            schema:
                                type: string
                '304':
                    description: 'Response 304'
    '/art/{id}':
        get:
            operationId: getArt
            summary: 'Get art'
            description: 'The bytes of one cached image, addressed by its id alone'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'image/jpeg':
                            schema:
                                type: string
                                format: binary
                        'image/png':
                            schema:
                                type: string
                                format: binary
                        'image/webp':
                            schema:
                                type: string
                                format: binary
                        'image/gif':
                            schema:
                                type: string
                                format: binary
                    headers:
                        cache-control:
                            schema:
                                type: string
                        etag:
                            schema:
                                type: string
                '304':
                    description: 'Response 304'
    '/art/{id}/{filename}':
        get:
            operationId: getArtFile
            summary: 'Get art file'
            description: 'The bytes of one cached image, under any filename'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: filename
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 3
                      maxLength: 64
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'image/jpeg':
                            schema:
                                type: string
                                format: binary
                        'image/png':
                            schema:
                                type: string
                                format: binary
                        'image/webp':
                            schema:
                                type: string
                                format: binary
                        'image/gif':
                            schema:
                                type: string
                                format: binary
                    headers:
                        cache-control:
                            schema:
                                type: string
                        etag:
                            schema:
                                type: string
                '304':
                    description: 'Response 304'
    '/art/personas':
        get:
            operationId: listPortraits
            summary: 'List persona portraits'
            description: 'Every persona that has a portrait'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaPortraitList'
    '/art/personas/{personaId}':
        post:
            operationId: replacePortrait
            summary: 'Replace persona portrait'
            description: 'Puts a picture on a persona. A persona that already had one keeps its URL, so a player holding it picks up the new picture'
            parameters:
                - name: personaId
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'multipart/form-data':
                        schema:
                            '$ref': '#/components/schemas/PersonaPortraitUpload'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaPortraitList'
                '400':
                    description: 'Bad request'
                '413':
                    description: 'Response 413'
                '415':
                    description: 'Response 415'
        delete:
            operationId: removePortrait
            summary: 'Remove persona portrait'
            description: "Takes a persona's picture away. A player shows the record's cover instead"
            parameters:
                - name: personaId
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaPortraitList'
    '/auth/apikeys':
        get:
            operationId: list
            summary: 'List API keys'
            description: "The signed-in account's API keys, newest first, including revoked and expired ones so the list says what was withdrawn and when"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ApiKeyList'
        post:
            operationId: create
            summary: 'Create API key'
            description: 'Issue a new API key for the signed-in account. The token is in this response and nowhere else, ever. Once the account has a strong second factor, this needs one verified in the last five minutes'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ApiKeyCreate'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ApiKeyIssued'
    '/auth/apikeys/{id}/rotate':
        post:
            operationId: rotate
            summary: 'Rotate API key'
            description: 'Give a key a new token, so the old one stops working at once. The key keeps its name, scopes and expiry. Needs the same recent second factor as creating one'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ApiKeyIssued'
    '/auth/apikeys/{id}':
        delete:
            operationId: revoke
            summary: 'Revoke API key'
            description: 'Revoke a key. Every request made with it is refused from the next one on. The key stays in the list, marked revoked'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '204':
                    description: 'No content'
    '/auth/token':
        post:
            operationId: requestToken
            summary: 'Request token'
            description: 'Request authenticated token'
            requestBody:
                required: true
                content:
                    'application/x-www-form-urlencoded':
                        schema:
                            '$ref': '#/components/schemas/AuthenticationRequest'
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/AuthenticationRequest'
            security: []
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/AuthenticationTokenResponse'
    '/auth/login/register':
        post:
            operationId: registerLogin
            summary: 'Register login'
            description: 'Register a new login'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/AuthenticationRegistration'
            security: []
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/AuthenticationRegistration'
    '/auth/login/verify':
        post:
            operationId: verifyLoginRegistration
            summary: 'Verify login registration'
            description: 'Verify a login registration'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/AuthenticationRegistrationVerification'
            security: []
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/AuthenticationToken'
    '/auth/login/start':
        post:
            operationId: startLogin
            summary: 'Start login'
            description: 'Start a password-less login process'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/AuthenticationLoginStart'
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/AuthenticationLoginStartResponse'
    '/auth/login/oidc/providers':
        get:
            operationId: listOidcProviders
            summary: 'List sign-in providers'
            description: 'The identity providers the sign-in page offers beside a password, in the order the operator listed them. Empty when none is set up'
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                type: array
                                items:
                                    '$ref': '#/components/schemas/OidcProviderSummary'
    '/auth/factors':
        get:
            operationId: listFactors
            summary: 'List factors'
            description: 'List authentication factors'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                type: array
                                items:
                                    '$ref': '#/components/schemas/AuthenticationFactor'
    '/auth/factors/register':
        post:
            operationId: registerFactor
            summary: 'Register factor'
            description: 'Register an authentication factor'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/AuthenticationFactorRegistration'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/AuthenticationFactorRegistrationResponse'
    '/auth/password':
        put:
            operationId: setPassword
            summary: 'Set password'
            description: "Set or change the caller's own password. Needs the current one when there is one, unless a sign-in link was used in the last ten minutes, and a recent strong-factor verification once an authenticator or passkey is enrolled. Every other session of the account is signed out, and the account's email addresses are told."
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PasswordChange'
            responses:
                '204':
                    description: 'No content'
    '/auth/factors/verify':
        post:
            operationId: verifyFactorRegistration
            summary: 'Verify factor registration'
            description: 'Verify an authentication factor registration'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/AuthenticationFactorRegistrationVerification'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/AuthenticationToken'
    '/auth/factors/start':
        post:
            operationId: startFactorChallenge
            summary: 'Start factor challenge'
            description: 'Issue a factor verification challenge for a pending MFA round. Authenticated via the short-lived `mfa_challenge_id` in the body, not by session — this is the only /auth/factors/* route that does not require an authenticated session.'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/FactorChallengeStartRequest'
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/FactorChallengeStartResponse'
    '/auth/mfa/start':
        post:
            operationId: startStepUpChallenge
            summary: 'Start MFA challenge'
            description: 'Mint a fresh MFA challenge for the *current* authenticated session so the SPA can satisfy a `step_up_required` denial. Optionally filters eligible factors against an inbound `StepUpRequirement` hint. Returns `enrollment_required` when no enrolled factor matches the requirement so the SPA can route the user into enrollment instead of getting stuck.'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/StepUpStartRequest'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StepUpStartResponse'
    '/auth/factors/{method}/{methodId}':
        delete:
            operationId: removeFactor
            summary: 'Remove factor'
            description: "Remove one of the caller's own factors. Answered for `authenticator` and `oidc`, and only after a recent strong-factor verification: the same gate enrolment sits behind once a strong factor exists, so a stolen session cannot quietly switch the second factor off. Removing the last authenticator turns the sign-in challenge off for that account. A linked identity provider that is the account's only way to sign in is refused with 409."
            parameters:
                - name: method
                  in: path
                  required: true
                  schema:
                      '$ref': '#/components/schemas/AuthenticationFactorMethod'
                - name: methodId
                  in: path
                  required: true
                  schema:
                      type: string
                      maxLength: 255
            responses:
                '204':
                    description: 'No content'
    '/auth/logout':
        post:
            operationId: revokeCurrentSession
            summary: Logout
            description: "revoke the caller's current session (self sign-out). Deliberately carries no policy gate: signing out must always clear the browser's httpOnly refresh cookie, including for a caller whose access token has already expired. A 401 here would leave a 30-day refresh cookie behind that silently signs the user back in on the next page load. SessionsService revokes the session only when the caller is actually authenticated; an anonymous caller still gets 204 and a cleared cookie."
            security: []
            responses:
                '204':
                    description: 'No content'
    '/auth/session':
        get:
            operationId: readCurrentSession
            summary: 'Read session'
            description: 'Who the caller is and which platform roles they hold'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/AuthSession'
    '/catalog/artists':
        get:
            operationId: listArtists
            summary: 'List artists'
            description: 'Every artist the station has ingested, ordered by name'
            parameters:
                - name: page
                  in: query
                  required: false
                  description: 'The page number'
                  schema:
                      type: integer
                      minimum: 0
                      default: 0
                      description: 'The page number'
                - name: pageSize
                  in: query
                  required: false
                  description: 'The page size'
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 25
                      description: 'The page size'
                - name: sort
                  in: query
                  required: false
                  description: 'The sort order'
                  schema:
                      type: string
                      enum: [asc, desc]
                      default: desc
                      description: 'The sort order'
                - name: total
                  in: query
                  required: true
                  description: 'The total number of items'
                  schema:
                      type: integer
                      minimum: 0
                      readOnly: true
                      description: 'The total number of items'
                - name: search
                  in: query
                  required: false
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: sortBy
                  in: query
                  required: false
                  schema:
                      '$ref': '#/components/schemas/CatalogSort'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ArtistPage'
    '/catalog/artists/{id}':
        get:
            operationId: getArtist
            summary: 'Get artist'
            description: 'One artist. 404s on an id that was merged away, since reads never return merged rows'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Artist'
    '/catalog/artists/{id}/enrichment':
        get:
            operationId: getArtistEnrichment
            summary: 'Get artist enrichment'
            description: 'What every enrichment provider said about this artist, and when each of them said it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ArtistEnrichmentDetail'
    '/catalog/artists/{id}/albums':
        get:
            operationId: listAlbumsByArtist
            summary: 'List artist albums'
            description: 'The albums credited to one artist'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: page
                  in: query
                  required: false
                  description: 'The page number'
                  schema:
                      type: integer
                      minimum: 0
                      default: 0
                      description: 'The page number'
                - name: pageSize
                  in: query
                  required: false
                  description: 'The page size'
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 25
                      description: 'The page size'
                - name: sort
                  in: query
                  required: false
                  description: 'The sort order'
                  schema:
                      type: string
                      enum: [asc, desc]
                      default: desc
                      description: 'The sort order'
                - name: total
                  in: query
                  required: true
                  description: 'The total number of items'
                  schema:
                      type: integer
                      minimum: 0
                      readOnly: true
                      description: 'The total number of items'
                - name: search
                  in: query
                  required: false
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: sortBy
                  in: query
                  required: false
                  schema:
                      '$ref': '#/components/schemas/CatalogSort'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/AlbumPage'
    '/catalog/artists/{id}/rating':
        put:
            operationId: rateArtist
            summary: 'Rate artist'
            description: 'What the station thinks of this artist. A dislike here excludes every record they are credited on'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/RateInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Artist'
    '/catalog/albums':
        get:
            operationId: listAlbums
            summary: 'List albums'
            parameters:
                - name: page
                  in: query
                  required: false
                  description: 'The page number'
                  schema:
                      type: integer
                      minimum: 0
                      default: 0
                      description: 'The page number'
                - name: pageSize
                  in: query
                  required: false
                  description: 'The page size'
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 25
                      description: 'The page size'
                - name: sort
                  in: query
                  required: false
                  description: 'The sort order'
                  schema:
                      type: string
                      enum: [asc, desc]
                      default: desc
                      description: 'The sort order'
                - name: total
                  in: query
                  required: true
                  description: 'The total number of items'
                  schema:
                      type: integer
                      minimum: 0
                      readOnly: true
                      description: 'The total number of items'
                - name: search
                  in: query
                  required: false
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: sortBy
                  in: query
                  required: false
                  schema:
                      '$ref': '#/components/schemas/CatalogSort'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/AlbumPage'
    '/catalog/albums/{id}':
        get:
            operationId: getAlbum
            summary: 'Get album'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Album'
    '/catalog/albums/{id}/enrichment':
        get:
            operationId: getAlbumEnrichment
            summary: 'Get album enrichment'
            description: "The record's own enrichment: the label, pressing and cover belong to the release, not to a track on it"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/AlbumEnrichmentDetail'
    '/catalog/albums/{id}/tracks':
        get:
            operationId: listTracksByAlbum
            summary: 'List album tracks'
            description: "One album's tracks"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: page
                  in: query
                  required: false
                  description: 'The page number'
                  schema:
                      type: integer
                      minimum: 0
                      default: 0
                      description: 'The page number'
                - name: pageSize
                  in: query
                  required: false
                  description: 'The page size'
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 25
                      description: 'The page size'
                - name: sort
                  in: query
                  required: false
                  description: 'The sort order'
                  schema:
                      type: string
                      enum: [asc, desc]
                      default: desc
                      description: 'The sort order'
                - name: total
                  in: query
                  required: true
                  description: 'The total number of items'
                  schema:
                      type: integer
                      minimum: 0
                      readOnly: true
                      description: 'The total number of items'
                - name: search
                  in: query
                  required: false
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: sortBy
                  in: query
                  required: false
                  schema:
                      '$ref': '#/components/schemas/TrackSort'
                - name: state
                  in: query
                  required: false
                  schema:
                      '$ref': '#/components/schemas/TrackState'
                - name: analyzer
                  in: query
                  required: false
                  description: "Only records this analysis plugin measured, or tried to and failed. The selector for measuring a detector's records again"
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                      description: "Only records this analysis plugin measured, or tried to and failed. The selector for measuring a detector's records again"
                - name: measureFailure
                  in: query
                  required: false
                  description: 'Only records whose measurement failed this way'
                  schema:
                      '$ref': '#/components/schemas/MeasureFailure'
                      description: 'Only records whose measurement failed this way'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TrackPage'
    '/catalog/albums/{id}/rating':
        put:
            operationId: rateAlbum
            summary: 'Rate album'
            description: 'What the station thinks of this record. A dislike here excludes every track on it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/RateInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Album'
    '/catalog/tracks/{id}':
        get:
            operationId: getTrack
            summary: 'Get track'
            description: 'One record and everything it has accumulated: its copies, its bytes, its measurement, what it has aired'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TrackDetail'
    '/catalog/tracks/{id}/audio':
        delete:
            operationId: clearAudio
            summary: 'Clear track audio'
            description: "Drop the station's own copies of this record. The next play fetches them again"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TrackClearResult'
                '409':
                    description: Conflict
    '/catalog/tracks/{id}/analysis':
        delete:
            operationId: clearAnalysis
            summary: 'Clear track analysis'
            description: 'Forget the measurement, so the walk takes it again'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TrackClearResult'
    '/catalog/tracks/{id}/vocal-markers':
        get:
            operationId: getVocalMarkers
            summary: 'Get vocal markers'
            description: "Where the singing starts and stops on one record, from an operator's correction or its timed lyrics"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/VocalMarkersDetail'
        put:
            operationId: setVocalMarkers
            summary: 'Set vocal markers'
            description: 'Correct where the singing starts and stops, over whatever the lyrics say'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/VocalMarkersInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/VocalMarkersDetail'
        delete:
            operationId: clearVocalMarkers
            summary: 'Clear vocal markers'
            description: "Drop the correction, so the record's timed lyrics decide again"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/VocalMarkersDetail'
    '/catalog/tracks/{id}/lyrics':
        get:
            operationId: getTrackLyrics
            summary: 'Get track lyrics'
            description: 'The words of one record, from the lyrics source the station believes, with the timing of each line when that source has it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TrackLyrics'
    '/catalog/tracks/{id}/lyrics/sources':
        get:
            operationId: listTrackLyricsSources
            summary: 'List track lyrics sources'
            description: 'What every lyrics source answered for one record, in the order the station believes them'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TrackLyricsSources'
    '/catalog/tracks/{id}/retry':
        post:
            operationId: retryAudio
            summary: 'Retry track audio'
            description: "Try this record's copies again now, rather than when the backoff says"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TrackClearResult'
    '/catalog/tracks/{id}/offer':
        post:
            operationId: offerAudio
            summary: 'Offer track copies again'
            description: 'Put copies a provider refused back on offer, and clear their backoff so they are tried now'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TrackClearResult'
    '/catalog/tracks/{id}/enrichment':
        get:
            operationId: getTrackEnrichment
            summary: 'Get track enrichment'
            description: 'What the providers said about one recording, including everything no canonical column holds'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TrackEnrichmentDetail'
        delete:
            operationId: clearEnrichment
            summary: 'Clear track enrichment'
            description: 'Forget what the providers said, so the enrichment pass asks again'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: provider
                  in: query
                  required: false
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TrackClearResult'
    '/catalog/tracks':
        get:
            operationId: listTracks
            summary: 'List tracks'
            description: 'Every track, flat. The only way to answer "do we have this song?" without knowing its artist'
            parameters:
                - name: page
                  in: query
                  required: false
                  description: 'The page number'
                  schema:
                      type: integer
                      minimum: 0
                      default: 0
                      description: 'The page number'
                - name: pageSize
                  in: query
                  required: false
                  description: 'The page size'
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 25
                      description: 'The page size'
                - name: sort
                  in: query
                  required: false
                  description: 'The sort order'
                  schema:
                      type: string
                      enum: [asc, desc]
                      default: desc
                      description: 'The sort order'
                - name: total
                  in: query
                  required: true
                  description: 'The total number of items'
                  schema:
                      type: integer
                      minimum: 0
                      readOnly: true
                      description: 'The total number of items'
                - name: search
                  in: query
                  required: false
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: sortBy
                  in: query
                  required: false
                  schema:
                      '$ref': '#/components/schemas/TrackSort'
                - name: state
                  in: query
                  required: false
                  schema:
                      '$ref': '#/components/schemas/TrackState'
                - name: analyzer
                  in: query
                  required: false
                  description: "Only records this analysis plugin measured, or tried to and failed. The selector for measuring a detector's records again"
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                      description: "Only records this analysis plugin measured, or tried to and failed. The selector for measuring a detector's records again"
                - name: measureFailure
                  in: query
                  required: false
                  description: 'Only records whose measurement failed this way'
                  schema:
                      '$ref': '#/components/schemas/MeasureFailure'
                      description: 'Only records whose measurement failed this way'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TrackPage'
    '/catalog/tracks/{id}/rating':
        put:
            operationId: rateTrack
            summary: 'Rate track'
            description: 'What the station thinks of this song, which is the narrowest thing an opinion can be about'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/RateInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Track'
    '/catalog/artists/{id}/suspension':
        put:
            operationId: suspendArtist
            summary: 'Suspend artist'
            description: 'Keep this artist, and every record they are credited on, off the station for a number of days. Nothing already in the running order is taken out; a suspension stops it being chosen again, and lapses by itself'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/SuspendInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Artist'
        delete:
            operationId: liftArtist
            summary: 'Lift artist suspension'
            description: 'End a suspension now. Something not suspended is answered as it stands rather than refused'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Artist'
    '/catalog/albums/{id}/suspension':
        put:
            operationId: suspendAlbum
            summary: 'Suspend album'
            description: 'Keep this release, and every record on it, off the station for a number of days. Nothing already in the running order is taken out; a suspension stops it being chosen again, and lapses by itself'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/SuspendInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Album'
        delete:
            operationId: liftAlbum
            summary: 'Lift album suspension'
            description: 'End a suspension now. Something not suspended is answered as it stands rather than refused'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Album'
    '/catalog/tracks/{id}/suspension':
        put:
            operationId: suspendTrack
            summary: 'Suspend track'
            description: 'Keep this record off the station for a number of days. Nothing already in the running order is taken out; a suspension stops it being chosen again, and lapses by itself'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/SuspendInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Track'
        delete:
            operationId: liftTrack
            summary: 'Lift track suspension'
            description: 'End a suspension now. Something not suspended is answered as it stands rather than refused'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Track'
    '/catalog/similarity':
        get:
            operationId: getGraph
            summary: 'Get similarity graph'
            description: 'Who the similarity sources say resembles whom, as the station has stored it. Without `around`, the best-ranked edges of the whole store; with it, the neighbourhood of one artist'
            parameters:
                - name: around
                  in: query
                  required: false
                  description: 'A catalog artist to centre on. Absent draws the whole store, best-ranked edges first'
                  schema:
                      type: string
                      format: uuid
                      description: 'A catalog artist to centre on. Absent draws the whole store, best-ranked edges first'
                - name: depth
                  in: query
                  required: false
                  description: 'How many steps out from `around`, following edges either way. Ignored without it'
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 2
                      default: 1
                      description: 'How many steps out from `around`, following edges either way. Ignored without it'
                - name: library
                  in: query
                  required: false
                  description: 'Only artists the catalog holds, on both ends of every edge'
                  schema:
                      type: boolean
                      default: false
                      description: 'Only artists the catalog holds, on both ends of every edge'
                - name: limit
                  in: query
                  required: false
                  description: 'The most edges answered'
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 2000
                      default: 500
                      description: 'The most edges answered'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/SimilarityGraph'
    '/charts':
        get:
            operationId: readCharts
            summary: 'List charts'
            description: 'Every chart every installed chart plugin currently offers'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationChartList'
    '/charts/{id}':
        get:
            operationId: readChart
            summary: 'Read chart'
            description: "One chart's records, ranked"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 400
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                - name: date
                  in: query
                  required: false
                  description: 'Which edition, as `YYYY-MM-DD`. Absent means the current one, and a service that keeps no history answers with the current one either way'
                  schema:
                      type: string
                      maxLength: 10
                      description: 'Which edition, as `YYYY-MM-DD`. Absent means the current one, and a service that keeps no history answers with the current one either way'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ChartPage'
    '/breaks/kinds':
        get:
            operationId: listBreakKinds
            summary: 'List break kinds'
            description: 'Every kind of break you have written, switched on or not, in your own order'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BreakKindList'
        post:
            operationId: createBreakKind
            summary: 'Create break kind'
            description: 'Writes a new kind of break. Nothing airs it until it is switched on and a band on the format clock names it'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/BreakKind'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BreakKindList'
    '/breaks/kinds/{id}':
        put:
            operationId: update
            summary: 'Update break kind'
            description: 'Rewrites one kind of break. Its key cannot change. A break already written keeps the words it was given'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/BreakKind'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BreakKindList'
        delete:
            operationId: remove
            summary: 'Delete break kind'
            description: 'Removes a kind of break. Refused while a band on the format clock still names it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BreakKindList'
    '/breaks/kinds/export':
        get:
            operationId: exportAll
            summary: 'Export break kinds'
            description: 'Every kind of break you have written, as one file'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BreakKindFile'
                    headers:
                        Content-Disposition:
                            schema:
                                type: string
    '/breaks/kinds/{id}/export':
        get:
            operationId: exportOne
            summary: 'Export break kind'
            description: 'One kind of break, as a file'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BreakKindFile'
                    headers:
                        Content-Disposition:
                            schema:
                                type: string
                '404':
                    description: 'Not found'
    '/breaks/kinds/import/preview':
        post:
            operationId: preview
            summary: 'Preview break kind import'
            description: 'Reads a file and reports what importing it would create, rewrite, skip and refuse. Writes nothing'
            parameters:
                - name: replace
                  in: query
                  required: false
                  schema:
                      type: array
                      items:
                          type: string
                          minLength: 1
                          maxLength: 60
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/BreakKindFile'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BreakKindImportPlan'
    '/breaks/kinds/import':
        post:
            operationId: import
            summary: 'Import break kinds'
            description: 'Writes a file into this station and answers with what it did. Every kind it writes arrives switched off'
            parameters:
                - name: replace
                  in: query
                  required: false
                  schema:
                      type: array
                      items:
                          type: string
                          minLength: 1
                          maxLength: 60
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/BreakKindFile'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BreakKindImportResult'
    '/clock/export':
        get:
            operationId: exportPack
            summary: 'Export clock'
            description: "This station's format clock as one file, to hand to another station"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ClockPack'
    '/clock/import/preview':
        post:
            operationId: previewImport
            summary: 'Preview clock import'
            description: 'Reads a file and reports what importing it would add, skip and leave out. Writes nothing'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ClockPack'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PackImportPlan'
    '/clock/import':
        post:
            operationId: importPack
            summary: 'Import clock'
            description: "Adds the bands in a file after this station's own, switched off, with any subject they need. Changes nothing the station already has"
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ClockPack'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ClockImportResult'
    '/clock/bands':
        get:
            operationId: listClockBands
            summary: 'List clock bands'
            description: "Every band on this station's clock, including the ones switched off, in the operator's own order"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ClockBandList'
        post:
            operationId: createClockBand
            summary: 'Create clock band'
            description: 'Adds a band. It claims its first boundary on the next commit pass'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ClockBand'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ClockBandList'
    '/clock/bands/{id}':
        put:
            operationId: updateClockBand
            summary: 'Update clock band'
            description: 'Rewrites one band. Breaks it has already planted stay where they are: the running order is the memory'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ClockBand'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ClockBandList'
        delete:
            operationId: deleteClockBand
            summary: 'Delete clock band'
            description: 'Removes a band, which costs it the boundaries it had not claimed yet and nothing else'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ClockBandList'
    '/direction':
        get:
            operationId: read
            summary: 'Read the talk direction'
            description: 'The direction in force, if any'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TalkDirectionReading'
        put:
            operationId: direct
            summary: 'Direct the presenters'
            description: 'Gives the presenters a line to lean on for a number of hours, replacing any direction already in force. Breaks already written are not rewritten'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/TalkDirectionInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TalkDirectionReading'
        delete:
            operationId: stop
            summary: 'Stop directing the presenters'
            description: 'Ends the direction now. Breaks already written are not rewritten'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TalkDirectionReading'
    '/director/air':
        get:
            operationId: getAir
            summary: 'Get station air'
            description: 'What the station is airing, and whether it is driving at all'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationAir'
        post:
            operationId: putOnAir
            summary: 'Put the station on air'
            description: 'Puts the station on air, building the running order from a playlist read at this moment. What is playing finishes: changing the programming is not a reason to cut a listener off mid-track'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PutOnAirInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationAir'
        patch:
            operationId: setAirMode
            summary: 'Set the air mode'
            description: 'Changes what puts the station on air: only while somebody is listening, or whenever there is a programme. Takes effect at once rather than at the next boundary'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/SetStationAirInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationAir'
    '/director/air/order':
        get:
            operationId: getOrder
            summary: 'Get the running order'
            description: 'The live running order, item by item, each saying where it has got to'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationOrder'
    '/director/air/persona':
        put:
            operationId: recast
            summary: 'Recast the broadcast'
            description: 'Changes who is presenting this broadcast. Breaks already written for it in the outgoing character are written again in the new one'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/SetStationHostInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationOrder'
    '/director/air/extend':
        post:
            operationId: extendOrder
            summary: 'Extend the running order'
            description: 'Queues a refill and returns at once. Generating a set walks the catalog, and an operator pressing a button should not be held open through it'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ExtendStationInput'
            responses:
                '202':
                    description: 'Response 202'
    '/director/air/replan':
        post:
            operationId: replanOrder
            summary: 'Replan the running order'
            description: 'Queues a fresh set for everything the player is not already holding, and swaps it in once it exists. The old tail keeps playing until then, because emptying the running order first would take the station off air while the model was still choosing'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ReplanStationInput'
            responses:
                '202':
                    description: 'Response 202'
    '/director/air/breaks':
        post:
            operationId: requestBreak
            summary: 'Request a break'
            description: 'Asks the station to say something now rather than when the format clock next calls for it: the news, the weather, a word from the host. The director decides where it goes. A decline is answered rather than thrown, with the station''s reason, because "breaks are off" and "it was asked for a moment ago" are things the person pressing the button needs to read'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/RequestStationBreakInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationBreakRequest'
    '/director/route/preview':
        post:
            operationId: previewAnArtistRoute
            summary: 'Preview an artist route'
            description: 'Finds a route from one artist to another through artists the library holds, and says how each stop connects to the one before. Nothing goes on air: this is what a route would be'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/RoutePreviewInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ArtistRoute'
    '/director/air/hold':
        patch:
            operationId: holdAgainstSchedule
            summary: 'Hold the station against the schedule'
            description: 'Holds the running order against the schedule, so a block boundary does not take back what an operator put on. A takeover is otherwise stamped with whichever slot was in force and is replaced when that block ends, which is correct and gives nobody any warning'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/HoldStationInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationAir'
        delete:
            operationId: releaseToSchedule
            summary: 'Release the station to the schedule'
            description: 'Releases a hold, so the next block boundary changes the station over as it ordinarily would. A station with no hold is unchanged rather than refused'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationAir'
    '/director/air/quiet':
        put:
            operationId: keepQuiet
            summary: 'Keep the station quiet'
            description: "Keeps the station's own breaks off the air for the next so many records, and takes out the ones already planned across them. Asking again replaces the count"
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/QuietStationInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationAir'
        delete:
            operationId: endQuiet
            summary: 'End the quiet spell'
            description: 'Ends a quiet spell now, so the station talks again at its next break. A station that is not quiet is unchanged rather than refused'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationAir'
    '/director/air/shuffle':
        post:
            operationId: shuffleOrder
            summary: 'Shuffle the running order'
            description: "Shuffles the records not yet handed to the player, and plants the breaks again around the new sequence. The head is already in the player's hands and is left alone"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationOrder'
    '/director/air/segments':
        post:
            operationId: addSegmentToOrder
            summary: 'Add a segment to the running order'
            description: 'Puts something the station says into the running order. A segment with no audio yet is refused here rather than accepted and skipped when it comes round, so an operator is told why it cannot play'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/AddStationSegmentInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationOrder'
    '/director/air/tracks':
        post:
            operationId: addTrackToOrder
            summary: 'Add a record to the running order'
            description: 'Puts a catalog record into the running order. A record whose audio is not local yet is refused here rather than accepted and held or skipped when its slot comes round, so an operator asking for a specific one is told why it cannot play. What makes this worth having on its own is undo: dropping an item only ever marks a segment, but a track is spliced out of the order entirely, so nothing could put one back until this existed'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/AddStationTrackInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationOrder'
    '/director/air/items/{itemId}':
        patch:
            operationId: moveOrderItem
            summary: 'Move a running order item'
            description: 'Moves an item. A position already handed to the player is refused rather than clamped'
            parameters:
                - name: itemId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/MoveStationItemInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationOrder'
        delete:
            operationId: removeOrderItem
            summary: 'Remove a running order item'
            description: 'Drops an item that has not been handed to the player yet'
            parameters:
                - name: itemId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationOrder'
    '/director/air/items/{itemId}/rewrite':
        post:
            operationId: rewriteOrderItem
            summary: 'Write a running order break again'
            description: 'Writes a break still to come again from nothing: its words, and any audio already made of them, are thrown away and the station writes it afresh as its slot nears, under whoever is presenting by then. Reaches a break that failed to be written, which nothing else retries, so a break that had nothing to say can be asked again after the phrasings change or the model is switched on. Only a break the station wrote itself and has not handed to the player, and never one turn of a programme on its own'
            parameters:
                - name: itemId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationOrder'
    '/director/air/items/{itemId}/skip-to':
        post:
            operationId: skipToOrderItem
            summary: 'Skip to a running order item'
            description: 'Makes a record further down the running order the next thing heard. Everything still to come in front of it is marked skipped, anything the player was already holding from in front of it is taken back, and the item on air is cut. Only a record can be skipped to, and only one still to come'
            parameters:
                - name: itemId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationOrder'
    '/rules':
        get:
            operationId: listNeverPlayRules
            summary: 'List never-play rules'
            description: 'Every never-play rule on this station, newest first, each saying whether it holds right now'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BlockRuleList'
        post:
            operationId: add
            summary: 'Add a never-play rule'
            description: 'Adds a rule. It holds from the next record the station chooses'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/BlockRule'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BlockRuleList'
    '/rules/steer':
        get:
            operationId: readSteer
            summary: 'Read the genre steer'
            description: 'The lean in force, if any'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/GenreSteerReading'
        put:
            operationId: steer
            summary: 'Steer toward genres'
            description: 'Leans the station toward some genres for a number of hours, replacing any lean already in force'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/GenreSteerInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/GenreSteerReading'
        delete:
            operationId: stopSteering
            summary: 'Stop steering'
            description: 'Ends the lean now'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/GenreSteerReading'
    '/rules/{id}':
        put:
            operationId: change
            summary: 'Change a never-play rule'
            description: 'Replaces a rule'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/BlockRule'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BlockRuleList'
                '404':
                    description: 'Not found'
        delete:
            operationId: removeANeverPlayRule
            summary: 'Remove a never-play rule'
            description: 'Removes a rule'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/BlockRuleList'
                '404':
                    description: 'Not found'
    '/events/types':
        get:
            operationId: listTypes
            summary: 'List event types'
            description: 'Every kind of event the station sends, each with an example of what a destination receives'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/EventTypeList'
    '/events/destinations':
        get:
            operationId: listEventDestinations
            summary: 'List event destinations'
            description: 'Every event destination, oldest first'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/EventDestinationList'
        post:
            operationId: createEventDestination
            summary: 'Create event destination'
            description: 'Add an event destination. The answer carries its signing secret, which is not shown again'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/EventDestinationCreate'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/EventDestinationCreated'
    '/events/destinations/{id}':
        patch:
            operationId: updateEventDestination
            summary: 'Update event destination'
            description: "Change an event destination's name, address, or whether it is on"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/EventDestinationUpdate'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/EventDestination'
        delete:
            operationId: deleteEventDestination
            summary: 'Delete event destination'
            description: 'Remove an event destination and its delivery log'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '204':
                    description: 'No content'
    '/events/destinations/{id}/secret':
        post:
            operationId: rotateSecret
            summary: 'Rotate event destination secret'
            description: 'Make a new signing secret for a destination. The old one stops working at once'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/EventDestinationSecret'
    '/events/destinations/{id}/test':
        post:
            operationId: test
            summary: 'Test event destination'
            description: 'Send a destination a test event now, and say what it answered. Sent even when the destination is off'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/EventTestResult'
    '/events/destinations/{id}/deliveries':
        get:
            operationId: listDeliveries
            summary: 'List event deliveries'
            description: "A destination's latest delivery attempts, newest first"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/EventDeliveryList'
    '/history':
        get:
            operationId: readHistory
            summary: 'Read history'
            description: 'What the station played, newest first, one page at a time'
            parameters:
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 200
                - name: before
                  in: query
                  required: false
                  description: 'Where the previous page ended. Opaque, and a keyset rather than an offset because rows arrive at the head continuously: an offset would re-show a row on every page as the station kept playing under it. Pass back whatever `nextBefore` said and nothing else'
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                      description: 'Where the previous page ended. Opaque, and a keyset rather than an offset because rows arrive at the head continuously: an offset would re-show a row on every page as the station kept playing under it. Pass back whatever `nextBefore` said and nothing else'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/HistoryPage'
    '/history/as-run':
        get:
            operationId: readAsRun
            summary: 'Read as-run log'
            description: 'The as-run log, newest first, one page at a time'
            parameters:
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 500
                - name: before
                  in: query
                  required: false
                  description: 'Where the previous page ended. Opaque: pass back whatever `nextBefore` said'
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                      description: 'Where the previous page ended. Opaque: pass back whatever `nextBefore` said'
                - name: until
                  in: query
                  required: false
                  description: 'Start reading from this moment back, to jump to an hour without paging to it. Ignored when `before` is sent'
                  schema:
                      type: string
                      format: date-time
                      description: 'Start reading from this moment back, to jump to an hour without paging to it. Ignored when `before` is sent'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/AsRunPage'
    '/console/language':
        get:
            operationId: choice
            summary: 'Get my console language'
            description: 'The language you chose for the console, if you chose one'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ConsoleLanguageChoice'
        put:
            operationId: choose
            summary: 'Choose my console language'
            description: 'Chooses the language your console is shown in, or, without one, goes back to following the browser'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ConsoleLanguageChoice'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ConsoleLanguageChoice'
    '/console/languages':
        get:
            operationId: listConsoleLanguages
            summary: 'List console languages'
            description: 'Every language this station holds a pack for, without the strings'
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ConsoleLanguageList'
    '/console/languages/{locale}':
        get:
            operationId: get
            summary: 'Get console language'
            description: "One language's pack, strings and all, as it was imported"
            parameters:
                - name: locale
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 2
                      maxLength: 35
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ConsoleLanguagePack'
        put:
            operationId: importConsoleLanguage
            summary: 'Import console language'
            description: "Installs a language pack, replacing any pack already installed for the language. The tag in the path must be the pack's own"
            parameters:
                - name: locale
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 2
                      maxLength: 35
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ConsoleLanguagePack'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ConsoleLanguageList'
        delete:
            operationId: removeConsoleLanguage
            summary: 'Remove console language'
            description: 'Removes a language. Anybody who had chosen it sees English'
            parameters:
                - name: locale
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 2
                      maxLength: 35
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ConsoleLanguageList'
    '/messaging/links':
        get:
            operationId: listMessagingLinks
            summary: 'List messaging links'
            description: 'The chat accounts linked to the signed-in account'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/MessagingLinkList'
    '/messaging/links/code':
        post:
            operationId: createCode
            summary: 'Create messaging link code'
            description: 'A new one-time code for linking a chat account. It replaces any earlier code and stops working after ten minutes'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/MessagingLinkCode'
    '/messaging/links/{pluginId}/{platformUserId}':
        delete:
            operationId: removeMessagingLink
            summary: 'Remove messaging link'
            description: 'Unlink a chat account. Its operator commands are refused from the next one on'
            parameters:
                - name: pluginId
                  in: path
                  required: true
                  schema:
                      type: string
                      maxLength: 200
                - name: platformUserId
                  in: path
                  required: true
                  schema:
                      type: string
                      maxLength: 200
            responses:
                '204':
                    description: 'No content'
    '/metrics/series':
        get:
            operationId: readSeries
            summary: 'Read metric series'
            description: 'Trends over a range, at minute resolution for two days or less and hourly beyond'
            parameters:
                - name: names
                  in: query
                  required: true
                  description: 'Comma-separated metric names, at most twenty: `station.listeners,work.job.ms`'
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 1000
                      description: 'Comma-separated metric names, at most twenty: `station.listeners,work.job.ms`'
                - name: from
                  in: query
                  required: true
                  description: 'The start of the range, inclusive'
                  schema:
                      type: string
                      format: date-time
                      description: 'The start of the range, inclusive'
                - name: to
                  in: query
                  required: true
                  description: 'The end of the range, exclusive. At most four hundred days after `from`'
                  schema:
                      type: string
                      format: date-time
                      description: 'The end of the range, exclusive. At most four hundred days after `from`'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/MetricSeriesPage'
    '/metrics/names':
        get:
            operationId: readNames
            summary: 'Read metric names'
            description: 'Every metric the station holds, with its labels and when it was last measured'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/MetricNames'
    '/narrations/series':
        get:
            operationId: listSeries
            summary: 'List series'
            description: 'Every series every installed narration plugin offers'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationSeriesList'
    '/narrations/pieces':
        get:
            operationId: readPieces
            summary: 'List pieces'
            description: "The pieces the station knows about, in their series' own order, with what it has done with each"
            parameters:
                - name: seriesId
                  in: query
                  required: false
                  description: "One series' pieces in its own order, or absent for every series' newest first"
                  schema:
                      type: string
                      maxLength: 400
                      description: "One series' pieces in its own order, or absent for every series' newest first"
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 500
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationPiecePage'
    '/narrations/pieces/{id}/render':
        post:
            operationId: requestRender
            summary: 'Render piece'
            description: 'Has one piece spoken now, rather than waiting for its slot to come near'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationPiece'
    '/narrations/refresh':
        post:
            operationId: requestRefresh
            summary: 'Refresh narrations'
            description: 'Reads every series again, in the background, rather than waiting for the next scheduled refresh'
    '/news/feeds':
        get:
            operationId: readFeeds
            summary: 'List feeds'
            description: 'Every feed every installed news plugin currently offers'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationFeedList'
    '/news':
        get:
            operationId: readNews
            summary: 'Read news'
            description: 'Published entries, newest first'
            parameters:
                - name: feedId
                  in: query
                  required: false
                  description: 'One feed, or absent for every feed the station can see, merged newest first'
                  schema:
                      type: string
                      maxLength: 400
                      description: 'One feed, or absent for every feed the station can see, merged newest first'
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                - name: since
                  in: query
                  required: false
                  description: 'Only entries published after this ISO-8601 instant'
                  schema:
                      type: string
                      maxLength: 40
                      description: 'Only entries published after this ISO-8601 instant'
                - name: headlinesOnly
                  in: query
                  required: false
                  description: "Answer with headlines and teasers alone, skipping the story behind each one. A story is read from the publisher's own page, which is by far the slowest thing this route does, so a caller that will not use `content` should say so"
                  schema:
                      type: boolean
                      description: "Answer with headlines and teasers alone, skipping the story behind each one. A story is read from the publisher's own page, which is by far the slowest thing this route does, so a caller that will not use `content` should say so"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/NewsPage'
    '/nowplaying':
        get:
            operationId: getNowPlaying
            summary: 'Get now playing'
            description: 'What is on air right now. Answers 200 with `onAir: false` when the station is quiet, so a device polling this treats silence as an answer rather than an error'
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/NowPlaying'
    '/nowplaying/lyrics':
        get:
            operationId: getNowPlayingLyrics
            summary: 'Get now playing lyrics'
            description: 'The words of the record on air, with what a player needs to follow along line by line'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/NowPlayingLyrics'
    '/auth/oauth/authorize/context':
        post:
            operationId: describe
            summary: 'Describe authorization request'
            description: "Validate an app's authorization request for the consent page, and stash it for the signed-in person. A POST because it stashes: what is approved is exactly what was validated here"
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OAuthAuthorizationQuery'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OAuthAuthorizationContextResult'
    '/auth/oauth/authorize/approve':
        post:
            operationId: approve
            summary: 'Approve authorization request'
            description: 'Let the app act as the signed-in person, as far as the chosen scopes allow. Once the account has a strong second factor, this needs one verified in the last five minutes'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OAuthAuthorizationApproval'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OAuthAuthorizationOutcome'
    '/auth/oauth/authorize/deny':
        post:
            operationId: deny
            summary: 'Deny authorization request'
            description: 'Turn the app away. It is told the person said no'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OAuthAuthorizationDecision'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OAuthAuthorizationOutcome'
    '/auth/oauth/clients':
        get:
            operationId: listOAuthClients
            summary: 'List OAuth clients'
            description: 'Every app registered with the station, by an operator or by itself'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OAuthClientList'
        post:
            operationId: createOAuthClient
            summary: 'Create OAuth client'
            description: 'Register an app by hand. The secret, for an app that keeps one, is in this response and nowhere else'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OAuthClientCreate'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OAuthClientIssued'
    '/auth/oauth/clients/{clientId}':
        delete:
            operationId: revokeOAuthClient
            summary: 'Revoke OAuth client'
            description: "Withdraw an app. Every person's approval of it ends, and so does every token it holds"
            parameters:
                - name: clientId
                  in: path
                  required: true
                  schema:
                      type: string
                      maxLength: 200
            responses:
                '204':
                    description: 'No content'
    '/auth/oauth/grants':
        get:
            operationId: listOAuthGrants
            summary: 'List OAuth grants'
            description: 'The apps the signed-in person has let act as them'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OAuthGrantList'
    '/auth/oauth/grants/{id}':
        delete:
            operationId: revokeOAuthGrant
            summary: 'Revoke OAuth grant'
            description: 'Disconnect an app. Every token it holds for this person stops working at once'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '204':
                    description: 'No content'
    '/onboarding':
        get:
            operationId: getOnboardingRequirements
            summary: 'Get Onboarding Requirements'
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                type: array
                                items:
                                    '$ref': '#/components/schemas/OnboardingRequirement'
        post:
            operationId: submitOnboardingRequirement
            summary: 'Submit Onboarding Requirement'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OnboardingRequirement'
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                type: array
                                items:
                                    '$ref': '#/components/schemas/OnboardingRequirement'
    '/outputs/devices':
        get:
            operationId: listDevices
            summary: 'List output devices'
            description: 'Every speaker the station can play on, from every `output` plugin, with the mounts each can take'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OutputDeviceList'
    '/outputs/casts':
        get:
            operationId: listCasts
            summary: 'List casts'
            description: 'Every speaker the station is meant to be playing on, each asked how it is doing now'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OutputCastList'
        post:
            operationId: startCast
            summary: 'Start cast'
            description: 'Play the station on a speaker, replacing whatever it was playing. The station keeps it playing, through a dropped stream or a restart, until it is stopped here or somebody plays something else on it'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OutputCastRequest'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OutputCast'
    '/outputs/casts/{pluginId}/{deviceId}':
        delete:
            operationId: stopCast
            summary: 'Stop cast'
            description: 'Stop the station on a speaker. Answers 204 when it was not playing too'
            parameters:
                - name: pluginId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: deviceId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 400
            responses:
                '204':
                    description: 'No content'
    '/personas/{id}/auditions':
        get:
            operationId: listPersonaAuditions
            summary: 'List persona auditions'
            description: 'Every audition of this character, newest first, without their breaks'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaAuditionList'
        post:
            operationId: start
            summary: 'Start persona audition'
            description: 'Asks the station to put this character through a playlist or a chart. It is queued, not written'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaAuditionRequest'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaAudition'
    '/personas/{id}/auditions/{auditionId}':
        get:
            operationId: getPersonaAudition
            summary: 'Get persona audition'
            description: 'One audition with every break it has written so far, in order'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: auditionId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaAudition'
    '/personas/{id}/auditions/{auditionId}/cancel':
        post:
            operationId: cancel
            summary: 'Cancel persona audition'
            description: 'Stops an audition where it stands, keeping the breaks it has already written'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: auditionId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaAuditionSummary'
    '/personas':
        get:
            operationId: listPersonas
            summary: 'List personas'
            description: 'Every persona this station has, oldest first'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaList'
        post:
            operationId: createPersona
            summary: 'Create persona'
            description: 'Writes a new persona. It is not put on air by creating it'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/Persona'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaList'
    '/personas/generate':
        post:
            operationId: generate
            summary: 'Generate persona'
            description: 'Turns a description of a character into a whole persona, checked against its own sample lines and handed back unsaved'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaRequest'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/GeneratedPersona'
    '/personas/{id}/rewrite':
        post:
            operationId: rewrite
            summary: 'Rewrite persona in station language'
            description: "Rewrites a character's own wording (its speech rules, sample lines, signature words, catchphrases, banned wording and phrasings) in the station's language, keeping who it is, and hands the sheet back unsaved"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/GeneratedPersona'
    '/personas/restore':
        post:
            operationId: restore
            summary: 'Restore station personas'
            description: "Writes back whichever of the station's own personas this station is missing, touching nothing it already has and putting nothing on air"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaList'
    '/personas/export':
        get:
            operationId: exportPersonas
            summary: 'Export personas'
            description: 'Every character this station holds, as one file'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaFile'
                    headers:
                        Content-Disposition:
                            schema:
                                type: string
    '/personas/{id}/export':
        get:
            operationId: exportPersona
            summary: 'Export persona'
            description: 'One character, its sheet and its stories, as a file'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaFile'
                    headers:
                        Content-Disposition:
                            schema:
                                type: string
                '404':
                    description: 'Not found'
    '/personas/import/preview':
        post:
            operationId: previewPersonaImport
            summary: 'Preview persona import'
            description: 'Reads a file and reports what importing it would create, rewrite and skip. Writes nothing'
            parameters:
                - name: replace
                  in: query
                  required: false
                  schema:
                      type: array
                      items:
                          type: string
                          minLength: 1
                          maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaFile'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaImportPlan'
    '/personas/import':
        post:
            operationId: importPersonas
            summary: 'Import personas'
            description: 'Writes a file into this station: creates what is new, rewrites only the characters named in `replace`, and answers with what it did'
            parameters:
                - name: replace
                  in: query
                  required: false
                  schema:
                      type: array
                      items:
                          type: string
                          minLength: 1
                          maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaFile'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaImportResult'
    '/personas/{id}':
        put:
            operationId: updatePersona
            summary: 'Update persona'
            description: 'Rewrites one persona. An edit to the one on air is heard on the next break'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/Persona'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaList'
        delete:
            operationId: deletePersona
            summary: 'Delete persona'
            description: 'Removes a persona, including the one on air, which leaves the station with none'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaList'
    '/personas/{id}/default-host':
        put:
            operationId: setDefaultHost
            summary: 'Set the station host'
            description: "Makes this persona the station's own host, and the previous one no longer is"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaList'
    '/personas/{id}/notes':
        get:
            operationId: listPersonaNotes
            summary: 'List persona notes'
            description: 'Everything this character has accumulated, oldest first, in every state'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaNoteList'
        post:
            operationId: writePersonaNote
            summary: 'Write persona note'
            description: "Writes a note by hand. An operator's own note is active from the moment it exists; only the distil pass proposes"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaNoteWrite'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaNoteList'
    '/personas/{id}/notes/{noteId}':
        put:
            operationId: updatePersonaNote
            summary: 'Update persona note'
            description: "Rewrites one note's words, whoever wrote it. Editing what the station proposed is most of the point of the panel"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: noteId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaNoteWrite'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaNoteList'
        delete:
            operationId: deletePersonaNote
            summary: 'Delete persona note'
            description: 'Removes a note outright. Turning down a PROPOSAL is a state rather than this, or the next pass writes it again'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: noteId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaNoteList'
    '/personas/{id}/notes/{noteId}/state':
        put:
            operationId: setState
            summary: 'Set persona note state'
            description: "Accepts a proposal, turns one down, or rests an active note. Mirrors the lexicon's own state route"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: noteId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaNoteState'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaNoteList'
    '/personas/{id}/stories':
        get:
            operationId: listPersonaStories
            summary: 'List persona stories'
            description: 'Every story this character holds, oldest first, in every state'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
        post:
            operationId: writePersonaStory
            summary: 'Write persona story'
            description: "Writes a story by hand. An operator's own is tellable from the moment it exists; only the enrichment pass proposes"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaStoryWrite'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
    '/personas/{id}/stories/{storyId}':
        put:
            operationId: updatePersonaStory
            summary: 'Update persona story'
            description: "Rewrites one story's handle and telling, whoever wrote it"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: storyId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaStoryWrite'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
        delete:
            operationId: deletePersonaStory
            summary: 'Delete persona story'
            description: 'Removes a story outright, details and all. Turning down a PROPOSAL is a state rather than this, or the next pass writes it again'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: storyId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
    '/personas/{id}/stories/{storyId}/state':
        put:
            operationId: setPersonaStoryState
            summary: 'Set persona story state'
            description: 'Accepts a proposal, turns one down, or takes a story out of the rotation without losing it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: storyId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaStoryState'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
    '/personas/{id}/stories/{storyId}/details':
        post:
            operationId: addDetail
            summary: 'Add persona story detail'
            description: 'Adds one thing to a story that already exists'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: storyId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaStoryDetailWrite'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
    '/personas/{id}/stories/{storyId}/details/{detailId}':
        put:
            operationId: updateDetail
            summary: 'Update persona story detail'
            description: "Rewrites one detail's words"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: storyId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: detailId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaStoryDetailWrite'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
        delete:
            operationId: removeDetail
            summary: 'Delete persona story detail'
            description: 'Removes one detail, leaving the story it was hung on alone'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: storyId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: detailId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
    '/personas/{id}/stories/{storyId}/details/{detailId}/state':
        put:
            operationId: setDetailState
            summary: 'Set persona story detail state'
            description: 'Accepts a proposed detail or turns it down, which has to outlive the pass that proposed it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: storyId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: detailId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaStoryState'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
    '/personas/{id}/rehearse':
        post:
            operationId: rehearse
            summary: 'Rehearse persona'
            description: 'Writes a talk break under this persona against two fixed invented records, and answers with every writer that was asked'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaRehearsal'
    '/personas/{id}/stories/{storyId}/beats':
        post:
            operationId: addBeat
            summary: 'Add persona story beat'
            description: 'Adds one part to an arc. A script rather than a summary: the floor speaks it as it stands'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: storyId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaStoryBeatWrite'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
    '/personas/{id}/stories/{storyId}/beats/{beatId}':
        put:
            operationId: updateBeat
            summary: 'Update persona story beat'
            description: "Rewrites one part's words, or moves it in the order"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: storyId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: beatId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaStoryBeatWrite'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
        delete:
            operationId: removeBeat
            summary: 'Delete persona story beat'
            description: 'Removes one part outright, leaving the arc standing. Turning down a PROPOSAL is a state instead'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: storyId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: beatId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
    '/personas/{id}/stories/{storyId}/beats/{beatId}/state':
        put:
            operationId: setBeatState
            summary: 'Set persona story beat state'
            description: 'Accepts a proposed part, or turns it down without losing that it was turned down'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: storyId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: beatId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaStoryState'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaStoryList'
    '/personas/{id}/memory':
        get:
            operationId: timeline
            summary: 'Read persona memory'
            description: 'What this character has told, newest first. The timeline a moment is picked from'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaMemoryTimeline'
    '/personas/{id}/memory/preview':
        get:
            operationId: previewPersonaMemoryRollback
            summary: 'Preview persona memory rollback'
            description: 'What rolling back to a moment would undo, without undoing it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: to
                  in: query
                  required: false
                  schema:
                      type: string
                      maxLength: 40
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaMemoryChange'
    '/personas/{id}/memory/rollback':
        post:
            operationId: rollback
            summary: 'Roll back persona memory'
            description: 'Undo it. Everything the station accrued after that moment goes; everything an operator wrote stays'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PersonaMemoryRollback'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PersonaMemory'
    '/playlists':
        get:
            operationId: listPlaylists
            summary: 'List importable playlists'
            description: "Every playlist the installed `catalog` plugins offer, as the library sync last read each one's list. A source with no list kept yet is asked while the request waits"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/CatalogPlaylistPage'
    '/playlists/{pluginId}/{playlistId}/tracks':
        get:
            operationId: getPlaylistTracks
            summary: 'Get playlist tracks'
            description: "One playlist's tracks from one plugin"
            parameters:
                - name: pluginId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: playlistId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 400
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/CatalogPlaylistTracks'
    '/playlists/{pluginId}/{playlistId}/hidden':
        put:
            operationId: hidePlaylist
            summary: 'Hide playlist'
            description: 'Hides one playlist from this station: the listing marks it hidden, the pickers stop offering it and the library sync stops reading it. Hiding one already hidden changes nothing'
            parameters:
                - name: pluginId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: playlistId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 400
        delete:
            operationId: showPlaylist
            summary: 'Show playlist'
            description: 'Shows a hidden playlist again. Showing one that is not hidden changes nothing'
            parameters:
                - name: pluginId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: playlistId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 400
    '/playlists/refresh':
        post:
            operationId: refreshPlaylists
            summary: 'Refresh playlists'
            description: 'Reads every playlist on every music source again, in the background, rather than waiting for the next scheduled read. New records reach the library; records gone from every playlist are retired'
    '/playlists/{pluginId}/{playlistId}/refresh':
        post:
            operationId: requestPlaylistRefresh
            summary: 'Refresh playlist'
            description: 'Reads one playlist again, in the background. New records reach the library; a record taken out of it stays until the next full read judges it'
            parameters:
                - name: pluginId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: playlistId
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 400
    '/station-playlists':
        get:
            operationId: listStationPlaylists
            summary: 'List station playlists'
            description: 'Every playlist the station owns, newest first'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationPlaylistList'
    '/station-playlists/{id}':
        get:
            operationId: getStationPlaylist
            summary: 'Get station playlist'
            description: 'One station playlist with its records in order, placeholders included'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationPlaylistDetail'
                '404':
                    description: 'Not found'
        patch:
            operationId: updateStationPlaylist
            summary: 'Update station playlist'
            description: 'Renames a station playlist, or rewrites what it is for'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/StationPlaylistUpdate'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationPlaylist'
                '404':
                    description: 'Not found'
        delete:
            operationId: delete
            summary: 'Delete station playlist'
            description: 'Deletes a station playlist. The records it named stay in the library'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '204':
                    description: 'No content'
                '404':
                    description: 'Not found'
    '/station-playlists/{id}/fill':
        post:
            operationId: requestFill
            summary: 'Fill station playlist'
            description: 'Looks up the records this playlist names and the library does not hold, in the background, and adds the ones a provider has. The activity feed says how it went'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '202':
                    description: 'Response 202'
                '404':
                    description: 'Not found'
    '/station-playlists/{id}/export':
        get:
            operationId: export
            summary: 'Export station playlist'
            description: 'One station playlist as a file another station can import'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlaylistFile'
                    headers:
                        Content-Disposition:
                            schema:
                                type: string
                '404':
                    description: 'Not found'
    '/station-playlists/import/preview':
        post:
            operationId: previewPlaylistImport
            summary: 'Preview playlist import'
            description: 'Reads a source and reports which of its records the library holds and which it would have to find. Writes nothing'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PlaylistImportInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlaylistImportPlan'
    '/station-playlists/import':
        post:
            operationId: importPlaylist
            summary: 'Import playlist'
            description: 'Makes a new station playlist from a source and answers with what it did'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PlaylistImportInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlaylistImportResult'
    '/playout/status':
        get:
            operationId: getStatus
            summary: 'Get playout status'
            description: 'What the station is playing and what is queued behind it. The console polls this'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlayoutStatus'
    '/playout/playlist':
        post:
            operationId: playPlaylist
            summary: 'Play a playlist'
            description: 'Loads a plugin playlist into the running order and starts handing it to the player. Replaces whatever was queued; what is on air finishes rather than being cut off'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PlayoutPlaylistInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlayoutStatus'
    '/playout/station-playlist':
        post:
            operationId: playStationPlaylist
            summary: 'Play a station playlist'
            description: 'Loads a playlist the station owns into the running order and starts handing it to the player. The same replacement a plugin playlist makes, from records the library already holds'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PlayoutStationPlaylistInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlayoutStatus'
    '/playout/album':
        post:
            operationId: playAlbum
            summary: 'Play an album'
            description: "Plays an album the library holds, whole and in the order it was made: by disc, then by track. A feature, so no breaks and no blends between its records, and what is on air finishes rather than being cut off. It stops at the end of the album, or when the schedule's next block starts"
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PlayoutAlbumInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlayoutStatus'
    '/playout/chart':
        post:
            operationId: playChart
            summary: 'Play a chart'
            description: 'Builds the running order from a published chart and starts handing it to the player. The same replacement a playlist makes, from a document somebody else ranked'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PlayoutChartInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlayoutStatus'
    '/playout/skip':
        post:
            operationId: skip
            summary: 'Skip the current item'
            description: 'Ends the item on air so the next one starts immediately. The station owns the decoder, so this lands at once rather than waiting out audio already committed to a player'
            parameters:
                - name: item
                  in: query
                  required: false
                  description: 'The id of the item on air as the caller last saw it (`PlayoutStatus.nowPlaying.item.id`). When it is no longer on air the skip is refused with a 409 and nothing is cut, so a press meant for a record that has just ended never takes off the one after it. Left out, the skip cuts whatever is on air when it arrives'
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                      description: 'The id of the item on air as the caller last saw it (`PlayoutStatus.nowPlaying.item.id`). When it is no longer on air the skip is refused with a 409 and nothing is cut, so a press meant for a record that has just ended never takes off the one after it. Left out, the skip cuts whatever is on air when it arrives'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlayoutStatus'
                '409':
                    description: Conflict
    '/playout/start':
        post:
            operationId: startPlayout
            summary: 'Start playout'
            description: 'Puts the station back on air with the running order it already has, picking it up where Stop left it. Distinct from putting a playlist on air, which builds a new broadcast and throws away what was there. Refused when there is nothing left to resume'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlayoutStatus'
    '/playout/stop':
        post:
            operationId: stopPlayout
            summary: 'Stop playout'
            description: 'Stands the station down: stops what is on air at once and hands the mount back. The running order is LEFT as it is, so `/playout/start` can pick it up where this stopped it. deadair holds the mount on a lease it renews while it has something to play, so stopping goes quiet rather than falling through to a bed nobody programmed'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlayoutStatus'
    '/playout/live/arm':
        post:
            operationId: armLive
            summary: 'Arm the live input'
            description: "Arms the live input. From here, real signal from an encoder connected to it starts a short countdown, and then the presenter is on the air above the station's own programme. Arming an input that is already armed or on the air only replaces the title"
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PlayoutLiveArmInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlayoutStatus'
                '409':
                    description: Conflict
    '/playout/live/disarm':
        post:
            operationId: disarmLive
            summary: 'Disarm the live input'
            description: 'Disarms the live input. A presenter on the air is handed back to the station at once'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PlayoutStatus'
                '409':
                    description: Conflict
    '/playout/live/connection':
        get:
            operationId: liveConnection
            summary: 'Get the live input connection'
            description: 'What an encoder needs to connect to the live input: the port, the mount, the user and the password'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/LiveConnection'
    '/plugins':
        get:
            operationId: listPlugins
            summary: 'List plugins'
            description: 'Lists every plugin the host knows about'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                type: array
                                items:
                                    '$ref': '#/components/schemas/PluginSummary'
    '/plugins/grants':
        get:
            operationId: listGrants
            summary: 'List plugin grants'
            description: 'Every capability an installed plugin is asking the operator for, with the answer so far'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginGrantList'
    '/plugins/providers':
        get:
            operationId: listProviders
            summary: 'List capability providers'
            description: 'Every capability more than one plugin could answer, who can answer it, and in what order the station asks them'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ProviderCatalogue'
    '/plugins/rescan':
        post:
            operationId: rescanPlugins
            summary: 'Rescan plugins'
            description: 'Rescans the mounted plugin directory: registers new plugins, unloads removed ones'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                type: array
                                items:
                                    '$ref': '#/components/schemas/PluginSummary'
    '/plugins/import':
        post:
            operationId: importPlugin
            summary: 'Import plugin'
            description: "Takes a plugin in from the browser as the tarball npm pack writes and puts it in the plugins directory. Importing runs the plugin's code: the station loads it to read its manifest, inside the server and with the server's privileges. It lands disabled, which only means the station does not use it until it is enabled. A newer version of an installed plugin replaces the older one"
            requestBody:
                required: true
                content:
                    'multipart/form-data':
                        schema:
                            '$ref': '#/components/schemas/PluginImport'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginImportResult'
                '400':
                    description: 'Bad request'
                '409':
                    description: Conflict
                '413':
                    description: 'Response 413'
                '415':
                    description: 'Response 415'
                '422':
                    description: 'Unprocessable entity'
    '/plugins/{id}':
        get:
            operationId: getPlugin
            summary: 'Get plugin'
            description: 'One plugin, including its stored non-secret configuration and last error'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginDetail'
        delete:
            operationId: removePlugin
            summary: 'Remove plugin'
            description: 'Removes a plugin the operator installed: stops it and deletes its folder. Its settings are kept, so importing it again brings them back. A bundled plugin is refused, unless an installed copy of it is left over from before the station shipped it: that copy never loads, and it is what gets removed'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                type: array
                                items:
                                    '$ref': '#/components/schemas/PluginSummary'
                '404':
                    description: 'Not found'
                '409':
                    description: Conflict
    '/plugins/{id}/config':
        put:
            operationId: updatePluginConfig
            summary: 'Update plugin configuration'
            description: "Validates against the plugin's own config schema, encrypts secrets, persists, and reinitializes"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PluginConfigInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginDetail'
    '/plugins/{id}/enable':
        post:
            operationId: enablePlugin
            summary: 'Enable plugin'
            description: 'Enables a plugin without resubmitting its configuration'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginDetail'
    '/plugins/{id}/disable':
        post:
            operationId: disablePlugin
            summary: 'Disable plugin'
            description: 'Disables a plugin and tears its instance down, keeping its configuration'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginDetail'
    '/plugins/{id}/grants':
        put:
            operationId: decideGrant
            summary: 'Decide plugin grant'
            description: 'Answers one capability this plugin asked for. Takes effect on the next fetch, with no reload'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PluginGrantInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginGrantList'
    '/plugins/{id}/reload':
        post:
            operationId: reloadPlugin
            summary: 'Reload plugin'
            description: "Reapplies the plugin's stored configuration: disposes the running instance and initializes it again"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginDetail'
    '/plugins/{id}/test':
        post:
            operationId: testPlugin
            summary: 'Test plugin connection'
            description: "Runs the plugin's own `testConnection()` through the invoker"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginTestResult'
    '/plugins/{id}/config/suggestions':
        post:
            operationId: suggestPluginConfigOptions
            summary: 'Suggest plugin config options'
            description: 'Asks the plugin what to offer for its config fields right now, through the invoker'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginFieldSuggestions'
    '/plugins/{id}/logs':
        get:
            operationId: getPluginLogs
            summary: 'Get plugin logs'
            description: "Returns the plugin's buffered log lines at or above the current log level"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 2000
                - name: level
                  in: query
                  required: false
                  schema:
                      '$ref': '#/components/schemas/PluginLogLevel'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginLogPage'
    '/plugins/{id}/logs/download':
        get:
            operationId: downloadPluginLogs
            summary: 'Download plugin logs'
            description: "Streams the plugin's full retained log as a plain-text attachment"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'text/plain':
                            schema:
                                type: string
                    headers:
                        Content-Disposition:
                            schema:
                                type: string
    '/plugins/{id}/logs/level':
        put:
            operationId: setPluginLogLevel
            summary: 'Set plugin log level'
            description: "Sets the minimum severity the plugin's log store retains going forward"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PluginLogLevelInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginDetail'
    '/plugins/{id}/oauth/authorize':
        get:
            operationId: startOAuthAuthorization
            summary: 'Start plugin OAuth authorization'
            description: "Reports where to send the operator for the provider's consent screen"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginOAuthStart'
    '/plugins/{id}/oauth':
        delete:
            operationId: disconnectOAuth
            summary: 'Disconnect plugin OAuth'
            description: "Forgets the plugin's stored OAuth tokens and reinitializes it"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginDetail'
    '/plugins/{id}/oauth/callback':
        get:
            operationId: completeOAuthCallback
            summary: 'Complete plugin OAuth authorization'
            description: 'Completes the flow. Anonymous: the provider redirects the browser here with no session of ours'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: code
                  in: query
                  required: false
                  schema:
                      type: string
                      maxLength: 2048
                - name: state
                  in: query
                  required: false
                  schema:
                      type: string
                      maxLength: 400
                - name: error
                  in: query
                  required: false
                  schema:
                      type: string
                      maxLength: 400
                - name: ubi
                  in: query
                  required: false
                  schema:
                      type: string
                      maxLength: 400
                - name: token
                  in: query
                  required: false
                  description: "What a desktop-style flow returns instead of `code`: the provider mints a token before the\nconsent screen and hands the same one back, which the plugin exchanges for a session. Last.fm's\nauth works this way. Listed here because the route parses this query strictly, so an\nundeclared parameter is a 400 before any plugin code runs"
                  schema:
                      type: string
                      maxLength: 2048
                      description: "What a desktop-style flow returns instead of `code`: the provider mints a token before the\nconsent screen and hands the same one back, which the plugin exchanges for a session. Last.fm's\nauth works this way. Listed here because the route parses this query strictly, so an\nundeclared parameter is a 400 before any plugin code runs"
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PluginOAuthResult'
    '/podcasts/shows':
        get:
            operationId: readShows
            summary: 'List shows'
            description: 'Every programme every installed podcast plugin carries'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationShowList'
    '/podcasts/search':
        get:
            operationId: searchDirectory
            summary: 'Search podcast directory'
            description: 'Looks a show up in the directories the installed podcast plugins can search'
            parameters:
                - name: query
                  in: query
                  required: true
                  description: 'Words to look a show up by: its name, its publisher, its subject'
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                      description: 'Words to look a show up by: its name, its publisher, its subject'
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 50
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationDirectoryPage'
    '/podcasts/episodes':
        get:
            operationId: readEpisodes
            summary: 'List episodes'
            description: 'The episodes the station knows about, newest first, with what it has done with each'
            parameters:
                - name: showId
                  in: query
                  required: false
                  description: "One show's episodes, or absent for every show's, newest first"
                  schema:
                      type: string
                      maxLength: 400
                      description: "One show's episodes, or absent for every show's, newest first"
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationEpisodePage'
    '/podcasts/episodes/{id}/fetch':
        post:
            operationId: requestFetch
            summary: 'Fetch episode'
            description: "Fetches one episode's audio into the station's store now, rather than waiting for its slot to come near"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationEpisode'
    '/podcasts/refresh':
        post:
            operationId: refreshPodcasts
            summary: 'Refresh podcasts'
            description: "Reads every show's feed again, in the background, rather than waiting for the next scheduled refresh"
    '/podcasts/own':
        get:
            operationId: listOwnShows
            summary: 'List own shows'
            description: 'The shows the station makes for itself'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OwnShowList'
        post:
            operationId: createOwnShow
            summary: 'Create own show'
            description: 'Makes a new show. Nothing is made until an episode is asked for'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OwnShow'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OwnShow'
    '/podcasts/own/{id}':
        put:
            operationId: updateOwnShow
            summary: 'Update own show'
            description: 'Rewrites a show. Episodes already asked for keep what they were asked with'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OwnShow'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OwnShow'
        delete:
            operationId: deleteOwnShow
            summary: 'Delete own show'
            description: 'Removes a show. Its episodes stay on the Productions page, no longer filed under it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
    '/podcasts/own/{id}/episodes':
        get:
            operationId: episodes
            summary: 'List own show episodes'
            description: "A show's episodes, newest first, with how far along each is"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ProductionList'
        post:
            operationId: requestEpisode
            summary: 'Request own show episode'
            description: 'Asks the show for an episode. It is queued, not started, and airs when it is made or at the time given'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OwnEpisodeRequest'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Production'
    '/productions':
        get:
            operationId: listProductions
            summary: 'List productions'
            description: 'Everything the station has made or is making, newest first'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ProductionList'
        post:
            operationId: request
            summary: 'Request production'
            description: 'Asks the station to make one. It is queued, not started'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ProductionRequest'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Production'
    '/productions/{id}/cancel':
        post:
            operationId: cancelProduction
            summary: 'Cancel production'
            description: 'Stops a production being made, for good'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Production'
    '/segments':
        get:
            operationId: listSegments
            summary: 'List segments'
            description: 'Everything the station can play that is not a record'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/SegmentList'
        post:
            operationId: createSegment
            summary: 'Create segment'
            description: 'Plans something for the station to say, and starts rendering it'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/SegmentCreate'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Segment'
    '/segments/upload':
        post:
            operationId: uploadSegment
            summary: 'Upload segment'
            description: 'Takes a recording in from the browser and puts it in the library, ready to air'
            requestBody:
                required: true
                content:
                    'multipart/form-data':
                        schema:
                            '$ref': '#/components/schemas/SegmentUpload'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Segment'
                '400':
                    description: 'Bad request'
                '413':
                    description: 'Response 413'
                '415':
                    description: 'Response 415'
    '/segments/scan':
        post:
            operationId: scanLibrary
            summary: 'Scan the segment inbox'
            description: 'Takes whatever audio is sitting in the inbox directory into the library. Safe to repeat: a segment is identified by its audio, so the same recording arriving twice is one segment'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/SegmentScanResult'
    '/scripts':
        get:
            operationId: readScriptHistory
            summary: 'Read script history'
            description: 'What the station has written lately, newest first, one page at a time'
            parameters:
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 200
                - name: before
                  in: query
                  required: false
                  description: 'Where the previous page ended. Opaque, and a keyset rather than an offset because rows arrive at the head continuously. Pass back whatever `nextBefore` said and nothing else'
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                      description: 'Where the previous page ended. Opaque, and a keyset rather than an offset because rows arrive at the head continuously. Pass back whatever `nextBefore` said and nothing else'
                - name: kind
                  in: query
                  required: false
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 50
                - name: writer
                  in: query
                  required: false
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                - name: outcome
                  in: query
                  required: false
                  schema:
                      '$ref': '#/components/schemas/ScriptOutcome'
                - name: personaKey
                  in: query
                  required: false
                  description: 'Everything ONE character has said. Absent is every character and none'
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                      description: 'Everything ONE character has said. Absent is every character and none'
                - name: segmentId
                  in: query
                  required: false
                  description: 'Every attempt made for ONE break, which is how a console reaches the words behind an item of the running order. Absent is the whole history'
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
                      description: 'Every attempt made for ONE break, which is how a console reaches the words behind an item of the running order. Absent is the whole history'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScriptHistoryPage'
    '/scripts/{id}/rating':
        put:
            operationId: rateScript
            summary: 'Rate script'
            description: 'What the operator thought of this attempt. Nothing acts on it automatically'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ScriptRatingInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScriptAttempt'
    '/scripts/summary':
        get:
            operationId: readScriptSummary
            summary: 'Read script summary'
            description: 'Write attempts by outcome, per presenter, over a recent window'
            parameters:
                - name: hours
                  in: query
                  required: false
                  description: 'How far back to count. Defaults to 24, and a week at most, because past that the nightly sweep may already have taken the rows and the count would quietly be of what survived rather than of what happened'
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 168
                      description: 'How far back to count. Defaults to 24, and a week at most, because past that the nightly sweep may already have taken the rows and the count would quietly be of what survived rather than of what happened'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScriptHistorySummary'
    '/scripts/performance':
        get:
            operationId: readScriptPerformance
            summary: 'Read script performance'
            description: 'Outcomes, decline reasons and ratings, per presenter and kind of break'
            parameters:
                - name: days
                  in: query
                  required: false
                  description: 'How far back to read. Defaults to 30. The nightly sweep decides how far back there is anything to read, and ratings go with the rows they rate'
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 365
                      description: 'How far back to read. Defaults to 30. The nightly sweep decides how far back there is anything to read, and ratings go with the rows they rate'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScriptPerformance'
    '/voices':
        get:
            operationId: listVoices
            summary: 'List voices'
            description: 'The voices the station can be asked to speak in'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/VoiceList'
    '/voices/sample':
        get:
            operationId: getDefaultVoiceSample
            summary: 'Get default voice sample'
            description: 'A short line spoken in whichever voice the plugin falls back to'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'audio/mpeg':
                            schema:
                                type: string
                                format: binary
                        'audio/wav':
                            schema:
                                type: string
                                format: binary
                        'audio/ogg':
                            schema:
                                type: string
                                format: binary
                        'audio/flac':
                            schema:
                                type: string
                                format: binary
                        'audio/mp4':
                            schema:
                                type: string
                                format: binary
                    headers:
                        cache-control:
                            schema:
                                type: string
                        etag:
                            schema:
                                type: string
                '304':
                    description: 'Response 304'
    '/voices/{voiceId}/sample':
        get:
            operationId: getVoiceSample
            summary: 'Get voice sample'
            description: 'A short line spoken in one voice, so an operator can hear it before choosing it'
            parameters:
                - name: voiceId
                  in: path
                  required: true
                  schema:
                      type: string
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'audio/mpeg':
                            schema:
                                type: string
                                format: binary
                        'audio/wav':
                            schema:
                                type: string
                                format: binary
                        'audio/ogg':
                            schema:
                                type: string
                                format: binary
                        'audio/flac':
                            schema:
                                type: string
                                format: binary
                        'audio/mp4':
                            schema:
                                type: string
                                format: binary
                    headers:
                        cache-control:
                            schema:
                                type: string
                        etag:
                            schema:
                                type: string
                '304':
                    description: 'Response 304'
    '/voices/preview':
        post:
            operationId: previewSpeech
            summary: 'Preview speech'
            description: "Speaks the caller's words in one voice, so a break can be heard before it is written for air"
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/SpeechPreviewRequest'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'audio/mpeg':
                            schema:
                                type: string
                                format: binary
                        'audio/wav':
                            schema:
                                type: string
                                format: binary
                        'audio/ogg':
                            schema:
                                type: string
                                format: binary
                        'audio/flac':
                            schema:
                                type: string
                                format: binary
                        'audio/mp4':
                            schema:
                                type: string
                                format: binary
    '/segments/{id}':
        delete:
            operationId: deleteSegment
            summary: 'Delete segment'
            description: 'Removes a recording and the inbox file behind it, so the next scan does not read it back in'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/SegmentList'
                '404':
                    description: 'Not found'
                '409':
                    description: Conflict
    '/segments/{id}/scope':
        put:
            operationId: scopeSegment
            summary: 'Scope segment'
            description: 'Sets which shows and presenters a recording is for. An empty scope makes it a recording for every show'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/SegmentScope'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Segment'
                '400':
                    description: 'Bad request'
                '404':
                    description: 'Not found'
                '409':
                    description: Conflict
    '/segments/{id}/sources':
        get:
            operationId: readSegmentSources
            summary: 'Read segment sources'
            description: 'The stored facts a written break was handed, the ones it said first'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/SegmentSourceList'
    '/segments/{id}/audio':
        get:
            operationId: getSegmentAudio
            summary: 'Get segment audio'
            description: 'The audio of one segment'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                - name: rendition
                  in: query
                  required: false
                  description: 'A purpose the station interprets rather than a format the caller picks, so what `share` means can change without any caller changing'
                  schema:
                      '$ref': '#/components/schemas/SegmentAudioRendition'
                      default: original
                      description: 'A purpose the station interprets rather than a format the caller picks, so what `share` means can change without any caller changing'
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'audio/mpeg':
                            schema:
                                type: string
                                format: binary
                        'audio/wav':
                            schema:
                                type: string
                                format: binary
                        'audio/ogg':
                            schema:
                                type: string
                                format: binary
                        'audio/flac':
                            schema:
                                type: string
                                format: binary
                        'audio/mp4':
                            schema:
                                type: string
                                format: binary
                    headers:
                        cache-control:
                            schema:
                                type: string
                        etag:
                            schema:
                                type: string
                        content-disposition:
                            schema:
                                type: string
                            description: 'A file name to save it under, on the `share` copy'
                '304':
                    description: 'Response 304'
                '503':
                    description: 'Response 503'
    '/audio/{checksum}/{ext}':
        get:
            operationId: getStoredAudio
            summary: 'Get stored audio'
            description: 'Audio out of the segment store, addressed by content rather than by row'
            parameters:
                - name: checksum
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 64
                      maxLength: 64
                - name: ext
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 8
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'audio/mpeg':
                            schema:
                                type: string
                                format: binary
                        'audio/wav':
                            schema:
                                type: string
                                format: binary
                        'audio/ogg':
                            schema:
                                type: string
                                format: binary
                        'audio/flac':
                            schema:
                                type: string
                                format: binary
                        'audio/mp4':
                            schema:
                                type: string
                                format: binary
                    headers:
                        cache-control:
                            schema:
                                type: string
                        etag:
                            schema:
                                type: string
                '304':
                    description: 'Response 304'
    '/pronunciations':
        get:
            operationId: listPronunciations
            summary: 'List pronunciations'
            description: "The station's lexicon: what it says, what has been proposed to it, and what it has turned down"
            parameters:
                - name: state
                  in: query
                  required: false
                  description: 'Absent is all of it'
                  schema:
                      type: string
                      enum: [active, suggested, rejected]
                      description: 'Absent is all of it'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PronunciationList'
        post:
            operationId: createPronunciation
            summary: 'Create pronunciation'
            description: 'Adds one the operator typed. It is said from the next render on'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PronunciationWrite'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PronunciationList'
    '/pronunciations/sample':
        post:
            operationId: samplePronunciation
            summary: 'Sample pronunciation'
            description: 'Speaks the written word as this entry says it, in one voice'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PronunciationSampleRequest'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'audio/mpeg':
                            schema:
                                type: string
                                format: binary
                        'audio/wav':
                            schema:
                                type: string
                                format: binary
                        'audio/ogg':
                            schema:
                                type: string
                                format: binary
                        'audio/flac':
                            schema:
                                type: string
                                format: binary
                        'audio/mp4':
                            schema:
                                type: string
                                format: binary
    '/pronunciations/{id}':
        put:
            operationId: updatePronunciation
            summary: 'Update pronunciation'
            description: "Rewrites one entry's words, whoever proposed it"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PronunciationWrite'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PronunciationList'
        delete:
            operationId: deletePronunciation
            summary: 'Delete pronunciation'
            description: 'Removes an entry outright. Turning a PROPOSAL down is a state rather than a deletion, because a deleted one comes back on the next pass'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PronunciationList'
    '/pronunciations/{id}/state':
        put:
            operationId: setPronunciationState
            summary: 'Set pronunciation state'
            description: 'Accepts a proposal, turns one down, or takes an entry out of use without losing what it said'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PronunciationStateWrite'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PronunciationList'
    '/pads':
        get:
            operationId: listPads
            summary: 'List pads'
            description: 'Every sound the station holds, board by board'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PadList'
        post:
            operationId: uploadPad
            summary: 'Upload pad'
            description: 'Takes a sound in from the browser and puts it on a board. The file lands in the pad library on disk, so it survives a rebuild and an archive carries it'
            requestBody:
                required: true
                content:
                    'multipart/form-data':
                        schema:
                            '$ref': '#/components/schemas/PadUpload'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PadList'
                '400':
                    description: 'Bad request'
                '409':
                    description: Conflict
                '413':
                    description: 'Response 413'
                '415':
                    description: 'Response 415'
    '/pads/scan':
        post:
            operationId: scanPads
            summary: 'Scan the pad library'
            description: 'Takes whatever audio is sitting in the pad library directory onto its board. Safe to repeat: a file nobody has touched is seen and left alone'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PadScanResult'
    '/pads/fetch':
        post:
            operationId: fetchPad
            summary: 'Fetch pad'
            description: 'Fetches a sound from an address and puts it on a board. The operator names the address, so this is them choosing a file exactly as dropping one in the library is'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PadFetch'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PadList'
                '400':
                    description: 'Bad request'
                '409':
                    description: Conflict
                '413':
                    description: 'Response 413'
                '415':
                    description: 'Response 415'
                '502':
                    description: 'Response 502'
    '/pads/{id}':
        delete:
            operationId: deletePad
            summary: 'Delete pad'
            description: 'Removes a sound the console put there, and the file it wrote for it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PadList'
                '404':
                    description: 'Not found'
                '409':
                    description: Conflict
    '/pads/{id}/state':
        put:
            operationId: setPadState
            summary: 'Set pad state'
            description: 'Turns a sound down, or puts one back. Answers the whole rack, since one pad changing state is one row moving between two sections of the same page'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PadState'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PadList'
    '/pads/{id}/use':
        put:
            operationId: setPadUse
            summary: 'Set pad use'
            description: 'Says where in a break a sound may land and when to reach for it. Answers the whole rack'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PadUse'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PadList'
    '/pads/{id}/audio':
        get:
            operationId: getPadAudio
            summary: 'Get pad audio'
            description: 'The sound itself, so an operator can hear what they dropped in'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'audio/mpeg':
                            schema:
                                type: string
                                format: binary
                        'audio/wav':
                            schema:
                                type: string
                                format: binary
                        'audio/ogg':
                            schema:
                                type: string
                                format: binary
                        'audio/flac':
                            schema:
                                type: string
                                format: binary
                        'audio/mp4':
                            schema:
                                type: string
                                format: binary
                    headers:
                        cache-control:
                            schema:
                                type: string
                        etag:
                            schema:
                                type: string
                '304':
                    description: 'Response 304'
    '/pads/sets':
        post:
            operationId: createPadSet
            summary: 'Create pad set'
            description: 'Names a new set, or answers the one already under that key'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PadSetWrite'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PadList'
    '/pads/sets/{id}':
        put:
            operationId: updatePadSet
            summary: 'Update pad set'
            description: 'Renames a set. The KEY moves with it, so every persona naming the old one stops finding it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PadSetWrite'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PadList'
        delete:
            operationId: deletePadSet
            summary: 'Delete pad set'
            description: 'Removes a set and its memberships, and no pads at all'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PadList'
    '/pads/sets/{id}/pads':
        put:
            operationId: setPadMembership
            summary: 'Set pad membership'
            description: 'Puts a pad on a set or takes it off. Refused where the set already answers to that name, because a script writes a name'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PadSetMembership'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PadList'
    '/requests/search':
        get:
            operationId: search
            summary: 'Search requestable records'
            description: 'Records the station could be asked to play, matching a title or an artist, then what the music providers carry in the room left'
            parameters:
                - name: q
                  in: query
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 25
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/RequestableTrackList'
    '/requests':
        get:
            operationId: listRequests
            summary: 'List requests'
            description: 'Every recent request, for the operator deciding on them'
            parameters:
                - name: status
                  in: query
                  required: false
                  schema:
                      '$ref': '#/components/schemas/RequestStatus'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ListenerRequestList'
        post:
            operationId: createRequest
            summary: 'Create request'
            description: 'Ask the station to play a record. Answers with the request whatever became of it, so a refusal says why in `reason`'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ListenerRequestCreate'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ListenerRequest'
    '/requests/mine':
        get:
            operationId: mine
            summary: 'List my requests'
            description: "The signed-in account's own recent requests"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ListenerRequestList'
    '/requests/{id}/insist':
        post:
            operationId: insist
            summary: 'Insist on request'
            description: 'Ask again for a record the station turned down for its own taste, overruling it. Only your own request, only one marked `overrulable`, and only once. Answers with the NEW request this makes, decided like any other: it can still wait for an operator, or be refused for who is asking or how full the line is'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ListenerRequest'
    '/requests/{id}/grant':
        post:
            operationId: grant
            summary: 'Grant request'
            description: 'Let a waiting request through. It goes into the running order once its audio is here'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ListenerRequest'
    '/requests/{id}/decline':
        post:
            operationId: decline
            summary: 'Decline request'
            description: 'Turn a request down. One already in the running order is left there; take it out of the order instead'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ListenerRequestDecline'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ListenerRequest'
    '/party':
        get:
            operationId: getParty
            summary: 'Get party'
            description: 'The party that is on, with its pass, so the console can show the QR code again'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PartyState'
        post:
            operationId: startParty
            summary: 'Start party'
            description: 'Start a party. A party already on is ended first, which turns its guests away, so there is only ever one pass to scan'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PartyStart'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PartyPass'
        delete:
            operationId: end
            summary: 'End party'
            description: 'End the party. Its pass stops working and every guest who joined with it is turned away on their next request'
            responses:
                '204':
                    description: 'No content'
    '/party/join':
        post:
            operationId: join
            summary: 'Join party'
            description: 'Join the party as a guest. Answers 404 for a pass that is unknown, ended or run out, without saying which'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/PartyJoin'
            security: []
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PartyGuestSession'
    '/festivals':
        get:
            operationId: listFestivals
            summary: 'List festivals'
            description: 'Every festival on this station, soonest first, each saying whether it is still to come, on now or over'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/FestivalList'
        post:
            operationId: addAFestival
            summary: 'Add a festival'
            description: 'Adds a festival. A show names it from the schedule, and nothing is said about it until one does'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/Festival'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/FestivalList'
    '/festivals/lookup':
        get:
            operationId: lookup
            summary: 'Look up a festival'
            description: 'Looks festivals up by name with the concert plugins that can list them, for an operator about to add one. Nothing is saved'
            parameters:
                - name: name
                  in: query
                  required: true
                  schema:
                      type: string
                      minLength: 2
                      maxLength: 120
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/FestivalLookup'
    '/festivals/{id}':
        put:
            operationId: changeAFestival
            summary: 'Change a festival'
            description: 'Replaces a festival and its whole bill. A show naming it plays and talks about the new one from its next refill and its next break'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/Festival'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/FestivalList'
                '404':
                    description: 'Not found'
        delete:
            operationId: removeAFestival
            summary: 'Remove a festival'
            description: 'Removes a festival. A show that named it carries on as the show it otherwise is'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/FestivalList'
                '404':
                    description: 'Not found'
    '/occasions':
        get:
            operationId: listOccasions
            summary: 'List occasions'
            description: 'Every occasion on this station, in the order a date is matched against them, each saying when it next falls'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OccasionList'
        post:
            operationId: addAnOccasion
            summary: 'Add an occasion'
            description: 'Adds an occasion at the end of the list. Presenters hear of it from the next break written for its day'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/Occasion'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OccasionList'
    '/occasions/order':
        put:
            operationId: reorder
            summary: 'Reorder occasions'
            description: 'Puts the list in a new order, which decides who wins when two fall on one date'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OccasionOrder'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OccasionList'
    '/occasions/export':
        get:
            operationId: exportOccasions
            summary: 'Export occasions'
            description: 'Every occasion on this station as one file, to hand to another station'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OccasionPack'
    '/occasions/import/preview':
        post:
            operationId: previewOccasionImport
            summary: 'Preview occasion import'
            description: 'Reads a file and reports what importing it would add, skip and leave out. Writes nothing'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OccasionPack'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OccasionImportPlan'
    '/occasions/import':
        post:
            operationId: importOccasions
            summary: 'Import occasions'
            description: 'Adds what is new in a file to the end of the list, switched off. Changes nothing the station already has'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/OccasionPack'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OccasionImportResult'
    '/occasions/{id}':
        put:
            operationId: changeAnOccasion
            summary: 'Change an occasion'
            description: 'Replaces an occasion, keeping its place in the list'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/Occasion'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OccasionList'
                '404':
                    description: 'Not found'
        delete:
            operationId: removeAnOccasion
            summary: 'Remove an occasion'
            description: 'Removes an occasion'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/OccasionList'
                '404':
                    description: 'Not found'
    '/schedule':
        get:
            operationId: listSchedule
            summary: 'List schedule'
            description: "Every slot in this station's schedule, earliest in the day first"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScheduleSlotList'
        post:
            operationId: createScheduleSlot
            summary: 'Create schedule slot'
            description: 'Adds a slot. The station does not change over until its start time comes round'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ScheduleSlot'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScheduleSlotList'
    '/schedule/current':
        get:
            operationId: current
            summary: 'Read current slot'
            description: 'Which slot the clock says should be on, and which one the station is actually airing'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScheduleNow'
    '/schedule/timetable':
        get:
            operationId: timetable
            summary: 'Read timetable'
            description: "The station's day as blocks, contiguous and gapless, for drawing"
            parameters:
                - name: from
                  in: query
                  required: false
                  description: "The first day to draw, as `YYYY-MM-DD` on the station's own calendar. Absent means the station's today, which is the only way a caller that does not know the station's timezone can anchor"
                  schema:
                      type: string
                      minLength: 10
                      maxLength: 10
                      description: "The first day to draw, as `YYYY-MM-DD` on the station's own calendar. Absent means the station's today, which is the only way a caller that does not know the station's timezone can anchor"
                - name: days
                  in: query
                  required: false
                  description: 'How many days from `from`. Defaults to a week'
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 31
                      description: 'How many days from `from`. Defaults to a week'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScheduleTimetable'
    '/schedule/export':
        get:
            operationId: exportSchedule
            summary: 'Export schedule'
            description: "This station's schedule as one file, to hand to another station. Slots name characters by key and playlists by name"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/SchedulePack'
    '/schedule/import/preview':
        post:
            operationId: previewScheduleImport
            summary: 'Preview schedule import'
            description: 'Reads a file and reports what importing it would add, skip and leave out, and what would clash if turned on. Writes nothing'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/SchedulePack'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PackImportPlan'
    '/schedule/import':
        post:
            operationId: importSchedule
            summary: 'Import schedule'
            description: 'Adds what is new in a file, switched off, so nothing airs until an operator turns it on. Changes nothing the station already has'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/SchedulePack'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScheduleImportResult'
    '/schedule/{id}':
        put:
            operationId: updateScheduleSlot
            summary: 'Update schedule slot'
            description: "Rewrites a slot. Takes effect at its next boundary rather than immediately; to change the show on air too, when it is this slot's, apply the slot afterwards with `POST /schedule/{id}/apply`"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/ScheduleSlot'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScheduleSlotList'
        delete:
            operationId: deleteScheduleSlot
            summary: 'Delete schedule slot'
            description: 'Removes a slot. Whatever is on air stays on until the next slot begins'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScheduleSlotList'
    '/schedule/{id}/apply':
        post:
            operationId: apply
            summary: 'Apply schedule slot to air'
            description: "Applies a slot, as it is saved now, to the show on air, which must be that slot's. Its name, brief, period, moods, rules and host change in place and the broadcast carries on; the records still planned are chosen again against the new programme, and the ones already planned keep playing until the new set is ready. A change to its source, mode, end or co-hosts cannot be made mid-show and waits for the slot's next occurrence"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/ScheduleSlotApplied'
                '404':
                    description: 'Not found'
                '409':
                    description: Conflict
    '/schedule/{id}/playlist-position':
        get:
            operationId: position
            summary: 'Read slot playlist position'
            description: 'The record a slot that resumes its playlist will open on next time, or nothing when it would start from the top'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/SlotPlaylistPosition'
        delete:
            operationId: restart
            summary: 'Restart slot playlist'
            description: 'Forgets where a slot got to in its playlist, so it starts from the top the next time it opens'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
    '/settings':
        get:
            operationId: getSettings
            summary: 'Get settings'
            description: 'Every station setting, its descriptor and its current value'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationSettings'
        put:
            operationId: writeSubmitted
            summary: 'Update settings'
            description: 'Applies a submitted settings form and answers with the settings as they now stand'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/StationSettingsInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationSettings'
    '/settings/signin/check':
        get:
            operationId: check
            summary: 'Check sign-in providers'
            description: 'Asks each identity provider in the sign-in settings for its discovery document, the way a sign-in would, and says which answered'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/SigninProvidersCheck'
    '/settings/mail/invitation/preview':
        get:
            operationId: previewInvitation
            summary: 'Preview invitation'
            description: "Renders the invitation email as it would be sent now, in the station's saved wording, with sample values in place of a real link, inviter and date"
            parameters:
                - name: role
                  in: query
                  required: true
                  description: "The role the invitation would be for. Its subject, its guide link and the station's own wording differ between the two"
                  schema:
                      type: string
                      enum: [listener, admin]
                      description: "The role the invitation would be for. Its subject, its guide link and the station's own wording differ between the two"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/InvitationPreview'
    '/logs':
        get:
            operationId: listSources
            summary: 'List logs'
            description: 'Every log this install has, present or not, with its size and when it was last written'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/LogSourceList'
    '/logs/{id}':
        get:
            operationId: readLog
            summary: 'Read log'
            description: 'A tail of one log, newest first'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 40
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 2000
                - name: level
                  in: query
                  required: false
                  description: 'Ignored by a source whose lines carry no level'
                  schema:
                      '$ref': '#/components/schemas/LogLevel'
                      description: 'Ignored by a source whose lines carry no level'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/LogPage'
                '404':
                    description: 'Not found'
    '/logs/{id}/download':
        get:
            operationId: downloadLog
            summary: 'Download log'
            description: 'The retained log as a plain-text attachment, oldest first, as the file is written'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 40
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'text/plain':
                            schema:
                                type: string
                    headers:
                        Content-Disposition:
                            schema:
                                type: string
                '404':
                    description: 'Not found'
    '/station/attention':
        get:
            operationId: readStationAttention
            summary: 'Read station attention'
            description: 'Everything wrong or waiting, worst first, each with the console page that can act on it'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationAttention'
    '/station/attention/{code}/dismiss':
        post:
            operationId: dismiss
            summary: 'Dismiss station attention'
            description: 'Accept an attention row as it stands, until something new joins it'
            parameters:
                - name: code
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 60
            responses:
                '204':
                    description: 'No content'
    '/station/checkup':
        get:
            operationId: readStationCheckup
            summary: 'Read station checkup'
            description: 'The loops the station runs and how much of the library it has looked at'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationCheckup'
    '/station/releases':
        get:
            operationId: readStationReleases
            summary: 'Read station releases'
            description: 'The releases this build contains and what each one changed, newest first'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationReleases'
    '/station/releases/check':
        post:
            operationId: checkStationReleases
            summary: 'Check station releases'
            description: 'Asks GitHub for newer releases now, and answers with what the station then knows'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StationReleases'
    '/traces':
        get:
            operationId: readTraces
            summary: 'Read traces'
            description: 'Recent decisions, newest first, folded to one row each'
            parameters:
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 200
                - name: kind
                  in: query
                  required: false
                  description: 'An exact queue name or route, for reading one kind of decision on its own'
                  schema:
                      type: string
                      maxLength: 200
                      description: 'An exact queue name or route, for reading one kind of decision on its own'
                - name: failedOnly
                  in: query
                  required: false
                  description: 'Only decisions carrying at least one failed call'
                  schema:
                      type: boolean
                      description: 'Only decisions carrying at least one failed call'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TracesPage'
    '/traces/{id}':
        get:
            operationId: readTrace
            summary: 'Read trace'
            description: 'One decision: every call it made, and the decisions on either side of it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TraceDetail'
                '404':
                    description: 'Not found'
    '/storage':
        get:
            operationId: readStorage
            summary: 'Read storage'
            description: 'What is on disk, per store, against what the database says should be'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StorageReport'
    '/archive/recordings':
        get:
            operationId: listRecordings
            summary: 'List recordings'
            description: 'Every recording in the archive, newest first'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/RecordingList'
    '/archive/recordings/{id}':
        delete:
            operationId: deleteRecording
            summary: 'Delete recording'
            description: 'Deletes a finished recording. One still being recorded is refused'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 64
    '/archive/recordings/{id}/audio':
        get:
            operationId: getRecordingAudio
            summary: 'Get recording audio'
            description: 'The audio of one recording. Answers a byte range, so a player can seek through an hour'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 64
                - name: download
                  in: query
                  required: false
                  schema:
                      type: boolean
                - name: range
                  in: header
                  required: false
                  schema:
                      type: string
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'audio/mpeg':
                            schema:
                                type: string
                                format: binary
                    headers:
                        accept-ranges:
                            schema:
                                type: string
                        content-disposition:
                            schema:
                                type: string
                '206':
                    description: 'Response 206'
                    content:
                        'audio/mpeg':
                            schema:
                                type: string
                                format: binary
                    headers:
                        accept-ranges:
                            schema:
                                type: string
                        content-range:
                            schema:
                                type: string
                            required: true
    '/hls/{name}':
        get:
            operationId: getHlsPlaylist
            summary: 'Get HLS playlist'
            description: 'One HLS playlist, and the tick that says somebody is still listening to it'
            parameters:
                - name: name
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 120
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/vnd.apple.mpegurl':
                            schema:
                                type: string
                                format: binary
                    headers:
                        cache-control:
                            schema:
                                type: string
                '404':
                    description: 'Not found'
    '/listen.pls':
        get:
            operationId: getTuneInPls
            summary: 'Get tune-in pls'
            description: "The station's streams as a PLS playlist, MP3 first, for a player that takes a playlist file rather than a stream address"
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'audio/x-scpls':
                            schema:
                                type: string
                '404':
                    description: 'Not found'
    '/listen.m3u':
        get:
            operationId: getTuneInM3u
            summary: 'Get tune-in m3u'
            description: "The station's streams as an M3U playlist, MP3 first, for a player that takes a playlist file rather than a stream address"
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'audio/x-mpegurl':
                            schema:
                                type: string
                '404':
                    description: 'Not found'
    '/stream/authorization':
        get:
            operationId: readAuthorization
            summary: 'Read fetcher authorization'
            description: 'What the track fetcher holds by way of a Spotify login, and whether an authorization is already waiting to be finished'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/FetcherAuthorization'
        post:
            operationId: startAuthorization
            summary: 'Start fetcher authorization'
            description: "Starts the fetcher's one-time authorization and answers with the URL to open. Starting another replaces whichever was pending"
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/FetcherAuthorizationStart'
    '/stream/authorization/complete':
        post:
            operationId: finishAuthorization
            summary: 'Finish fetcher authorization'
            description: "Finishes an authorization from the address the operator's browser ended up at"
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/FetcherAuthorizationInput'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/FetcherAuthorizationFinished'
    '/stream/listeners':
        get:
            operationId: listListeners
            summary: 'List stream listeners'
            description: "Who is connected to the station's stream right now, over Icecast and over HLS"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/StreamListeners'
    '/topics':
        get:
            operationId: listTopics
            summary: 'List topics'
            description: 'Every subject this station has named, for one sort of break or for all of them'
            parameters:
                - name: kind
                  in: query
                  required: false
                  description: 'One sort of break, or absent for every subject this station has named'
                  schema:
                      type: string
                      maxLength: 100
                      description: 'One sort of break, or absent for every subject this station has named'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TopicList'
        post:
            operationId: createTopic
            summary: 'Create topic'
            description: 'Names a new subject. Nothing uses it until something points at it'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/Topic'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TopicList'
    '/topics/kinds':
        get:
            operationId: kinds
            summary: 'List topic kinds'
            description: "Which sorts of break have subjects, and the form each one's settings are edited with"
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TopicKindList'
    '/topics/export':
        get:
            operationId: exportTopics
            summary: 'Export topics'
            description: 'Every subject this station has named as one file, to hand to another station'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TopicPack'
    '/topics/import/preview':
        post:
            operationId: previewTopicImport
            summary: 'Preview topic import'
            description: 'Reads a file and reports what importing it would add, skip and leave out. Writes nothing'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/TopicPack'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/PackImportPlan'
    '/topics/import':
        post:
            operationId: importTopics
            summary: 'Import topics'
            description: 'Adds what is new in a file. A subject this station already has, by kind and key, is left as it is'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/TopicPack'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TopicImportResult'
    '/topics/{id}':
        put:
            operationId: updateTopic
            summary: 'Update topic'
            description: 'Rewrites one subject. A break already written keeps the words it was given'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/Topic'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TopicList'
        delete:
            operationId: deleteTopic
            summary: 'Delete topic'
            description: 'Removes a subject, and any band on the format clock that asked for it'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 100
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/TopicList'
    '/invitations':
        get:
            operationId: listInvitations
            summary: 'List invitations'
            description: 'Every invitation, newest first, with the link of each one still open'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/InvitationList'
        post:
            operationId: createInvitation
            summary: 'Create invitation'
            description: 'Invite somebody into a role. An open invitation to the same address is withdrawn first, so this is also how one is sent again. Refused for an address that already has an account'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/InvitationCreate'
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Invitation'
    '/invitations/{id}':
        delete:
            operationId: revokeInvitation
            summary: 'Revoke invitation'
            description: 'Withdraw an invitation. Its link stops working at once. Nothing is deleted: it stays in the list as withdrawn'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/Invitation'
    '/invitations/accept/details':
        post:
            operationId: details
            summary: 'Read invitation'
            description: 'What an open invitation is for: the address, the role and the station. Changes nothing'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/InvitationToken'
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/InvitationDetails'
    '/invitations/accept/start':
        post:
            operationId: startAcceptingInvitation
            summary: 'Start accepting invitation'
            description: 'Check the password and start setting up the second step. Nothing is saved, and starting again replaces the setup'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/InvitationAcceptStart'
            security: []
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/InvitationAcceptStartResponse'
    '/invitations/accept':
        post:
            operationId: accept
            summary: 'Accept invitation'
            description: 'Accept: make the account with its password, its second step and its role, all at once, and spend the invitation'
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/InvitationAccept'
            security: []
            responses:
                '201':
                    description: Created
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/InvitationAccepted'
    '/users':
        get:
            operationId: listUsers
            summary: 'List users'
            description: "The station's people, one page at a time, ordered by when their account was made"
            parameters:
                - name: page
                  in: query
                  required: false
                  description: 'The page number'
                  schema:
                      type: integer
                      minimum: 0
                      default: 0
                      description: 'The page number'
                - name: pageSize
                  in: query
                  required: false
                  description: 'The page size'
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 25
                      description: 'The page size'
                - name: sort
                  in: query
                  required: false
                  description: 'The sort order'
                  schema:
                      type: string
                      enum: [asc, desc]
                      default: desc
                      description: 'The sort order'
                - name: total
                  in: query
                  required: true
                  description: 'The total number of items'
                  schema:
                      type: integer
                      minimum: 0
                      readOnly: true
                      description: 'The total number of items'
                - name: active
                  in: query
                  required: false
                  description: 'Optionally filter by whether the items are active'
                  schema:
                      type: boolean
                      description: 'Optionally filter by whether the items are active'
                - name: search
                  in: query
                  required: false
                  description: 'Part of an email address'
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 200
                      description: 'Part of an email address'
                - name: role
                  in: query
                  required: false
                  description: 'Only people holding this role'
                  schema:
                      '$ref': '#/components/schemas/PlatformRole'
                      description: 'Only people holding this role'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/UserPage'
    '/users/{id}':
        get:
            operationId: getUser
            summary: 'Get user'
            description: 'One person, with every way they sign in, where they are signed in and their recent sign-ins'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/UserDetail'
    '/users/{id}/role':
        put:
            operationId: changeRole
            summary: 'Change user role'
            description: 'Give a person a different role. They hold exactly one, so the role they had is taken away. Refused for your own account, and for the last admin'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            requestBody:
                required: true
                content:
                    'application/json':
                        schema:
                            '$ref': '#/components/schemas/UserRoleChange'
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/UserSummary'
    '/users/{id}/deactivate':
        post:
            operationId: deactivate
            summary: 'Deactivate user'
            description: 'Switch a person off. They are signed out everywhere and cannot sign in, and their API keys, connected apps and chat links stop working, until they are switched back on. Nothing is deleted. Refused for your own account, and for the last admin'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/UserSummary'
    '/users/{id}/reactivate':
        post:
            operationId: reactivate
            summary: 'Reactivate user'
            description: 'Switch a person back on. They sign in as they did before, and their API keys, connected apps and chat links work again'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '200':
                    description: 'Successful response'
                    content:
                        'application/json':
                            schema:
                                '$ref': '#/components/schemas/UserSummary'
    '/users/{id}/sign-out':
        post:
            operationId: signOut
            summary: 'Sign out user'
            description: 'Sign a person out everywhere. They can sign straight back in'
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '204':
                    description: 'No content'
    '/users/{id}/mfa/reset':
        post:
            operationId: resetMfa
            summary: 'Reset user MFA'
            description: "Remove a person's authenticator apps and passkeys and sign them out everywhere, for when they have lost the device. They sign in with their password and set a new one up"
            parameters:
                - name: id
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
            responses:
                '204':
                    description: 'No content'
components:
    schemas:
        ActivityModule:
            type: string
            enum: [playout, director, render, catalog, plugins, storage, events]
            description: "Which part of the station an entry came from, and the console's one filter axis"
        ActivitySeverity:
            type: string
            enum: [info, warn, fault]
            description: "How an entry reads, not how bad it is. There is deliberately no `waiting`: a station idling for\nwant of a listener says so in its own words and stays `info`, for the same reason the transport\nreports it as `ready` rather than as a mild fault"
        ActivityEntry:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Unique across the whole feed, and half of the cursor below'
                at:
                    type: string
                    format: date-time
                    description: 'When it happened, as the database recorded it'
                module:
                    '$ref': '#/components/schemas/ActivityModule'
                kind:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Dotted and stable: `silence.cause`, `air.on`, `segment.ready`, `track.aired`. What a console draws a line with, never something a decision is made on'
                severity:
                    '$ref': '#/components/schemas/ActivitySeverity'
                detail:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: 'The sentence a person reads, phrased by whatever produced it'
                data:
                    type: object
                    additionalProperties: {}
                    description: 'The structured half, for a reader that wants to filter or chart rather than read'
                segmentId:
                    type: string
                    maxLength: 100
                    description: 'The segment this is about, for an entry that came from one'
                trackId:
                    type: string
                    maxLength: 100
                    description: 'The catalog track this is about, for an entry that came from one'
            required: [id, at, module, kind, severity, detail]
            description: "One thing that happened, from whichever of the feed's sources holds it"
        ActivityQuery:
            type: object
            properties:
                limit:
                    type: integer
                    minimum: 1
                    maximum: 200
                before:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Where the previous page ended. Opaque, and a keyset rather than an offset because rows arrive at the head continuously: an offset would re-show a row on every page as the feed grew under it. Pass back whatever `nextBefore` said and nothing else'
                module:
                    '$ref': '#/components/schemas/ActivityModule'
                minSeverity:
                    '$ref': '#/components/schemas/ActivitySeverity'
                    description: 'The floor, not the exact match: `warn` answers with warnings and faults. Absent is everything'
            description: 'One page of the feed, newest first'
        ActivityPage:
            type: object
            properties:
                entries:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ActivityEntry'
                nextBefore:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The cursor for the page after this one, absent once the feed has been read to its end'
            required: [entries]
        BreakArtwork:
            type: object
            properties:
                kind:
                    type: string
                    minLength: 1
                    maxLength: 64
                    description: '`segments.kind`, which is what decides which break wears this: `weather`, `news`, or whatever an operator wrote on a format-clock band'
                url:
                    type: string
                    maxLength: 2000
                    description: "Where the station serves it, as a path under the API root. The same shape and the same route a record's cover uses"
                source:
                    type: string
                    enum: [shipped, operator]
                    description: 'Whether these are the bytes this repository ships or ones somebody uploaded over them'
                hasShipped:
                    type: boolean
                    description: 'Whether this repository ships a picture for this kind, which is whether reverting has anywhere to go'
            required: [kind, url, source, hasShipped]
            description: "The picture one KIND of break wears -- a weather forecast, a news bulletin -- as the console draws\nit.\n\nOnly kinds the station actually holds bytes for are listed. A kind with no picture is a break\nwearing the station's logo on the mount and nothing in a listener's app, which is what every break\ndid before this existed and is not a row worth drawing"
        BreakArtworkList:
            type: object
            properties:
                breaks:
                    type: array
                    items:
                        '$ref': '#/components/schemas/BreakArtwork'
            required: [breaks]
            description: 'Every kind the station holds a picture for, kind by kind'
        BreakArtworkUpload:
            type: object
            properties:
                file:
                    type: string
                    format: binary
                    description: 'The image itself. jpeg, png, webp or gif, decided by its BYTES rather than by its name or its declared type, and at most 4 MB'
            required: [file]
            description: "A picture arriving from the browser, as multipart form parts.\n\nDocumentation rather than validation: a multipart body reaches the service as the raw parser and\nthe generated client types the body as `FormData`, so nothing checks this shape. It says what to\nsend"
        PersonaPortrait:
            type: object
            properties:
                personaId:
                    type: string
                    format: uuid
                    description: 'The persona it belongs to'
                url:
                    type: string
                    maxLength: 2000
                    description: "Where the station serves it, as a path under the API root. The same shape and the same route a record's cover uses"
            required: [personaId, url]
            description: "A presenter's picture, which a listener's player shows while that persona is on air"
        PersonaPortraitList:
            type: object
            properties:
                portraits:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaPortrait'
            required: [portraits]
            description: 'Every persona that has a portrait'
        PersonaPortraitUpload:
            type: object
            properties:
                file:
                    type: string
                    format: binary
                    description: 'The image itself. jpeg, png, webp or gif, decided by its BYTES, and at most 4 MB'
            required: [file]
            description: "A portrait arriving from the browser, as multipart form parts. Documentation rather than validation, as for a break's picture"
        AuthenticationGrantType:
            type: string
            enum:
                - client_credentials
                - password
                - refresh_token
                - link
                - code
                - fido
                - authenticator
                - oidc
            description: 'Denotes the authorization flow to use'
        PasswordlessAuthenticationGrantType:
            type: string
            enum: [link, code, fido, oidc]
            description: 'Denotes the authorization flow to use'
        AuthenticationFactorMethod:
            type: string
            enum: [phone, password, email, authenticator, fido, oidc]
            description: 'The type of the factor'
        AuthenticationFactorKind:
            type: string
            enum: [knowledge, possession, biometric]
            description: 'The kind of the factor'
        OidcProvider:
            type: string
            minLength: 1
            maxLength: 32
            description: 'The name of an identity provider the station offers, as the operator set it under Settings, Sign-in and security. `GET /auth/login/oidc/providers` lists them'
        BaseAuthenticationRequest:
            type: object
            properties:
                grant_type:
                    '$ref': '#/components/schemas/AuthenticationGrantType'
                    description: 'The grant type for the request'
                scope:
                    type: string
                    maxLength: 100
                    description: 'The scope of the request'
                client_id:
                    type: string
                    format: uuid
                    description: "The application's client identifier, if available"
            required: [grant_type]
        ClientCredentialsAuthenticationRequest:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationRequest'
                - type: object
                  properties:
                      grant_type:
                          const: client_credentials
                          description: 'The grant type for the request'
                      client_id:
                          type: string
                          format: uuid
                          description: 'The client identifier'
                      client_secret:
                          type: string
                          minLength: 8
                          maxLength: 256
                          description: 'The client secret'
                  required: [grant_type, client_id, client_secret]
        PasswordAuthenticationRequest:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationRequest'
                - type: object
                  properties:
                      grant_type:
                          const: password
                          description: 'The grant type for the request'
                      username:
                          type: string
                          minLength: 3
                          maxLength: 64
                          description: "User's identifier, usually an email address"
                      password:
                          type: string
                          minLength: 8
                          maxLength: 256
                          description: "User's password"
                  required: [grant_type, username, password]
        RefreshTokenAuthenticationRequest:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationRequest'
                - type: object
                  properties:
                      grant_type:
                          const: refresh_token
                          description: 'The grant type for the request'
                      refresh_token:
                          type: string
                          description: 'The refresh token issued by the authorization server. Optional: browser clients omit it and present the httpOnly refresh cookie instead'
                  required: [grant_type]
        LinkAuthenticationRequest:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationRequest'
                - type: object
                  properties:
                      grant_type:
                          const: link
                          description: 'The grant type for the request'
                      challenge_id:
                          type: string
                          maxLength: 100
                          description: 'The email challenge id returned by `POST /auth/login/start` — binds the link to the issued challenge so cross-device clicks work'
                      link:
                          type: string
                          description: 'The magic link token'
                  required: [grant_type, challenge_id, link]
        CodeAuthenticationRequest:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationRequest'
                - type: object
                  properties:
                      grant_type:
                          const: code
                          description: 'The grant type for the request'
                      code:
                          type: string
                          minLength: 6
                          maxLength: 10
                          description: 'The one-time code'
                      code_verifier:
                          type: string
                          minLength: 43
                          maxLength: 128
                          description: 'PKCE verifier — required for a primary code login; absent when mfa_challenge_id is set'
                      mfa_challenge_id:
                          type: string
                          maxLength: 100
                          description: 'When set, completes a pending MFA challenge; replaces code_verifier as proof-of-origin'
                      challenge_id:
                          type: string
                          maxLength: 100
                          description: 'The phone/email challenge id (returned by POST /auth/factors/start for phone-MFA). Required when mfa_challenge_id is set; ignored otherwise (resolved via PKCE)'
                  required: [grant_type, code]
        FidoAuthenticationRequest:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationRequest'
                - type: object
                  properties:
                      grant_type:
                          const: fido
                          description: 'The grant type for the request'
                      credential:
                          '$ref': '#/components/schemas/PublicKeyCredentialWithAssertion'
                          description: 'A passkey credential object'
                      challenge_id:
                          type: string
                          maxLength: 100
                          description: 'The FIDO assertion challenge id returned by `POST /auth/login/start` (primary) or `POST /auth/factors/start` (MFA second factor). Must be the per-challenge id, not the actor id.'
                      mfa_challenge_id:
                          type: string
                          maxLength: 100
                          description: 'When set, completes a pending MFA challenge instead of issuing a single-factor session'
                  required: [grant_type, credential, challenge_id]
        AuthenticatorAuthenticationRequest:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationRequest'
                - type: object
                  properties:
                      grant_type:
                          const: authenticator
                          description: 'The grant type for the request'
                      code:
                          type: string
                          minLength: 6
                          maxLength: 10
                          description: 'The TOTP code'
                      mfa_challenge_id:
                          type: string
                          maxLength: 100
                          description: 'The pending MFA challenge — required, TOTP has no other actor binding at initial login'
                      method_id:
                          type: string
                          description: "The id of the enrolled authenticator factor to verify against (must be present in the MFA challenge's eligible list)"
                  required: [grant_type, code, mfa_challenge_id, method_id]
        OidcAuthenticationRequest:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationRequest'
                - type: object
                  properties:
                      grant_type:
                          const: oidc
                          description: 'The grant type for the request'
                      challenge_id:
                          type: string
                          maxLength: 100
                          description: 'The one-time stash id from the OIDC callback redirect (the value after `?token=oidc:` on `/auth/callback`). Single-use — the API consumes it via `OidcFactorService.redeemAuthenticatedExchange`.'
                  required: [grant_type, challenge_id]
        AuthenticationRequest:
            oneOf:
                - '$ref': '#/components/schemas/PasswordAuthenticationRequest'
                - '$ref': '#/components/schemas/ClientCredentialsAuthenticationRequest'
                - '$ref': '#/components/schemas/RefreshTokenAuthenticationRequest'
                - '$ref': '#/components/schemas/LinkAuthenticationRequest'
                - '$ref': '#/components/schemas/CodeAuthenticationRequest'
                - '$ref': '#/components/schemas/FidoAuthenticationRequest'
                - '$ref': '#/components/schemas/AuthenticatorAuthenticationRequest'
                - '$ref': '#/components/schemas/OidcAuthenticationRequest'
            discriminator:
                propertyName: grant_type
                mapping:
                    password: '#/components/schemas/PasswordAuthenticationRequest'
                    client_credentials: '#/components/schemas/ClientCredentialsAuthenticationRequest'
                    refresh_token: '#/components/schemas/RefreshTokenAuthenticationRequest'
                    link: '#/components/schemas/LinkAuthenticationRequest'
                    code: '#/components/schemas/CodeAuthenticationRequest'
                    fido: '#/components/schemas/FidoAuthenticationRequest'
                    authenticator: '#/components/schemas/AuthenticatorAuthenticationRequest'
                    oidc: '#/components/schemas/OidcAuthenticationRequest'
        AuthenticationToken:
            type: object
            properties:
                accessToken:
                    type: string
                    description: 'The access token string as issued by the authorization server'
                refreshToken:
                    type: string
                    description: 'A refresh token which applications can use to obtain another access token'
                expiresIn:
                    type: integer
                    description: 'Unix timestamp (seconds) when the access token expires'
                tokenType:
                    type: string
                    description: 'The type of token this is, typically just the string *Bearer*'
                scope:
                    type: string
                    description: 'Space-separated list of scopes granted to this token'
            required: [accessToken, expiresIn, tokenType, scope]
            description: 'Represents an authentication token'
        AuthenticationTokenIssued:
            type: object
            properties:
                result:
                    const: token
                    description: Discriminator
                accessToken:
                    type: string
                    description: 'The access token string as issued by the authorization server'
                refreshToken:
                    type: string
                    description: 'A refresh token which applications can use to obtain another access token'
                expiresIn:
                    type: integer
                    description: 'Unix timestamp (seconds) when the access token expires'
                tokenType:
                    type: string
                    description: 'The type of token this is, typically just the string *Bearer*'
                scope:
                    type: string
                    description: 'Space-separated list of scopes granted to this token'
            required: [result, accessToken, expiresIn, tokenType, scope]
            description: 'Issued-token arm of /auth/token response'
        MfaChallengeFactor:
            type: object
            properties:
                method:
                    '$ref': '#/components/schemas/AuthenticationFactorMethod'
                    description: 'The factor method'
                methodId:
                    type: string
                    description: "The id of the enrolled factor (opaque to the SPA, must be echoed back in the proof for methods that don't bind another way)"
                kind:
                    '$ref': '#/components/schemas/AuthenticationFactorKind'
                    description: 'The factor kind (knowledge, possession, biometric) — the SPA filters against step-up `acceptableKinds`/`excludeKinds` hints'
                label:
                    type: string
                    description: 'Optional human-readable label (e.g. provider name for OIDC, friendly name for FIDO)'
            required: [method, methodId, kind]
            description: 'A factor the SPA may use to satisfy the MFA challenge'
        MfaRequiredResponse:
            type: object
            properties:
                result:
                    const: mfa_required
                    description: Discriminator
                challengeId:
                    type: string
                    maxLength: 100
                    description: 'The MFA challenge identifier — pass back as `mfa_challenge_id` on the proof grant'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When the MFA challenge expires'
                factors:
                    type: array
                    items:
                        '$ref': '#/components/schemas/MfaChallengeFactor'
                    description: 'Eligible factors the SPA may use to complete the challenge'
            required: [result, challengeId, expiresAt, factors]
            description: 'MFA-required arm of /auth/token response'
        EnrollmentRequiredResponse:
            type: object
            properties:
                result:
                    const: enrollment_required
                    description: Discriminator
            required: [result]
            description: 'Returned by /auth/step-up/start when no enrolled factor satisfies the requirement. The SPA should drive the user through enrollment and retry the gated action afterwards.'
        StepUpStartResponse:
            oneOf:
                - '$ref': '#/components/schemas/MfaRequiredResponse'
                - '$ref': '#/components/schemas/EnrollmentRequiredResponse'
            discriminator:
                propertyName: result
                mapping:
                    mfa_required: '#/components/schemas/MfaRequiredResponse'
                    enrollment_required: '#/components/schemas/EnrollmentRequiredResponse'
        AuthenticationTokenResponse:
            oneOf:
                - '$ref': '#/components/schemas/AuthenticationTokenIssued'
                - '$ref': '#/components/schemas/MfaRequiredResponse'
            discriminator:
                propertyName: result
                mapping:
                    token: '#/components/schemas/AuthenticationTokenIssued'
                    mfa_required: '#/components/schemas/MfaRequiredResponse'
        PublicKeyCredential:
            type: object
            properties:
                id:
                    type: string
                    description: 'The base64url encoding of `rawId`'
                type:
                    const: public-key
                    description: 'This enumeration defines the valid credential types. It is an extension point; values can be added to it in the future, as more credential types are defined. The values of this enumeration are used for versioning the Authentication Assertion and attestation structures according to the type of the authenticator. Currently one credential type is defined, namely `public-key`.'
                rawId:
                    type: string
                    description: 'The credential identifier'
                authenticatorAttachment:
                    type: string
                    enum: [cross-platform, platform]
                    description: 'The authenticator attachment'
            required: [id, type, rawId]
            description: 'Represents a common shape of a `PublicKeyCredential` after the client serializes the `id` and `rawId` fields to base64 strings for transport'
        SimpleClientExtensionResults:
            type: object
            properties:
                appid:
                    type: boolean
                    description: 'Whether the client is an application'
                appidExclude:
                    type: boolean
                    description: 'Whether the client is excluded from appid verification'
                credProps:
                    type: object
                    properties:
                        rk:
                            type: boolean
                            description: 'Whether the client supports the rk extension'
                    required: [rk]
            description: 'Subset of the WebAuthn client extension results the service round-trips'
        FidoAuthenticatorAssertionResponse:
            type: object
            properties:
                clientDataJSON:
                    type: string
                    description: 'The client data JSON'
                authenticatorData:
                    type: string
                    description: 'The authenticator data'
                signature:
                    type: string
                    description: 'The signature'
                userHandle:
                    type: string
                    description: 'The user handle'
            required: [clientDataJSON, authenticatorData, signature]
        PublicKeyCredentialWithAssertion:
            allOf:
                - '$ref': '#/components/schemas/PublicKeyCredential'
                - type: object
                  properties:
                      clientExtensionResults:
                          '$ref': '#/components/schemas/SimpleClientExtensionResults'
                          description: 'The client extension results'
                      response:
                          '$ref': '#/components/schemas/FidoAuthenticatorAssertionResponse'
                          description: 'The authenticator assertion response'
                  required: [clientExtensionResults, response]
        AuthenticationRegistration:
            type: object
            properties:
                registrationId:
                    type: string
                    readOnly: true
                    description: 'The registration identifier'
                expiresAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'The registration expiration timestamp'
                email:
                    type: string
                    format: email
                    writeOnly: true
                    description: "User's email address"
                password:
                    type: string
                    minLength: 8
                    maxLength: 256
                    writeOnly: true
                    description: 'optionally set a password for the user'
            required: [registrationId, expiresAt, email]
        AuthenticationRegistrationVerification:
            type: object
            properties:
                registrationId:
                    type: string
                    description: 'The registration identifier'
                code:
                    type: string
                    minLength: 6
                    maxLength: 10
                    description: 'The verification code'
            required: [registrationId, code]
        BaseAuthenticationLoginStart:
            type: object
            properties:
                grant_type:
                    '$ref': '#/components/schemas/PasswordlessAuthenticationGrantType'
                    description: 'The grant type for the request'
                client_id:
                    type: string
                    format: uuid
                    description: "The application's client identifier, if available"
            required: [grant_type]
        BaseAuthenticationLoginStartWithEmail:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationLoginStart'
                - type: object
                  properties:
                      email:
                          type: string
                          format: email
                          description: "User's email address"
                  required: [email]
        LinkAuthenticationLoginStart:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationLoginStartWithEmail'
                - type: object
                  properties:
                      grant_type:
                          const: link
                          description: 'The grant type for the request'
                      purpose:
                          type: string
                          enum: [signin, reset]
                          description: 'What the link is for. `reset` words the email as a password reset and lands the person on the password form once signed in; the link and what it proves are the same. Absent means `signin`'
                  required: [grant_type]
        CodeAuthenticationLoginStart:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationLoginStartWithEmail'
                - type: object
                  properties:
                      grant_type:
                          const: code
                          description: 'The grant type for the request'
                      code_challenge:
                          type: string
                          maxLength: 100
                          description: 'A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device'
                  required: [grant_type, code_challenge]
        FidoAuthenticationLoginStart:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationLoginStartWithEmail'
                - type: object
                  properties:
                      grant_type:
                          const: fido
                          description: 'The grant type for the request'
                  required: [grant_type]
        OidcAuthenticationLoginStart:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationLoginStart'
                - type: object
                  properties:
                      grant_type:
                          const: oidc
                          description: 'The grant type for the request'
                      provider:
                          '$ref': '#/components/schemas/OidcProvider'
                          description: 'The IdP to authorize against'
                      redirect_after:
                          type: string
                          maxLength: 2048
                          description: 'A path on the console to return to once signed in, such as `/settings/security`. Anything that is not a same-origin path is ignored and the console opens at its home page'
                  required: [grant_type, provider]
        AuthenticationLoginStart:
            oneOf:
                - '$ref': '#/components/schemas/LinkAuthenticationLoginStart'
                - '$ref': '#/components/schemas/CodeAuthenticationLoginStart'
                - '$ref': '#/components/schemas/FidoAuthenticationLoginStart'
                - '$ref': '#/components/schemas/OidcAuthenticationLoginStart'
            discriminator:
                propertyName: grant_type
                mapping:
                    link: '#/components/schemas/LinkAuthenticationLoginStart'
                    code: '#/components/schemas/CodeAuthenticationLoginStart'
                    fido: '#/components/schemas/FidoAuthenticationLoginStart'
                    oidc: '#/components/schemas/OidcAuthenticationLoginStart'
        PublicKeyCredentialDescriptor:
            type: object
            properties:
                type:
                    const: public-key
                    description: 'The credential type — currently always `public-key`'
                id:
                    type: string
                    description: 'The base64url-encoded credential identifier'
                transports:
                    type: array
                    items:
                        type: string
                        enum: [usb, nfc, ble, internal, hybrid]
                    description: 'Transports the authenticator advertises'
            required: [type, id]
            description: 'A credential the relying party expects the user to be able to present'
        BaseAuthenticationLoginStartResponse:
            type: object
            properties:
                grant_type:
                    '$ref': '#/components/schemas/PasswordlessAuthenticationGrantType'
                    description: 'The grant type for the response'
                challengeId:
                    type: string
                    maxLength: 100
                    description: 'The challenge identifier'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'The challenge expiration timestamp'
            required: [grant_type, challengeId, expiresAt]
        CodeAuthenticationLoginStartResponse:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationLoginStartResponse'
                - type: object
                  properties:
                      grant_type:
                          const: code
                          description: 'The grant type for the response'
                  required: [grant_type]
        LinkAuthenticationLoginStartResponse:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationLoginStartResponse'
                - type: object
                  properties:
                      grant_type:
                          const: link
                          description: 'The grant type for the response'
                  required: [grant_type]
        FidoPublicKeyCredentialRequestOptions:
            type: object
            properties:
                challenge:
                    type: string
                timeout:
                    type: integer
                    description: 'WebAuthn timeout hint in milliseconds'
                rpId:
                    type: string
                attestation:
                    type: string
                    enum: [direct, indirect, none]
                    description: 'The attestation'
                userVerification:
                    type: string
                    enum: [required, preferred, discouraged]
                    description: 'Whether the authenticator must verify the user'
                rawChallenge:
                    type: string
                    format: binary
                    description: 'The raw challenge'
                extensions:
                    type: object
                allowCredentials:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PublicKeyCredentialDescriptor'
            required: [challenge]
        FidoAuthenticationLoginStartResponse:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationLoginStartResponse'
                - type: object
                  properties:
                      grant_type:
                          const: fido
                          description: 'The grant type for the response'
                      assertion:
                          '$ref': '#/components/schemas/FidoPublicKeyCredentialRequestOptions'
                          description: 'The WebAuthn assertion options'
                  required: [grant_type, assertion]
        OidcAuthenticationLoginStartResponse:
            allOf:
                - '$ref': '#/components/schemas/BaseAuthenticationLoginStartResponse'
                - type: object
                  properties:
                      grant_type:
                          const: oidc
                          description: 'The grant type for the response'
                      authorize_url:
                          type: string
                          description: 'Fully-formed authorize URL the user-agent should be redirected to'
                      state:
                          type: string
                          maxLength: 200
                          description: 'Opaque state token bound to this authorization round-trip'
                  required: [grant_type, authorize_url, state]
        AuthenticationLoginStartResponse:
            oneOf:
                - '$ref': '#/components/schemas/CodeAuthenticationLoginStartResponse'
                - '$ref': '#/components/schemas/LinkAuthenticationLoginStartResponse'
                - '$ref': '#/components/schemas/FidoAuthenticationLoginStartResponse'
                - '$ref': '#/components/schemas/OidcAuthenticationLoginStartResponse'
            discriminator:
                propertyName: grant_type
                mapping:
                    code: '#/components/schemas/CodeAuthenticationLoginStartResponse'
                    link: '#/components/schemas/LinkAuthenticationLoginStartResponse'
                    fido: '#/components/schemas/FidoAuthenticationLoginStartResponse'
                    oidc: '#/components/schemas/OidcAuthenticationLoginStartResponse'
        FidoAuthenticatorTransport:
            type: string
            enum: [hybrid, ble, internal, nfc, usb]
            description: 'The transport used by the authenticator'
        FidoAuthenticatorAttestationResponse:
            type: object
            properties:
                clientDataJSON:
                    type: string
                    description: 'The client data JSON'
                attestationObject:
                    type: string
                    description: 'The attestation object'
                transports:
                    type: array
                    items:
                        '$ref': '#/components/schemas/FidoAuthenticatorTransport'
                    description: 'The transports used by the authenticator'
            required: [clientDataJSON, attestationObject]
            description: 'Serialized form of `AuthenticatorAttestationResponse` — produced by the browser at registration; all binary fields are base64-encoded for transport'
        PublicKeyCredentialWithAttestation:
            allOf:
                - '$ref': '#/components/schemas/PublicKeyCredential'
                - type: object
                  properties:
                      clientExtensionResults:
                          '$ref': '#/components/schemas/SimpleClientExtensionResults'
                          description: 'The client extension results'
                      response:
                          '$ref': '#/components/schemas/FidoAuthenticatorAttestationResponse'
                          description: 'The authenticator attestation response'
                  required: [clientExtensionResults, response]
        AuthenticationFactor:
            type: object
            properties:
                method:
                    '$ref': '#/components/schemas/AuthenticationFactorMethod'
                    description: 'The method of the factor'
                kind:
                    '$ref': '#/components/schemas/AuthenticationFactorKind'
                    description: 'The kind of the factor'
                methodId:
                    type: string
                    description: 'The method identifier'
                label:
                    type: string
                    description: 'The label for the factor'
            required: [method, kind, methodId]
        OidcProviderSummary:
            type: object
            properties:
                name:
                    '$ref': '#/components/schemas/OidcProvider'
                    description: 'What to start a sign-in with'
                label:
                    type: string
                    description: 'What its button says'
            required: [name, label]
            description: 'An identity provider the sign-in page can offer'
        FactorChallengePhoneStart:
            type: object
            properties:
                method:
                    const: phone
                    description: Discriminator
                transport:
                    const: sms
                    description: 'Delivery channel — only `sms` is supported in this phase'
                mfa_challenge_id:
                    type: string
                    maxLength: 100
                    description: 'The MFA challenge to which this factor challenge is bound'
            required: [method, transport, mfa_challenge_id]
            description: 'Issue a phone SMS challenge during a pending MFA round'
        FactorChallengeFidoStart:
            type: object
            properties:
                method:
                    const: fido
                    description: Discriminator
                mfa_challenge_id:
                    type: string
                    maxLength: 100
                    description: 'The MFA challenge to which this factor challenge is bound'
            required: [method, mfa_challenge_id]
            description: 'Issue a WebAuthn assertion challenge during a pending MFA round'
        FactorChallengeEmailStart:
            type: object
            properties:
                method:
                    const: email
                    description: Discriminator
                mfa_challenge_id:
                    type: string
                    maxLength: 100
                    description: 'The MFA challenge to which this factor challenge is bound'
            required: [method, mfa_challenge_id]
            description: 'Issue an email one-time-code challenge during a pending MFA round. Always a code: a magic link cannot complete an MFA round, since the `code` grant that redeems one takes `code(min=6, max=10)` and a link token is 43 characters'
        FactorChallengeStartRequest:
            oneOf:
                - '$ref': '#/components/schemas/FactorChallengePhoneStart'
                - '$ref': '#/components/schemas/FactorChallengeFidoStart'
                - '$ref': '#/components/schemas/FactorChallengeEmailStart'
            discriminator:
                propertyName: method
                mapping:
                    phone: '#/components/schemas/FactorChallengePhoneStart'
                    fido: '#/components/schemas/FactorChallengeFidoStart'
                    email: '#/components/schemas/FactorChallengeEmailStart'
        FactorChallengePhoneStartResponse:
            type: object
            properties:
                method:
                    const: phone
                    description: Discriminator
                transport:
                    const: sms
                    description: 'Echo of the chosen delivery channel'
                phoneChallengeId:
                    type: string
                    maxLength: 100
                    description: 'The phone-factor challenge id — echo back on the `code` grant as `challenge_id`'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When the phone challenge expires'
            required: [method, transport, phoneChallengeId, expiresAt]
            description: 'Response for a phone SMS challenge'
        FactorChallengeFidoStartResponse:
            type: object
            properties:
                method:
                    const: fido
                    description: Discriminator
                fidoChallengeId:
                    type: string
                    maxLength: 100
                    description: 'The FIDO-factor challenge id — echo back on the `fido` grant as `challenge_id`'
                assertion:
                    '$ref': '#/components/schemas/FidoPublicKeyCredentialRequestOptions'
                    description: 'WebAuthn assertion options for navigator.credentials.get'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When the FIDO challenge expires'
            required: [method, fidoChallengeId, assertion, expiresAt]
            description: 'Response for a FIDO assertion challenge'
        FactorChallengeEmailStartResponse:
            type: object
            properties:
                method:
                    const: email
                    description: Discriminator
                emailChallengeId:
                    type: string
                    maxLength: 100
                    description: 'The email-factor challenge id — echo back on the `code` grant as `challenge_id`'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When the email challenge expires'
            required: [method, emailChallengeId, expiresAt]
            description: 'Response for an email one-time-code challenge'
        FactorChallengeStartResponse:
            oneOf:
                - '$ref': '#/components/schemas/FactorChallengePhoneStartResponse'
                - '$ref': '#/components/schemas/FactorChallengeFidoStartResponse'
                - '$ref': '#/components/schemas/FactorChallengeEmailStartResponse'
            discriminator:
                propertyName: method
                mapping:
                    phone: '#/components/schemas/FactorChallengePhoneStartResponse'
                    fido: '#/components/schemas/FactorChallengeFidoStartResponse'
                    email: '#/components/schemas/FactorChallengeEmailStartResponse'
        StepUpStartRequest:
            type: object
            properties:
                acceptableMethods:
                    type: array
                    items:
                        '$ref': '#/components/schemas/AuthenticationFactorMethod'
                    description: 'If set, only these factor methods are listed as eligible'
                acceptableKinds:
                    type: array
                    items:
                        '$ref': '#/components/schemas/AuthenticationFactorKind'
                    description: 'If set, only these factor kinds are listed as eligible'
                excludeMethods:
                    type: array
                    items:
                        '$ref': '#/components/schemas/AuthenticationFactorMethod'
                    description: 'If set, factors with these methods are never listed'
            description: 'Mint a fresh MFA challenge for the current session so the SPA can satisfy a `step_up_required` denial. Filters mirror `StepUpRequirement` from `@maroonedsoftware/policies`.'
        SessionFactor:
            type: object
            properties:
                method:
                    type: string
                    enum: [phone, password, authenticator, email, fido, oidc]
                    description: 'The verification method'
                methodId:
                    type: string
                    maxLength: 255
                    description: 'Stable identifier for the specific factor record'
                kind:
                    type: string
                    enum: [knowledge, possession, biometric]
                    description: 'MFA category for the factor'
                issuedAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When this factor entry was first added to the session'
                authenticatedAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When the factor was most recently re-verified'
            required: [method, methodId, kind, issuedAt, authenticatedAt]
            description: 'A factor satisfied by the session'
        Session:
            type: object
            properties:
                sessionToken:
                    type: string
                    maxLength: 255
                    readOnly: true
                    description: 'Opaque session token used as the cache key and embedded in JWTs'
                actorId:
                    type: string
                    format: uuid
                    readOnly: true
                    description: 'The actor that owns this session'
                issuedAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When the session was originally issued'
                expiresAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When the session expires'
                lastAccessedAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When the session was last accessed'
                factors:
                    type: array
                    items:
                        '$ref': '#/components/schemas/SessionFactor'
                    readOnly: true
                    description: 'Factors that have been satisfied in this session'
                ip:
                    type: [string, 'null']
                    maxLength: 64
                    readOnly: true
                    description: 'IP address recorded when the session was created'
                userAgent:
                    type: [string, 'null']
                    maxLength: 512
                    readOnly: true
                    description: 'User agent recorded when the session was created'
                isCurrent:
                    type: boolean
                    readOnly: true
                    description: 'True when this session matches the requesting session'
            required:
                - sessionToken
                - actorId
                - issuedAt
                - expiresAt
                - lastAccessedAt
                - factors
                - isCurrent
            description: 'An active authentication session'
        PlatformRole:
            type: string
            enum: [admin, listener]
            description: 'A platform-wide role held on `platform:main`. `admin` grants every operation; `listener` grants the reads'
        AuthSession:
            type: object
            properties:
                actorId:
                    type: string
                    maxLength: 100
                    description: 'The actor the session belongs to'
                roles:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PlatformRole'
                    description: 'Every platform role the caller holds, sorted. Empty for an account nobody has granted one, which today is any account that did not come in through onboarding'
            required: [actorId, roles]
            description: 'Who the caller is, as the station sees them'
        ApiKeyScope:
            type: string
            enum: [view, manage]
            description: 'What an API key may be granted. `view` covers every route a listener may read; `manage` covers the rest, and includes `view`'
        ApiKey:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    description: "The key's identifier, for rotating or revoking it"
                name:
                    type: string
                    maxLength: 100
                    description: 'What the account called the key'
                hint:
                    type: string
                    maxLength: 16
                    description: "The token's first characters, enough to recognise the key in a config file and far too few to use"
                scopes:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ApiKeyScope'
                    description: 'What the key was granted. A key never does more than the account that owns it'
                createdAt:
                    type: string
                    format: date-time
                    description: 'When the key was issued'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When the key stops working. Absent means it never expires'
                lastUsedAt:
                    type: string
                    format: date-time
                    description: 'When the key was last used, to within five minutes. Absent means it has not been used'
                revokedAt:
                    type: string
                    format: date-time
                    description: 'When the key was revoked. Present means every request made with it is refused'
            required: [id, name, hint, scopes, createdAt]
            description: 'A personal API key, as its owner sees it in a list. The token itself is never returned after it is issued'
        ApiKeyList:
            type: object
            properties:
                keys:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ApiKey'
            required: [keys]
            description: 'Every API key the account holds, newest first, revoked and expired keys included'
        ApiKeyCreate:
            type: object
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'What to call the key, so a list of several says which is which'
                scopes:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ApiKeyScope'
                    description: 'What the key may do. At least one; `manage` includes `view`'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When the key should stop working. Omit for a key that never expires'
            required: [name, scopes]
            description: 'A new API key'
        ApiKeyIssued:
            type: object
            properties:
                key:
                    '$ref': '#/components/schemas/ApiKey'
                    description: 'The key as it will appear in the list'
                token:
                    type: string
                    description: 'The bearer token, sent as `Authorization: Bearer <token>`'
            required: [key, token]
            description: 'A key and its token. The only time the token is ever returned: store it now, because nothing can show it again'
        PhoneFactorRegistration:
            type: object
            properties:
                method:
                    const: phone
                    description: 'The method of the factor'
                value:
                    type: string
                    pattern: '^\+[1-9]\d{1,14}$'
                    description: 'The phone number in E.164 format (e.g. `+12025550123`)'
                codeChallenge:
                    type: string
                    maxLength: 100
                    description: 'A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device'
            required: [method, value, codeChallenge]
        PasswordFactorRegistration:
            type: object
            properties:
                method:
                    const: password
                    description: 'The method of the factor'
                value:
                    type: string
                    minLength: 8
                    maxLength: 256
                    description: 'The password'
            required: [method, value]
        PasswordChange:
            type: object
            properties:
                password:
                    type: string
                    minLength: 8
                    maxLength: 256
                    description: 'The new password'
                currentPassword:
                    type: string
                    maxLength: 256
                    description: 'The password it replaces. Needed when the account has one, unless a sign-in link was used in the last ten minutes'
            required: [password]
        EmailFactorRegistration:
            type: object
            properties:
                method:
                    const: email
                    description: 'The method of the factor'
                value:
                    type: string
                    format: email
                    description: 'The email address'
                codeChallenge:
                    type: string
                    maxLength: 100
                    description: 'A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device'
            required: [method, value, codeChallenge]
        AuthenticatorFactorRegistration:
            type: object
            properties:
                method:
                    const: authenticator
                    description: 'The method of the factor'
                codeChallenge:
                    type: string
                    maxLength: 100
                    description: 'A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device'
                label:
                    type: string
                    description: 'The label for the authenticator factor'
            required: [method, codeChallenge]
        FidoFactorRegistration:
            type: object
            properties:
                method:
                    const: fido
                    description: 'The method of the factor'
                label:
                    type: string
                    description: 'The label for the FIDO factor'
            required: [method]
        OidcFactorRegistration:
            type: object
            properties:
                method:
                    const: oidc
                    description: 'The method of the factor'
                provider:
                    '$ref': '#/components/schemas/OidcProvider'
                    description: 'The provider to link, as `GET /auth/login/oidc/providers` names it'
            required: [method, provider]
            description: "Link an identity provider to the signed-in account. Answered with the provider's address; the browser goes there and comes back to Security"
        AuthenticationFactorRegistration:
            oneOf:
                - '$ref': '#/components/schemas/PhoneFactorRegistration'
                - '$ref': '#/components/schemas/PasswordFactorRegistration'
                - '$ref': '#/components/schemas/EmailFactorRegistration'
                - '$ref': '#/components/schemas/AuthenticatorFactorRegistration'
                - '$ref': '#/components/schemas/FidoFactorRegistration'
                - '$ref': '#/components/schemas/OidcFactorRegistration'
            discriminator:
                propertyName: method
                mapping:
                    phone: '#/components/schemas/PhoneFactorRegistration'
                    password: '#/components/schemas/PasswordFactorRegistration'
                    email: '#/components/schemas/EmailFactorRegistration'
                    authenticator: '#/components/schemas/AuthenticatorFactorRegistration'
                    fido: '#/components/schemas/FidoFactorRegistration'
                    oidc: '#/components/schemas/OidcFactorRegistration'
        PhoneFactorRegistrationResponse:
            type: object
            properties:
                method:
                    const: phone
                    description: 'The method of the factor'
                registrationId:
                    type: string
                    description: 'The registration identifier'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'The expiration timestamp'
                issuedAt:
                    type: string
                    format: date-time
                    description: 'The issuance timestamp'
            required: [method, registrationId, expiresAt, issuedAt]
        PasswordFactorRegistrationResponse:
            type: object
            properties:
                method:
                    const: password
                    description: 'The method of the factor'
                needsReset:
                    type: boolean
                    description: 'Whether the password needs to be reset'
            required: [method, needsReset]
        EmailFactorRegistrationResponse:
            type: object
            properties:
                method:
                    const: email
                    description: 'The method of the factor'
                registrationId:
                    type: string
                    description: 'The registration identifier'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'The expiration timestamp'
                issuedAt:
                    type: string
                    format: date-time
                    description: 'The issuance timestamp'
            required: [method, registrationId, expiresAt, issuedAt]
        AuthenticatorFactorRegistrationResponse:
            type: object
            properties:
                method:
                    const: authenticator
                    description: 'The method of the factor'
                registrationId:
                    type: string
                    description: 'The registration identifier'
                secret:
                    type: string
                    description: 'The secret for the authenticator'
                uri:
                    type: string
                    description: 'The URI for the authenticator'
                qrCode:
                    type: string
                    description: 'The QR code for the authenticator'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'The expiration timestamp'
                issuedAt:
                    type: string
                    format: date-time
                    description: 'The issuance timestamp'
            required: [method, registrationId, secret, uri, qrCode, expiresAt, issuedAt]
        FidoFactorAttestation:
            type: object
            properties:
                rp:
                    type: object
                    properties:
                        name:
                            type: string
                            description: 'The relying party name'
                        id:
                            type: string
                            description: 'The relying party identifier'
                        icon:
                            type: string
                            description: 'The relying party icon'
                    required: [name, id]
                    description: 'The relying party'
                user:
                    type: object
                    properties:
                        id:
                            type: string
                            description: 'The user identifier'
                        name:
                            type: string
                            description: 'The user name'
                        displayName:
                            type: string
                            description: 'The user display name'
                    required: [id, name, displayName]
                challenge:
                    type: string
                    description: 'The challenge'
                pubKeyCredParams:
                    type: array
                    items:
                        type: object
                        properties:
                            type:
                                const: public-key
                            alg:
                                type: integer
                        required: [type, alg]
                    description: 'The public key credential parameters'
                timeout:
                    type: integer
                    description: 'The timeout'
                attestation:
                    type: string
                    enum: [direct, indirect, none]
                    description: 'The attestation'
            required: [rp, user, challenge, pubKeyCredParams, attestation]
            description: 'The FIDO factor attestation information'
        FidoFactorRegistrationResponse:
            type: object
            properties:
                method:
                    const: fido
                    description: 'The method of the factor'
                registrationId:
                    type: string
                    description: 'The registration identifier'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'The expiration timestamp'
                issuedAt:
                    type: string
                    format: date-time
                    description: 'The issuance timestamp'
                attestation:
                    '$ref': '#/components/schemas/FidoFactorAttestation'
                    description: 'The FIDO factor attestation information'
            required: [method, registrationId, expiresAt, issuedAt, attestation]
        OidcFactorRegistrationResponse:
            type: object
            properties:
                method:
                    const: oidc
                    description: 'The method of the factor'
                authorizeUrl:
                    type: string
                    description: 'Where to send the browser. The provider sends it back to Security, with `?linked=<provider>` on success'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When the link attempt expires if the provider has not answered'
            required: [method, authorizeUrl, expiresAt]
        AuthenticationFactorRegistrationResponse:
            oneOf:
                - '$ref': '#/components/schemas/PhoneFactorRegistrationResponse'
                - '$ref': '#/components/schemas/PasswordFactorRegistrationResponse'
                - '$ref': '#/components/schemas/EmailFactorRegistrationResponse'
                - '$ref': '#/components/schemas/AuthenticatorFactorRegistrationResponse'
                - '$ref': '#/components/schemas/FidoFactorRegistrationResponse'
                - '$ref': '#/components/schemas/OidcFactorRegistrationResponse'
            discriminator:
                propertyName: method
                mapping:
                    phone: '#/components/schemas/PhoneFactorRegistrationResponse'
                    password: '#/components/schemas/PasswordFactorRegistrationResponse'
                    email: '#/components/schemas/EmailFactorRegistrationResponse'
                    authenticator: '#/components/schemas/AuthenticatorFactorRegistrationResponse'
                    fido: '#/components/schemas/FidoFactorRegistrationResponse'
                    oidc: '#/components/schemas/OidcFactorRegistrationResponse'
        PhoneFactorRegistrationVerification:
            type: object
            properties:
                method:
                    const: phone
                    description: 'The method of the factor'
                registrationId:
                    type: string
                    description: 'The registration identifier'
                code:
                    type: string
                    minLength: 6
                    maxLength: 10
                    description: 'The verification code'
                codeVerifier:
                    type: string
                    minLength: 43
                    maxLength: 128
                    description: 'A base64url encoded one time secret used to validate that the request starts and ends on the same device'
            required: [method, registrationId, code, codeVerifier]
        EmailFactorRegistrationVerification:
            type: object
            properties:
                method:
                    const: email
                    description: 'The method of the factor'
                registrationId:
                    type: string
                    description: 'The registration identifier'
                code:
                    type: string
                    minLength: 6
                    maxLength: 10
                    description: 'The verification code'
                codeVerifier:
                    type: string
                    minLength: 43
                    maxLength: 128
                    description: 'A base64url encoded one time secret used to validate that the request starts and ends on the same device'
            required: [method, registrationId, code, codeVerifier]
        AuthenticatorFactorRegistrationVerification:
            type: object
            properties:
                method:
                    const: authenticator
                    description: 'The method of the factor'
                registrationId:
                    type: string
                    description: 'The registration identifier'
                code:
                    type: string
                    minLength: 6
                    maxLength: 10
                    description: 'The verification code'
                codeVerifier:
                    type: string
                    minLength: 43
                    maxLength: 128
                    description: 'A base64url encoded one time secret used to validate that the request starts and ends on the same device'
            required: [method, registrationId, code, codeVerifier]
        FidoFactorRegistrationVerification:
            type: object
            properties:
                method:
                    const: fido
                    description: 'The method of the factor'
                registrationId:
                    type: string
                    description: 'The registration identifier'
                credential:
                    '$ref': '#/components/schemas/PublicKeyCredentialWithAttestation'
                    description: 'The credential the client posts back to complete registration'
            required: [method, registrationId, credential]
        AuthenticationFactorRegistrationVerification:
            oneOf:
                - '$ref': '#/components/schemas/PhoneFactorRegistrationVerification'
                - '$ref': '#/components/schemas/EmailFactorRegistrationVerification'
                - '$ref': '#/components/schemas/AuthenticatorFactorRegistrationVerification'
                - '$ref': '#/components/schemas/FidoFactorRegistrationVerification'
            discriminator:
                propertyName: method
                mapping:
                    phone: '#/components/schemas/PhoneFactorRegistrationVerification'
                    email: '#/components/schemas/EmailFactorRegistrationVerification'
                    authenticator: '#/components/schemas/AuthenticatorFactorRegistrationVerification'
                    fido: '#/components/schemas/FidoFactorRegistrationVerification'
        Rating:
            type: string
            enum: [liked, neutral, disliked]
            description: "What the station has been told about a record. `neutral` is the absence of an opinion rather than\na middling one, and it is what rating something back to nothing means."
        RateInput:
            type: object
            properties:
                rating:
                    '$ref': '#/components/schemas/Rating'
            required: [rating]
            description: "Rate an artist, a record or a song. Ratings are absolute: a dislike anywhere above a track\nexcludes it, and nothing the station programmes may turn that off."
        Artist:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    readOnly: true
                name:
                    type: string
                mbid:
                    type: string
                    format: uuid
                    description: 'MusicBrainz artist id, absent until enrichment resolves one'
                imageUrl:
                    type: string
                    description: "An API-relative path: the cached copy, or the station's proxy for an uncached one"
                rating:
                    '$ref': '#/components/schemas/Rating'
                    default: neutral
                suspendedUntil:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'Kept off the station until this moment: a scheduling decision with an end date, which leaves `rating` alone. Absent is not suspended, and a suspension that has lapsed is simply absent'
                albumCount:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Unmerged albums credited to this artist'
                trackCount:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Unmerged tracks credited to this artist'
            required: [id, name, rating, albumCount, trackCount]
            description: "The canonical work, not a binding to a provider. `deadair.artists` minus the columns that\nonly ingest cares about: `artist_key` is a match key, and a row with `merged_into_id` set is\nnever read out at all.\n\n`imageUrl` on both contracts below is always a path under the API root, never a provider's URL:\n`art/<uuid>` for the station's cached copy, or `art/source/<token>` for one it has not cached\nyet, which the station fetches on first ask and serves as its own. Resolve either against the\nAPI base the client already configures (the API mounts at the root and does not know the `/api`\nprefix the edge adds). The switch from the second to the first happens server-side."
        Album:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    readOnly: true
                name:
                    type: string
                artistId:
                    type: string
                    format: uuid
                    readOnly: true
                artistName:
                    type: string
                    readOnly: true
                    description: 'Joined, so a list renders without a second request per row'
                mbid:
                    type: string
                    format: uuid
                    description: 'MusicBrainz release-group id, absent until enrichment resolves one'
                year:
                    type: integer
                imageUrl:
                    type: string
                    description: "An API-relative path: the cached copy, or the station's proxy for an uncached one"
                rating:
                    '$ref': '#/components/schemas/Rating'
                    default: neutral
                suspendedUntil:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'Kept off the station until this moment: a scheduling decision with an end date, which leaves `rating` alone. Absent is not suspended, and a suspension that has lapsed is simply absent'
                trackCount:
                    type: integer
                    minimum: 0
                    readOnly: true
            required: [id, name, artistId, artistName, rating, trackCount]
        Track:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    readOnly: true
                title:
                    type: string
                artistId:
                    type: string
                    format: uuid
                    readOnly: true
                artistName:
                    type: string
                    readOnly: true
                albumId:
                    type: string
                    format: uuid
                    readOnly: true
                    description: 'Absent on a single ingested outside any release: `tracks.album_id` is nullable'
                albumName:
                    type: string
                    readOnly: true
                albumImageUrl:
                    type: string
                    readOnly: true
                    description: "The record's cover, as `Album.imageUrl` spells it. Nothing hangs art off a recording"
                artists:
                    type: string
                    description: 'Display credit as written on the release ("X feat. Y"), not a join key'
                genre:
                    type: string
                year:
                    type: integer
                durationMs:
                    type: integer
                    minimum: 0
                rating:
                    '$ref': '#/components/schemas/Rating'
                    default: neutral
                suspendedUntil:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'Kept off the station until this moment: a scheduling decision with an end date, which leaves `rating` alone. Absent is not suspended, and a suspension that has lapsed is simply absent'
            required: [id, title, artistId, artistName, artists, rating]
        TrackBinding:
            type: object
            properties:
                sourceId:
                    type: string
                    format: uuid
                    readOnly: true
                    description: '`track_sources.id`, which is also what the audio URL carries'
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                externalId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    readOnly: true
                playable:
                    type: boolean
                    readOnly: true
                    description: 'False when the provider still knows the record but will not serve it here'
                missingAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When the station gave up on this copy. Cleared by the next sync that sees it again'
                origin:
                    type: string
                    minLength: 1
                    maxLength: 40
                    readOnly: true
                    description: '`sync` if a playlist walk saw it, `discovered` if something looked it up'
                bitrate:
                    type: integer
                    minimum: 0
                    readOnly: true
                format:
                    type: string
                    maxLength: 100
                    readOnly: true
                lastSeenAt:
                    type: string
                    format: date-time
                    readOnly: true
                byteSize:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'What the station holds of this copy, absent when nothing has ever fetched it.'
                fetchedAt:
                    type: string
                    format: date-time
                    readOnly: true
                lastServedAt:
                    type: string
                    format: date-time
                    readOnly: true
                attempts:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'CONSECUTIVE failures. Reset by a fetch that works'
                lastError:
                    type: string
                    maxLength: 2000
                    readOnly: true
                nextAttemptAt:
                    type: string
                    format: date-time
                    readOnly: true
            required: [sourceId, pluginId, externalId, playable, origin, attempts]
            description: "One provider's copy of a record, with whatever the station holds of it.\n\nPER BINDING and never per track, which is the rule the whole page is built on: one canonical\nrecord may bind to several copies inside one provider, those copies are different files with\ndifferent loudness and different cue points, and the one that airs is the one that was resolved.\nCollapsing them would make \"clear the audio\" ambiguous about which file it took.\n\nThe failure columns are here rather than hidden because that is the question this page exists to\nanswer. A row with `attempts` and no `fetchedAt` is a remembered failure, and `lastError` with\n`nextAttemptAt` is the whole of why a perfectly good-looking record will not play."
        TrackAnalysis:
            type: object
            properties:
                schemaVersion:
                    type: integer
                    minimum: 0
                    readOnly: true
                complete:
                    type: boolean
                    readOnly: true
                analyzer:
                    type: string
                    maxLength: 200
                    readOnly: true
                    description: 'The measuring thing itself, which is not the plugin adapting it'
                analyzerPluginId:
                    type: string
                    maxLength: 200
                    readOnly: true
                analyzedAt:
                    type: string
                    format: date-time
                    readOnly: true
                failedAt:
                    type: string
                    format: date-time
                    readOnly: true
                failureReason:
                    type: string
                    maxLength: 2000
                    readOnly: true
                bpm:
                    type: number
                    minimum: 0
                    readOnly: true
                    description: "The record's tempo in beats a minute, as measured from its audio. Absent where it has no pulse to report, or has not been measured for one yet"
                beatConfidence:
                    type: number
                    minimum: 0
                    maximum: 1
                    readOnly: true
                    description: 'How far to trust that tempo, from 0 to 1. Low on a record that changes tempo or feel'
                failureCode:
                    '$ref': '#/components/schemas/MeasureFailure'
                    readOnly: true
                    description: 'Which kind of failure it was, which decides when the walk tries again. Present whenever `failedAt` is'
            required: [schemaVersion, complete]
            description: "What the measurement sidecar made of a record.\n\n`complete` is NOT `analyzedAt`, and the two are separate fields for a reason `0005_music.sql`\nargues at length: a measurement of a truncated download is confident and wrong, so every reader in\nthe app filters on `complete` and a page that showed only a date would be reporting a record as\nmeasured that nothing will use the measurement of."
        MeasureFailure:
            type: string
            enum: [unfetchable, undecodable, truncated]
            description: "Why a measurement failed, as the station retries it.\n\n  unfetchable  the bytes could not be fetched: a provider was down or a link expired. Tried again within the hour\n  truncated    the fetch stopped part of the way through. Tried again within the hour\n  undecodable  the file itself would not decode. Tried again after a day, since retrying sooner is the same bytes again\n\nA failure recorded before the station kept the kind reads as `undecodable`, because that is the clock it is retried on."
        TrackPlay:
            type: object
            properties:
                airedAt:
                    type: string
                    format: date-time
                    readOnly: true
                broadcastId:
                    type: string
                    format: uuid
                    readOnly: true
                source:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                    description: 'What put it in the running order'
            required: [airedAt, source]
            description: 'One airing of a record, as this page needs it: when, and under which broadcast.'
        TrackDetail:
            allOf:
                - '$ref': '#/components/schemas/Track'
                - type: object
                  properties:
                      bindings:
                          type: array
                          items:
                              '$ref': '#/components/schemas/TrackBinding'
                      analysis:
                          '$ref': '#/components/schemas/TrackAnalysis'
                          description: 'Absent for a record the walk has not reached'
                      plays:
                          type: array
                          items:
                              '$ref': '#/components/schemas/TrackPlay'
                          description: 'The most recent airings, newest first'
                      playCount:
                          type: integer
                          minimum: 0
                          readOnly: true
                          description: 'How many times in all, which the list above is only the head of'
                  required: [bindings, plays, playCount]
        TrackClearResult:
            type: object
            properties:
                trackId:
                    type: string
                    format: uuid
                    readOnly: true
                cleared:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Rows this affected. Zero is an ordinary answer, not a failure'
                detail:
                    type: string
                    minLength: 1
                    maxLength: 400
                    readOnly: true
                    description: 'What happened, in the words the console shows'
            required: [trackId, cleared, detail]
            description: "What a clear actually did.\n\nA count rather than a bare 204, because the interesting answers are the small ones: clearing the\naudio of a record with three copies and being told `1` is the station saying two of them were\nnever here — which is a fact about the record and not about the button."
        VocalMarkersDetail:
            type: object
            properties:
                trackId:
                    type: string
                    format: uuid
                    readOnly: true
                kind:
                    type: string
                    enum: [instrumental, ranges, unknown]
                    readOnly: true
                    description: 'Nobody sings on it; where the singing is; or nothing to go on'
                onsetMs:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Where the first sung word lands, when kind is ranges'
                endMs:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Where the singing stops, when it is known'
                source:
                    type: string
                    enum: [override, lyrics, none]
                    readOnly: true
                    description: "An operator's correction, the record's timed lyrics, or neither"
            required: [trackId, kind, source]
            description: "Where the singing starts and stops on one record, and which answer that is. Times are milliseconds\nfrom the start of the file, the timeline a lyric's timings use. Never the words themselves."
        LyricWordDetail:
            type: object
            properties:
                atMs:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Where this piece starts being sung'
                text:
                    type: string
                    readOnly: true
                    description: "The piece, with any space after it, so a line's pieces joined are its text exactly"
            required: [atMs, text]
            description: "One timed piece of a lyric line: a word, or a syllable, and when it starts being sung. Milliseconds\nfrom the start of the file, as the line's own start is."
        LyricLineDetail:
            type: object
            properties:
                atMs:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Where the line starts'
                endMs:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Where the line ends, when the source published one. Absent rather than guessed'
                text:
                    type: string
                    readOnly: true
                    description: 'The words of the line. Empty for a gap the source marked between lines'
                words:
                    type: array
                    items:
                        '$ref': '#/components/schemas/LyricWordDetail'
                    readOnly: true
                    description: 'The line cut where its source timed each word, in order, when the source times words. Joined, the pieces are text'
            required: [atMs, text]
            description: "One timed line of a record's lyrics. Times are milliseconds from the start of the file."
        TrackLyrics:
            type: object
            properties:
                trackId:
                    type: string
                    format: uuid
                    readOnly: true
                kind:
                    type: string
                    enum: [words, instrumental, none]
                    readOnly: true
                    description: 'The words are here; a source says nobody sings on it; or no source has an answer yet'
                provider:
                    type: string
                    readOnly: true
                    description: 'The plugin whose answer this is, when kind is words or instrumental'
                plain:
                    type: string
                    readOnly: true
                    description: 'The words without timings, when that source has them'
                synced:
                    type: array
                    items:
                        '$ref': '#/components/schemas/LyricLineDetail'
                    readOnly: true
                    description: 'The timed lines, when that source has them. Preferred over plain when choosing a source'
                language:
                    type: string
                    readOnly: true
                    description: 'A BCP 47 tag, when the source stated one'
            required: [trackId, kind]
            description: "The station's answer for one record's lyrics: the words from the source it believes, or that nobody\nsings on it, or nothing. Timings count from the start of the file, as the vocal markers' do, so a\nplayer following along adds the record's cue-in to how long it has been on air."
        TrackLyricsSource:
            type: object
            properties:
                provider:
                    type: string
                    readOnly: true
                    description: 'The plugin that answered'
                providerRef:
                    type: string
                    readOnly: true
                    description: "The source's own id for what it matched"
                plain:
                    type: string
                    readOnly: true
                synced:
                    type: array
                    items:
                        '$ref': '#/components/schemas/LyricLineDetail'
                    readOnly: true
                language:
                    type: string
                    readOnly: true
                instrumental:
                    type: boolean
                    readOnly: true
                    description: 'The source says nobody sings on this record, so it holds no words'
                fetchedAt:
                    type: string
                    format: date-time
                    readOnly: true
            required: [provider, instrumental, fetchedAt]
            description: "One lyrics source's answer for one record. A source that was asked and had nothing is not listed."
        TrackLyricsSources:
            type: object
            properties:
                trackId:
                    type: string
                    format: uuid
                    readOnly: true
                sources:
                    type: array
                    items:
                        '$ref': '#/components/schemas/TrackLyricsSource'
                    readOnly: true
            required: [trackId, sources]
            description: "Every lyrics source's answer for one record, in the order the station believes them."
        VocalMarkersInput:
            type: object
            properties:
                instrumental:
                    type: boolean
                    default: false
                    description: 'Nobody sings on this record, whatever its lyrics say'
                onsetMs:
                    type: integer
                    minimum: 0
                    description: 'Where the first sung word lands, from the start of the file. Required unless instrumental'
                endMs:
                    type: integer
                    minimum: 0
                    description: 'Where the singing stops. Optional, and after the onset'
            description: "An operator's correction: either the record is instrumental, or the singing starts at `onsetMs`."
        ClearEnrichmentQuery:
            type: object
            properties:
                provider:
                    type: string
                    minLength: 1
                    maxLength: 200
            description: "Narrow a clear to one provider's answer, for the case where one source is wrong and the rest are\nnot. Absent clears every provider's."
        CatalogSort:
            type: string
            enum: [name, albums, tracks, year, rating]
            description: "What an artist or album list is ordered BY, where `Pagination.sort` says only which direction.\n\n  name    the default, and the only key every row here has\n  albums  how many records the station holds of them. Artists only\n  tracks  how many songs. Artists only\n  year    when the record came out. Albums only\n  rating  the operator's own opinion\n\nOne enum for both lists rather than two, because the alternative is a second near-identical\ncontract whose only content is which two keys it drops. A key the row cannot answer falls back to\nname order rather than failing: an ordering nobody can serve is a page an operator cannot open."
        CatalogQuery:
            allOf:
                - '$ref': '#/components/schemas/Pagination'
                - type: object
                  properties:
                      search:
                          type: string
                          minLength: 1
                          maxLength: 200
                      sortBy:
                          '$ref': '#/components/schemas/CatalogSort'
        TrackState:
            type: string
            enum: [cached, uncached, unmeasured, benched, failing, suspended]
            description: "Which records to show, by what the station has of them rather than by what they are.\n\n  cached      the audio is on this machine, so it can be committed to the running order now\n  uncached    it is not, which for most of a library is ordinary rather than wrong\n  unmeasured  no trustworthy measurement, so no cue points and no level decided before air\n  benched     every copy written off, which is the one state that means it CANNOT air\n  failing     a fetch has failed and is backing off. Not benched yet, and often the state before it\n  suspended   kept off the station until a date, by the record itself, its release, or an artist credited on it"
        TrackSort:
            type: string
            enum: [title, artist, album, year, duration, rating]
            description: "What a track list is ordered BY. Its own enum for `TrackQuery`'s own reason: none of these keys\nmeans anything about an artist, and `name` is spelled `title` on a song.\n\n`state` is deliberately absent. It is three independent booleans rather than one column, so there\nis no ordering of it an operator would agree with: a benched record and an unmeasured one are not\nmore or less than each other."
        TrackQuery:
            allOf:
                - '$ref': '#/components/schemas/CatalogQuery'
                - type: object
                  properties:
                      state:
                          '$ref': '#/components/schemas/TrackState'
                      sortBy:
                          '$ref': '#/components/schemas/TrackSort'
                      analyzer:
                          type: string
                          minLength: 1
                          maxLength: 200
                          description: "Only records this analysis plugin measured, or tried to and failed. The selector for measuring a detector's records again"
                      measureFailure:
                          '$ref': '#/components/schemas/MeasureFailure'
                          description: 'Only records whose measurement failed this way'
        TrackStateCounts:
            type: object
            properties:
                total:
                    type: integer
                    minimum: 0
                    readOnly: true
                cached:
                    type: integer
                    minimum: 0
                    readOnly: true
                measured:
                    type: integer
                    minimum: 0
                    readOnly: true
                enriched:
                    type: integer
                    minimum: 0
                    readOnly: true
                benched:
                    type: integer
                    minimum: 0
                    readOnly: true
                failing:
                    type: integer
                    minimum: 0
                    readOnly: true
                suspended:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Kept off the station right now by a suspension on the record, its release or a credited artist'
                lyrics:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'A lyrics source has the words of it. The words themselves are at `/catalog/tracks/{id}/lyrics`'
                synced:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'A lyrics source has the timing of its lines, which says when the singing starts'
                instrumental:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'A lyrics source says nobody sings on it'
                moods:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'A model has judged what mood it is in'
                analyzers:
                    type: array
                    items:
                        '$ref': '#/components/schemas/TrackAnalyzerCount'
                    readOnly: true
                    description: 'Which analysis plugins measured the records, or tried to, most first. What the `analyzer` filter is chosen from'
                measureFailures:
                    '$ref': '#/components/schemas/MeasureFailureCounts'
                    readOnly: true
                    description: 'How many measurements failed, by kind'
            required:
                - total
                - cached
                - measured
                - enriched
                - benched
                - failing
                - suspended
                - lyrics
                - synced
                - instrumental
                - moods
                - analyzers
                - measureFailures
            description: "How much of the library is in each state, over the whole filtered set rather than this page.\n\nThe aggregate is what an operator reads first — \"13 of 581 measured\" is the sentence that made\n[analysis-queue-ordering](https://github.com/robert-dean/deadair/discussions/5) necessary, and it was a psql query then. `total` is the\nsame number as `meta.total` when nothing is filtered, and is repeated here so the counts can be\nread as N of M without reaching into the pager."
        TrackAnalyzerCount:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                count:
                    type: integer
                    minimum: 0
                    readOnly: true
            required: [pluginId, count]
            description: 'How many records one analysis plugin measured or tried to.'
        MeasureFailureCounts:
            type: object
            properties:
                unfetchable:
                    type: integer
                    minimum: 0
                    readOnly: true
                undecodable:
                    type: integer
                    minimum: 0
                    readOnly: true
                truncated:
                    type: integer
                    minimum: 0
                    readOnly: true
            required: [unfetchable, undecodable, truncated]
            description: 'Failed measurements by kind. See `MeasureFailure`.'
        TrackRow:
            allOf:
                - '$ref': '#/components/schemas/Track'
                - type: object
                  properties:
                      hasAudio:
                          type: boolean
                          readOnly: true
                          description: 'The bytes are on this machine'
                      measured:
                          type: boolean
                          readOnly: true
                          description: 'Measured, COMPLETE, and at a schema version the station still trusts'
                      enriched:
                          type: boolean
                          readOnly: true
                          description: 'At least one provider has answered about it'
                      suspended:
                          type: boolean
                          readOnly: true
                          description: "Kept off the station right now, by a suspension on the record, its release or an artist credited on it. `suspendedUntil` is only the record's own. Absent or false is not suspended"
                  required: [hasAudio, measured, enriched]
        ArtistPage:
            type: object
            properties:
                meta:
                    '$ref': '#/components/schemas/Pagination'
                data:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Artist'
            required: [meta, data]
            description: 'One page of artists, with the totals the request was counted against'
        AlbumPage:
            type: object
            properties:
                meta:
                    '$ref': '#/components/schemas/Pagination'
                data:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Album'
            required: [meta, data]
            description: 'One page of albums'
        TrackPage:
            type: object
            properties:
                meta:
                    '$ref': '#/components/schemas/Pagination'
                data:
                    type: array
                    items:
                        '$ref': '#/components/schemas/TrackRow'
                states:
                    '$ref': '#/components/schemas/TrackStateCounts'
            required: [meta, data, states]
            description: 'One page of tracks, with what the station has of each and of the whole set'
        EnrichmentExternalId:
            type: object
            properties:
                source:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'e.g. `musicbrainz`, `wikidata`'
                id:
                    type: string
                    minLength: 1
                    maxLength: 200
            required: [source, id]
        EnrichmentLink:
            type: object
            properties:
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                url:
                    type: string
                    minLength: 1
                    maxLength: 2000
            required: [label, url]
            description: "Narrowed to http(s) by the host before it is stored, since the console renders these as\nsomething a human clicks."
        TrackEnrichmentData:
            type: object
            properties:
                artist:
                    type: string
                    maxLength: 2000
                title:
                    type: string
                    maxLength: 2000
                album:
                    type: string
                    maxLength: 2000
                year:
                    type: integer
                releaseDate:
                    type: string
                    maxLength: 10
                genres:
                    type: array
                    items:
                        type: string
                        maxLength: 2000
                moods:
                    type: array
                    items:
                        type: string
                        maxLength: 2000
                biography:
                    type: string
                    maxLength: 20000
                facts:
                    type: array
                    items:
                        type: string
                        maxLength: 2000
                    description: 'Short lines, each independently speakable'
                bpm:
                    type: number
                    description: 'Not an integer: a tempo a source measured rather than declared is fractional'
                musicalKey:
                    type: string
                    maxLength: 2000
                label:
                    type: string
                    maxLength: 2000
                isrc:
                    type: string
                    maxLength: 2000
                artworkUrl:
                    type: string
                    maxLength: 2000
                    description: "The provider's picture as the station serves it: `art/<id>` once cached, else the station's proxy `art/source/<token>`. Never the URL the plugin supplied"
                externalIds:
                    type: array
                    items:
                        '$ref': '#/components/schemas/EnrichmentExternalId'
                links:
                    type: array
                    items:
                        '$ref': '#/components/schemas/EnrichmentLink'
                extra:
                    type: object
                    additionalProperties: {}
                    description: 'What the plugin said that the SDK has no field for. Per provider only: the merged view drops it. Never holds a URL: any string with one is dropped when read, along with the key or array element that held it'
            description: "`releaseDate` is a string and not `datetime` because it is a partial date: MusicBrainz answers\n`1997`, `1997-06` or `1997-06-24` depending on what is actually known about the release, and the\nSDK types it the same way. A `datetime` would reject the first two or invent a day and a time\nfor them, which is a precision the source never claimed."
        ArtistEnrichmentData:
            type: object
            properties:
                name:
                    type: string
                    maxLength: 2000
                biography:
                    type: string
                    maxLength: 20000
                imageUrl:
                    type: string
                    maxLength: 2000
                    description: "The provider's picture as the station serves it: `art/<id>` once cached, else the station's proxy `art/source/<token>`. Never the URL the plugin supplied"
                genres:
                    type: array
                    items:
                        type: string
                        maxLength: 2000
                facts:
                    type: array
                    items:
                        type: string
                        maxLength: 2000
                externalIds:
                    type: array
                    items:
                        '$ref': '#/components/schemas/EnrichmentExternalId'
                links:
                    type: array
                    items:
                        '$ref': '#/components/schemas/EnrichmentLink'
                extra:
                    type: object
                    additionalProperties: {}
        AlbumEnrichmentData:
            type: object
            properties:
                name:
                    type: string
                    maxLength: 2000
                artist:
                    type: string
                    maxLength: 2000
                    description: "The record's own credit, which is not always the track's"
                year:
                    type: integer
                releaseDate:
                    type: string
                    maxLength: 10
                    description: 'Partial, exactly as on TrackEnrichmentData'
                label:
                    type: string
                    maxLength: 2000
                genres:
                    type: array
                    items:
                        type: string
                        maxLength: 2000
                facts:
                    type: array
                    items:
                        type: string
                        maxLength: 2000
                artworkUrl:
                    type: string
                    maxLength: 2000
                    description: "The provider's picture as the station serves it: `art/<id>` once cached, else the station's proxy `art/source/<token>`. Never the URL the plugin supplied"
                externalIds:
                    type: array
                    items:
                        '$ref': '#/components/schemas/EnrichmentExternalId'
                links:
                    type: array
                    items:
                        '$ref': '#/components/schemas/EnrichmentLink'
                extra:
                    type: object
                    additionalProperties: {}
        TrackEnrichmentSource:
            type: object
            properties:
                provider:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                providerRef:
                    type: string
                    maxLength: 200
                    readOnly: true
                    description: 'The id it was fetched under. Provenance, not identity'
                fetchedAt:
                    type: string
                    format: date-time
                    readOnly: true
                expiresAt:
                    type: string
                    format: date-time
                    readOnly: true
                stale:
                    type: boolean
                    readOnly: true
                    description: 'Past its TTL, so the next pass will ask again'
                found:
                    type: boolean
                    readOnly: true
                failed:
                    type: boolean
                    readOnly: true
                    description: 'The last attempt errored, so `expiresAt` is a backoff rather than a TTL'
                data:
                    '$ref': '#/components/schemas/TrackEnrichmentData'
            required: [provider, fetchedAt, stale, found, failed, data]
            description: "One provider's stored answer. `found: false` is a recorded miss, which is a fact rather than a\nfailure: the provider was asked, had nothing, and is not asked again until `expiresAt`. A provider\nthat could not be asked at all is `failed` instead, and the two never both hold."
        ArtistEnrichmentSource:
            type: object
            properties:
                provider:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                providerRef:
                    type: string
                    maxLength: 200
                    readOnly: true
                fetchedAt:
                    type: string
                    format: date-time
                    readOnly: true
                expiresAt:
                    type: string
                    format: date-time
                    readOnly: true
                stale:
                    type: boolean
                    readOnly: true
                found:
                    type: boolean
                    readOnly: true
                failed:
                    type: boolean
                    readOnly: true
                    description: 'The last attempt errored, so `expiresAt` is a backoff rather than a TTL'
                data:
                    '$ref': '#/components/schemas/ArtistEnrichmentData'
            required: [provider, fetchedAt, stale, found, failed, data]
        AlbumEnrichmentSource:
            type: object
            properties:
                provider:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                providerRef:
                    type: string
                    maxLength: 200
                    readOnly: true
                fetchedAt:
                    type: string
                    format: date-time
                    readOnly: true
                expiresAt:
                    type: string
                    format: date-time
                    readOnly: true
                stale:
                    type: boolean
                    readOnly: true
                found:
                    type: boolean
                    readOnly: true
                failed:
                    type: boolean
                    readOnly: true
                    description: 'The last attempt errored, so `expiresAt` is a backoff rather than a TTL'
                data:
                    '$ref': '#/components/schemas/AlbumEnrichmentData'
            required: [provider, fetchedAt, stale, found, failed, data]
        FactClaim:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    readOnly: true
                claim:
                    type: string
                    minLength: 1
                    maxLength: 500
                    readOnly: true
                    description: 'One sentence, as the DJ would say it'
                category:
                    type: string
                    minLength: 1
                    maxLength: 40
                    readOnly: true
                source:
                    type: string
                    minLength: 1
                    maxLength: 20
                    readOnly: true
                    description: "`lead` for the article's own opening, `model` for what a model found"
                sourceProvider:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                sourceUrl:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    readOnly: true
                sourceQuote:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    readOnly: true
                confidence:
                    type: number
                    readOnly: true
                model:
                    type: string
                    maxLength: 200
                    readOnly: true
                lastUsedAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'Absent means never said on air'
            required: [id, claim, category, source, sourceProvider, sourceUrl, sourceQuote]
            description: "One thing the station believes, and the words it read that say so. Extracted by the host out of\nan article a plugin handed over, rather than said by any plugin: `sourceUrl` is where a person\nchecks it and `sourceQuote` is the span that supports it, and neither is ever absent."
        TrackEnrichmentDetail:
            type: object
            properties:
                trackId:
                    type: string
                    format: uuid
                    readOnly: true
                merged:
                    '$ref': '#/components/schemas/TrackEnrichmentData'
                sources:
                    type: array
                    items:
                        '$ref': '#/components/schemas/TrackEnrichmentSource'
                claims:
                    type: array
                    items:
                        '$ref': '#/components/schemas/FactClaim'
            required: [trackId, merged, sources, claims]
            description: "Every provider's answer, plus the same merge the promotion step used, so the console and the\ncanonical columns cannot tell different stories. `sources` is empty on a row the walk has not\nreached yet.\n\n`claims` sits beside them rather than inside `merged`, because a claim is the host's own and not\nany provider's. The articles they were read out of are deliberately NOT here: raw source prose is\nstored and never sent."
        ArtistEnrichmentDetail:
            type: object
            properties:
                artistId:
                    type: string
                    format: uuid
                    readOnly: true
                merged:
                    '$ref': '#/components/schemas/ArtistEnrichmentData'
                sources:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ArtistEnrichmentSource'
                claims:
                    type: array
                    items:
                        '$ref': '#/components/schemas/FactClaim'
            required: [artistId, merged, sources, claims]
        AlbumEnrichmentDetail:
            type: object
            properties:
                albumId:
                    type: string
                    format: uuid
                    readOnly: true
                merged:
                    '$ref': '#/components/schemas/AlbumEnrichmentData'
                sources:
                    type: array
                    items:
                        '$ref': '#/components/schemas/AlbumEnrichmentSource'
                claims:
                    type: array
                    items:
                        '$ref': '#/components/schemas/FactClaim'
            required: [albumId, merged, sources, claims]
        SuspendInput:
            type: object
            properties:
                days:
                    type: integer
                    minimum: 1
                    maximum: 365
                    description: 'How long, from now. Required, because a suspension with no end is a dislike, and that has its own control. Suspending again replaces the date'
            required: [days]
            description: 'Keep something off the station for a while, without passing judgement on it'
        SimilarityGraphQuery:
            type: object
            properties:
                around:
                    type: string
                    format: uuid
                    description: 'A catalog artist to centre on. Absent draws the whole store, best-ranked edges first'
                depth:
                    type: integer
                    minimum: 1
                    maximum: 2
                    default: 1
                    description: 'How many steps out from `around`, following edges either way. Ignored without it'
                library:
                    type: boolean
                    default: false
                    description: 'Only artists the catalog holds, on both ends of every edge'
                limit:
                    type: integer
                    minimum: 1
                    maximum: 2000
                    default: 500
                    description: 'The most edges answered'
            required: [depth, library, limit]
            description: 'Which part of the similarity store to draw.'
        SimilarityNode:
            type: object
            properties:
                key:
                    type: string
                    readOnly: true
                    description: "The artist's name as the station folds it for matching. Unique in one graph"
                name:
                    type: string
                    readOnly: true
                    description: "The catalog's spelling when the catalog holds the artist, else the source's"
                artistId:
                    type: string
                    format: uuid
                    readOnly: true
                    description: 'The catalog artist, when the catalog holds one. Absent for an artist only a source has named'
            required: [key, name]
            description: "One artist in the similarity graph. Keyed by its folded name rather than an id, because most of\nthe artists the sources name are not in the catalog at all."
        SimilarityEdge:
            type: object
            properties:
                from:
                    type: string
                    readOnly: true
                    description: 'The key of the artist whose neighbours these are'
                to:
                    type: string
                    readOnly: true
                    description: 'The key of the neighbour'
                rank:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: "Position in `from`'s merged answer, from 0. The one weight comparable across sources"
                match:
                    type: number
                    readOnly: true
                    description: "The source's own score, comparable only inside that source's answer. Absent when it gave none"
                source:
                    type: string
                    readOnly: true
                    description: 'The plugin id whose answer named this neighbour first'
            required: [from, to, rank, source]
            description: "One artist naming another as a neighbour. DIRECTED: that A lists B says nothing about whether B\nlists A, and both rows are answered when both exist."
        SimilarityGraph:
            type: object
            properties:
                nodes:
                    type: array
                    items:
                        '$ref': '#/components/schemas/SimilarityNode'
                    readOnly: true
                    description: 'Every artist an edge names, once'
                edges:
                    type: array
                    items:
                        '$ref': '#/components/schemas/SimilarityEdge'
                    readOnly: true
                truncated:
                    type: boolean
                    readOnly: true
                    description: 'More edges matched than `limit` allowed'
            required: [nodes, edges, truncated]
        StationChart:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: "Unique across the station: the plugin's own id for the chart, qualified with the plugin that offered it. Two services both calling something `top-100` stay distinct"
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                country:
                    type: string
                    maxLength: 10
                    description: 'ISO 3166-1 alpha-2, when the chart is national. Absent means global'
                genre:
                    type: string
                    maxLength: 200
                description:
                    type: string
                    maxLength: 2000
            required: [id, pluginId, name]
            description: 'A chart one installed plugin offers'
        StationChartList:
            type: object
            properties:
                charts:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationChart'
            required: [charts]
        ChartRecord:
            type: object
            properties:
                rank:
                    type: integer
                    minimum: 1
                title:
                    type: string
                    minLength: 1
                    maxLength: 400
                artist:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The lead artist alone. The other credits are in `featuring`'
                featuring:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                album:
                    type: string
                    maxLength: 400
                year:
                    type: integer
                    minimum: 0
                peak:
                    type: integer
                    minimum: 1
                    description: 'Best position this record has reached, where the source tracks it'
                weeksOn:
                    type: integer
                    minimum: 0
                    description: 'How many editions it has appeared in, where the source tracks it'
                lastWeek:
                    type: integer
                    minimum: 1
                    description: 'Its position in the edition before this one, where the source tracks it. Absent when the source does not publish it or the record was not on that edition'
            required: [rank, title, artist]
            description: "One record's place in a chart"
        ChartQuery:
            type: object
            properties:
                limit:
                    type: integer
                    minimum: 1
                    maximum: 100
                date:
                    type: string
                    maxLength: 10
                    description: 'Which edition, as `YYYY-MM-DD`. Absent means the current one, and a service that keeps no history answers with the current one either way'
        ChartPage:
            type: object
            properties:
                chartId:
                    type: string
                    minLength: 1
                    maxLength: 400
                records:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ChartRecord'
                    description: 'Ranked. Empty when the chart could not be read, which is deliberately not an error: a chart is something to look at, never something the station needs to air'
            required: [chartId, records]
        BreakKind:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                key:
                    type: string
                    minLength: 1
                    maxLength: 60
                    pattern: '^[a-z0-9]+(-[a-z0-9]+)*$'
                    description: 'The kind, as a band on the format clock names it: lowercase words joined by hyphens. Fixed once the kind is created, because every band and every break it ever planted carries it'
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What the console calls it. Never read out'
                brief:
                    type: string
                    minLength: 1
                    maxLength: 4000
                    description: "What this kind of break is for and when to say nothing, written as an instruction to the presenter. The station's own rules for every break still apply on top of it"
                rules:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                    maxItems: 20
                    description: 'Anything this kind owes beyond the rules every break owes, one per entry. Added to those rules, never in place of them'
                showsPrevious:
                    type: boolean
                    description: 'Whether the presenter is shown the record that has just finished'
                showsPlayed:
                    type: boolean
                    description: "Whether the presenter is shown the rest of this broadcast's records, to refer back to"
                showsFacts:
                    type: boolean
                    description: 'Whether the records shown carry the notes the station holds about them'
                showsNotebook:
                    type: boolean
                    description: 'Whether the presenter is shown their own notebook'
                enabled:
                    type: boolean
                    description: 'Whether the station writes this kind at all. A new or imported kind is off until you switch it on'
                position:
                    type: integer
                    minimum: 0
                    description: 'Your own order, for the list'
            required:
                - id
                - key
                - name
                - brief
                - rules
                - showsPrevious
                - showsPlayed
                - showsFacts
                - showsNotebook
                - enabled
                - position
            description: 'A kind of break you write yourself: a brief in prose, and what the presenter is shown while writing one'
        BreakKindList:
            type: object
            properties:
                kinds:
                    type: array
                    items:
                        '$ref': '#/components/schemas/BreakKind'
            required: [kinds]
        BreakKindFile:
            type: object
            properties:
                format:
                    type: string
                    minLength: 1
                    maxLength: 50
                    description: 'What shape this is, so a file from a later build says so rather than being read wrongly'
                takenAt:
                    type: string
                    minLength: 1
                    maxLength: 40
                    description: 'When it was exported, ISO-8601'
                station:
                    type: string
                    maxLength: 100
                    description: 'The station it was taken from. Provenance only'
                kinds:
                    type: array
                    items:
                        '$ref': '#/components/schemas/BreakKindFileKind'
                    maxItems: 200
            required: [format, takenAt, kinds]
            description: 'Kinds of break as a file, to move between stations. No id, no place in a list and no switch: a kind arrives switched off wherever it lands, so it is read back before it airs'
        BreakKindFileKind:
            type: object
            properties:
                key:
                    type: string
                    minLength: 1
                    maxLength: 60
                    pattern: '^[a-z0-9]+(-[a-z0-9]+)*$'
                    description: 'What identifies the kind across two stations, and what a band on the format clock names'
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                brief:
                    type: string
                    minLength: 1
                    maxLength: 4000
                rules:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                    maxItems: 20
                showsPrevious:
                    type: boolean
                showsPlayed:
                    type: boolean
                showsFacts:
                    type: boolean
                showsNotebook:
                    type: boolean
            required:
                - key
                - name
                - brief
                - rules
                - showsPrevious
                - showsPlayed
                - showsFacts
                - showsNotebook
            description: 'One kind of break in a file: everything that says what it is, and nothing about how this station has it set'
        BreakKindImportPlan:
            type: object
            properties:
                format:
                    type: string
                    minLength: 1
                    maxLength: 50
                    readOnly: true
                    description: 'What the file said it was'
                station:
                    type: string
                    maxLength: 100
                    readOnly: true
                    description: 'The station it was taken from, when it said'
                takenAt:
                    type: string
                    maxLength: 40
                    readOnly: true
                    description: 'When it was taken, when it said'
                notices:
                    type: array
                    items:
                        '$ref': '#/components/schemas/BreakKindImportNotice'
                    readOnly: true
                    description: 'About the file rather than any one kind in it'
                kinds:
                    type: array
                    items:
                        '$ref': '#/components/schemas/BreakKindImportEntry'
                    readOnly: true
            required: [format, notices, kinds]
            description: 'What importing a file WOULD do here, worked out by the same code the import runs and written nowhere'
        BreakKindImportEntry:
            type: object
            properties:
                key:
                    type: string
                    minLength: 1
                    maxLength: 60
                    readOnly: true
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                outcome:
                    type: string
                    enum: [create, update, skip, refuse]
                    readOnly: true
                    description: 'New here; already here and named in `replace`, so rewritten; already here and left alone; or a key this station uses for a break of its own, which no file can take'
                notices:
                    type: array
                    items:
                        '$ref': '#/components/schemas/BreakKindImportNotice'
                    readOnly: true
            required: [key, name, outcome, notices]
            description: 'One kind in a file, and what would become of it here'
        BreakKindImportNotice:
            type: object
            properties:
                kind:
                    type: string
                    enum: [format, duplicate, switched-off, refused]
                    readOnly: true
                    description: 'Which sort, so a console can group by it rather than parsing the sentence'
                message:
                    type: string
                    minLength: 1
                    maxLength: 500
                    readOnly: true
                    description: "The whole of it, in the station's own words"
            required: [kind, message]
            description: 'Something to know before pressing Import'
        BreakKindImportResult:
            type: object
            properties:
                plan:
                    '$ref': '#/components/schemas/BreakKindImportPlan'
                    readOnly: true
                created:
                    type: integer
                    minimum: 0
                    readOnly: true
                updated:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Kinds rewritten from the file, and switched off until read back'
                skipped:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Kinds this station already held and was not asked to replace, or could not take'
                kinds:
                    type: array
                    items:
                        '$ref': '#/components/schemas/BreakKind'
                    readOnly: true
                    description: 'The list as it now stands'
            required: [plan, created, updated, skipped, kinds]
            description: 'What importing did, with the plan it did it from. All or nothing'
        ClockBand:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                kind:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Which sort of break this slot wants, as `segments.kind` spells it. Free text: a station that wants sponsor spots writes `sponsor` and drops the recordings in'
                at:
                    type: string
                    enum: [clock, interval]
                    description: "`clock` is a time of day and `interval` is a spacing rule for a kind the station's own interval does not cover"
                hour:
                    type: integer
                    minimum: 0
                    maximum: 23
                    description: 'For a `clock` band: the hour it happens at. Absent means every hour, which is the common case'
                minute:
                    type: integer
                    minimum: 0
                    maximum: 59
                    description: 'For a `clock` band: minutes past the hour'
                days:
                    type: array
                    items:
                        type: integer
                        minimum: 0
                        maximum: 6
                    description: "For a `clock` band: the weekdays it happens on, Sunday 0, on the station's own clock. Absent or empty means every day"
                hard:
                    type: boolean
                    description: 'For a `clock` band: airs at its time exactly and never before it, waiting when the order comes up early and cutting the record in the way when it runs late. Absent or false is a soft marker, which airs at the first boundary after its time'
                everyMs:
                    type: integer
                    minimum: 60000
                    description: 'For an `interval` band: how far apart, in milliseconds'
                position:
                    type: integer
                    minimum: 0
                    description: "Where this sits in the operator's own order, which is what settles a boundary two rules both want"
                enabled:
                    type: boolean
                    description: 'A rule turned off without being lost'
                topicId:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'What this band is about, as a subject of its own kind: a news category, later a weather location. Absent means it covers whatever it finds'
                topicLabel:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                    description: "That subject's name, so a list can be drawn without a second call"
            required: [id, kind, at, position, enabled]
            description: "One rule on the station's format clock: a sort of break, and when it happens"
        ClockBandList:
            type: object
            properties:
                bands:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ClockBand'
                producibleKinds:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 100
                    description: 'Which sorts of break this station can actually make right now: one it can write and speak, one it has recordings of, or one it produces as an episode. A band naming anything else claims its boundary and then passes over it'
            required: [bands, producibleKinds]
        ClockPack:
            type: object
            properties:
                format:
                    const: deadair.clock
                    description: 'Says the file is a clock file'
                version:
                    type: integer
                    minimum: 1
                    description: "The version of the document's shape. This station reads version 1"
                name:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'What the file is, as whoever made it would describe it'
                bands:
                    type: array
                    items:
                        type: object
                        additionalProperties: {}
                    maxItems: 500
            required: [format, version, name, bands]
            description: "A format clock as one file, to hand to another station. Each entry is read as a `ClockPackRow` when it\nis imported, so one a station cannot use is reported rather than refusing the file"
        ClockImportResult:
            type: object
            properties:
                plan:
                    '$ref': '#/components/schemas/PackImportPlan'
                    readOnly: true
                list:
                    '$ref': '#/components/schemas/ClockBandList'
                    readOnly: true
            required: [plan, list]
            description: 'What an import did, and the clock as it now stands'
        TalkDirection:
            type: object
            properties:
                words:
                    type: string
                    minLength: 1
                    maxLength: 280
                    description: 'What the presenters are told, as the operator wrote it'
                endsAt:
                    type: string
                    format: date-time
                    description: 'When the presenters stop hearing it'
            required: [words, endsAt]
            description: "A line the operator gives the presenters for a while. Talk breaks, banter between co-hosts and the\nchangeover into a show hear it as a lean on what they talk about, never as a fact to state or a\nline to read out. Bulletins, the date, jingles and calls never hear it"
        TalkDirectionReading:
            type: object
            properties:
                direction:
                    '$ref': '#/components/schemas/TalkDirection'
                    description: 'Absent when nothing is directing the presenters, including once a direction has run out'
            description: 'The direction in force, or none'
        TalkDirectionInput:
            type: object
            properties:
                words:
                    type: string
                    minLength: 1
                    maxLength: 280
                    description: 'A lean for the presenters, such as "it''s Sam''s birthday tonight" or "we''re snowed in, keep it cosy"'
                hours:
                    type: integer
                    minimum: 1
                    maximum: 24
                    description: 'How long it lasts, from now'
            required: [words, hours]
            description: 'Direct the presenters for a number of hours'
        StationMode:
            type: string
            enum: [rotation, setlist, feature]
            description: 'What kind of programming the station is running, which decides the rules it runs under'
        AirMode:
            type: string
            enum: [audience, always]
            description: 'What the mount lease is renewed against: `audience` airs only while somebody is listening, `always` airs whenever there is a programme'
        StationAir:
            type: object
            properties:
                active:
                    type: boolean
                    description: 'False means the station was stood down. What it was playing is remembered so the console can still say what it was'
                airMode:
                    '$ref': '#/components/schemas/AirMode'
                    description: 'What puts the station on air. In `audience` mode a station that is active with a full running order is still silent while nobody is connected, which is the intended state and not a fault'
                name:
                    type: string
                    maxLength: 200
                    description: 'What is on. Absent before the station has ever been given anything to play'
                source:
                    type: string
                    maxLength: 50
                    description: 'Who built what is on: `import` or `director`'
                remaining:
                    type: integer
                    minimum: 0
                    description: 'Items left before the running order runs out and `onEnd` decides what happens'
                slotId:
                    type: string
                    maxLength: 100
                    description: 'Which slot of the schedule this broadcast belongs to. Absent means nothing scheduled it, which is every station with no schedule'
                airSource:
                    '$ref': '#/components/schemas/AirSource'
                    description: 'Who is driving the station right now'
                held:
                    type: boolean
                    description: 'Whether the schedule has been told to leave this broadcast alone. A takeover is otherwise replaced when the block it started inside ends'
                holdUntil:
                    type: string
                    minLength: 24
                    maxLength: 24
                    description: 'When that hold lapses, as an ISO-8601 instant. ABSENT WHILE `held` IS TRUE means until it is released by hand, which is a real state rather than a missing value — `Infinity` is not a thing JSON can carry, so the two facts are two fields'
                quietRecords:
                    type: integer
                    minimum: 1
                    maximum: 500
                    description: 'How many more records the station keeps its own breaks off the air for. Absent is not quiet. It counts down as each record starts, so it only runs while somebody can hear it, and ends by itself'
            required: [active, airMode, remaining, airSource, held]
            description: 'What the station is airing, and whether it is driving at all'
        QuietStationInput:
            type: object
            properties:
                records:
                    type: integer
                    minimum: 1
                    maximum: 500
                    description: "How many records, from the next one to start. The breaks already planned across them come out at once. Somebody else's programme is still carried, and a break somebody asks for is refused until the quiet ends"
            required: [records]
            description: "Keep the station's own breaks off the air for a while"
        AirSource:
            type: string
            enum: ['off', schedule, sustaining, operator]
            description: 'Who chose what is on air. `schedule` is a block the clock changed over to and `sustaining` is what it plays in the hours no block claims — both are the schedule driving. `operator` is a person, including one who took over inside a scheduled block, and it holds until the next block begins. `off` is a station stood down'
        HoldStationInput:
            type: object
            properties:
                minutes:
                    type: integer
                    minimum: 1
                    maximum: 1440
                    description: 'How long the hold lasts, from now. ABSENT means until it is released by hand, which is the answer for an operator who does not know yet — a day is the ceiling because a hold nobody remembers setting is worse than one that lapses'
            description: 'How long to keep the schedule off the running order'
        SetStationAirInput:
            type: object
            properties:
                airMode:
                    '$ref': '#/components/schemas/AirMode'
            required: [airMode]
            description: 'Change how the station decides to be on air'
        StationOnEnd:
            type: string
            enum: [extend, repeat, stop]
            description: 'What the station does when the running order runs out'
        StationItemState:
            type: string
            enum: [planned, handed, airing, played, skipped, unavailable, removed]
            description: 'Where an item of the running order has got to. `handed` is a promise and `airing` is a fact, which is the distinction everything here is built around. The three terminal states that are not `played` are three different facts on a page that has to say why the station is silent: `skipped` is the station passing over an item it reached, `removed` is an operator taking one out before its turn, and `unavailable` is a record the station could not obtain the audio for — the only one of the three an operator can act on, since it names a copy rather than a decision'
        StationOrderItem:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'What an edit names, what rides through the player, and what comes back on its readings'
                kind:
                    type: string
                    enum: [track, segment]
                    description: 'Whether this is a record or something the station says: an ident, a stinger, a talk break'
                state:
                    '$ref': '#/components/schemas/StationItemState'
                title:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: "The record's title, or the segment's label. What the mount is labelled with while it airs"
                artists:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                    description: 'Empty for a segment, which has no artist'
                durationMs:
                    type: integer
                    minimum: 0
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Absent on a segment: the station serves its own audio'
                externalId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'Absent on a segment'
                album:
                    type: string
                    maxLength: 400
                artworkUrl:
                    type: string
                    maxLength: 2000
                year:
                    type: integer
                    minimum: 0
                trackId:
                    type: string
                    maxLength: 100
                    description: 'The canonical catalog track, when this is one the catalog holds'
                artistId:
                    type: string
                    maxLength: 100
                    description: 'The canonical artist behind that track, so a console can reach their page from the running order. Absent on a segment, and on a record the catalog has never seen'
                albumId:
                    type: string
                    maxLength: 100
                    description: 'The release that track was ingested inside. Absent for the two reasons above and for a third: a single ingested outside any release has none'
                rating:
                    '$ref': '#/components/schemas/Rating'
                    description: 'What the station thinks of this record, read as the order is drawn rather than stored on it. Absent on a segment, and on a record the catalog has never seen'
                mixedIn:
                    type: boolean
                    description: 'The station chose this record to sound like the playlist around it, rather than the playlist naming it. Absent on everything the playlist named, and on a segment'
                followsRequest:
                    type: boolean
                    description: "The station chose this record to follow a listener's request, on a request show. Absent on everything else, and on a segment"
                segmentId:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Which segment this plays. Present only on a segment'
                segmentState:
                    type: string
                    enum: [planned, writing, written, rendering, ready, failed, gone]
                playable:
                    type: boolean
                    description: 'Whether the station can actually air this segment. One that cannot is SKIPPED when it comes round, rather than held open'
                segmentError:
                    type: string
                    maxLength: 2000
                    description: 'Why this segment will not air, in a sentence. Present only on a failed one'
                segmentWriter:
                    type: string
                    maxLength: 200
                    description: "What decided the words: the station's own templates, or the model that wrote them. Absent on a recording somebody made"
                scriptId:
                    type: string
                    format: uuid
                    description: 'The newest written attempt behind this segment, which is the words that air and the attempt a rating of this break lands on. Absent on a record, on a recording nobody wrote, and on a break not written yet'
                scriptRating:
                    '$ref': '#/components/schemas/ScriptRating'
                    description: 'What the operator thought of that attempt. Absent means nobody has said, which `neutral` does not, and a rewrite starts unrated'
                overAtMs:
                    type: integer
                    minimum: 0
                    description: 'Heard OVER the record that follows, this far into it, with the music ducked under it. Such an item is never handed to the player in its own right'
                overEndOf:
                    type: boolean
                    description: 'Present with `overAtMs` when the item is heard over the END of the record BEFORE it instead, that far into that record, ending as it ends. Absent for every other talk-over'
            required: [id, kind, state, title, artists]
            description: 'One item of the live running order, and where it has got to'
        StationOrder:
            type: object
            properties:
                name:
                    type: string
                    maxLength: 200
                    description: 'What is on, for a console to draw. A label for this broadcast rather than the name of a stored object'
                brief:
                    type: string
                    maxLength: 500
                    description: 'What the operator asked the station to play, in their own words. It keeps steering every refill until the station is put on air again, so a console should show it rather than only accept it'
                personaId:
                    type: string
                    maxLength: 100
                    description: 'Who is hosting this broadcast, when it named somebody. Absent means whichever persona the station has on air'
                personaLabel:
                    type: string
                    maxLength: 200
                    description: 'What that host is called, resolved as the order is read so a console need not fetch the persona list to draw a name'
                coHostPersonaIds:
                    type: array
                    items:
                        type: string
                        maxLength: 100
                    maxItems: 3
                    description: 'Who presents beside the host on this broadcast, in order: the co-hosts the schedule put on for tonight. Absent is one voice'
                mode:
                    '$ref': '#/components/schemas/StationMode'
                onEnd:
                    '$ref': '#/components/schemas/StationOnEnd'
                source:
                    type: string
                    minLength: 1
                    maxLength: 50
                    description: 'Who built it: `import`, `chart` or `director`'
                sourcePluginId:
                    type: string
                    maxLength: 200
                    description: 'Where more material is pulled from, when it came from a playlist'
                sourcePlaylistId:
                    type: string
                    maxLength: 400
                    description: 'The playlist it was built from. With no `sourcePluginId`, a playlist the station owns'
                sourceChartId:
                    type: string
                    maxLength: 400
                    description: 'The published chart this broadcast was built from, qualified with the plugin that offered it. Provenance rather than a binding: a chart is a fixed document, so it is read once and never topped up from'
                requestShow:
                    type: boolean
                    description: 'Whether this is a request show, on which each listener request is followed by records like it. Absent is an ordinary show'
                requestFollowOn:
                    type: integer
                    minimum: 0
                    maximum: 10
                    description: 'How many records follow each request on a request show. Present only on one'
                items:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationOrderItem'
            required: [name, mode, onEnd, source, items]
            description: "The station's live running order: what is airing, item by item"
        PutOnAirInput:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The plugin whose playlist to build from. Absent starts empty and lets the station generate its own programming'
                playlistId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'Required alongside `pluginId`. The playlist is READ at this moment rather than copied, so it is never edited by having been aired'
                chartId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'A published chart to build from instead, as `pluginId:chartId`. An ALTERNATIVE to `pluginId` and `playlistId` rather than a companion: a chart names records where a playlist names copies, so its entries are looked up and ingested before they can air, and a station with `rotation.discover` off can play almost none of one'
                chartOrder:
                    type: string
                    enum: [countdown, ranked, unordered]
                    description: "Which way round to play it. `countdown` opens on the lowest rank and ends on number one, which is the shape a chart show has; `ranked` walks the published document from the top; `unordered` leaves the sequence to the station's own artist spacing. Absent is `countdown`. Ignored without `chartId`"
                chartPositions:
                    type: boolean
                    description: 'Whether the host says where the chart placed each record it named: "number seven on the Hot 100". Absent is yes. Set it false to air a chart without its positions read out. A record no chart named has no position to say whatever this says'
                beds:
                    type: boolean
                    description: 'Whether the breaks the station writes during this broadcast air over a music bed from the library: one scoped to the slot or host on air, or else one scoped to nobody. Absent is yes, wherever the library holds a bed for it. False keeps every break dry'
                concerts:
                    type: boolean
                    description: "Whether the host may mention an artist's next show near the station, when the record either side of a break is theirs and a concert plugin knows of one. Absent is no"
                festivalId:
                    type: string
                    format: uuid
                    description: 'The festival this broadcast is built around, from `GET /festivals`. It plays the acts on the bill and its host may talk about the festival, from what the station holds about it, until its last day. Absent is no festival'
                albumId:
                    type: string
                    format: uuid
                    description: 'An album the library holds, to play in the order it was made: by disc, then by track, with any record nobody numbered after the rest. An ALTERNATIVE to every source above, and like a station playlist its records air from whichever provider serves a copy. Pair it with `mode: feature` to play it whole, with no breaks and no blends'
                routeFrom:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Start a route at this artist and travel to `routeTo` through artists the library holds, one record each, every step a record two of them share or a similarity source naming them alike. Send both or neither, and nothing else that names a source. Preview it first with `/director/route/preview`, which also makes this quicker'
                routeTo:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Where a route ends. See `routeFrom`'
                stationPlaylistId:
                    type: string
                    format: uuid
                    description: "A playlist the station owns to build from instead. An ALTERNATIVE to `pluginId` and `playlistId`, and to `chartId`: its records are the library's own, so each airs from whichever provider serves a copy, and a row the library does not hold yet is left out"
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What to call this broadcast. Absent names it after the chart, or after the plugin, since only the surface that listed the source knows its own name for it'
                brief:
                    type: string
                    maxLength: 500
                    description: 'What the station should play, in your own words: "heavy metal hits". It steers every refill for as long as this broadcast runs, not just the first batch, and it needs a model to programme with. Absent programmes the station the way its own rules do'
                personaId:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Who is hosting this broadcast. It rides the running order for as long as the broadcast does, so the presenter cannot drift back mid-show. Absent uses whichever persona the station has on air'
                eraFrom:
                    type: integer
                    minimum: 1900
                    maximum: 2100
                    description: 'The earliest release year this broadcast plays. Absent means no lower bound, and a record whose year the catalog does not know is played whatever the period'
                eraTo:
                    type: integer
                    minimum: 1900
                    maximum: 2100
                    description: 'The latest release year, on the same terms. Set with `eraFrom` for a decade; either may stand alone'
                moods:
                    type: array
                    items:
                        type: string
                        enum: [love, happiness, comfort, sadness, loneliness, anger, fear]
                    maxItems: 4
                    description: 'The moods this broadcast leans into, as stages in order across the schedule slot it fills. Off the schedule, only the first is used. Records a model has judged to be in the mood are a little more likely to be picked; nothing is ever kept off the air for it. Absent or empty is no lean'
                avoidMoods:
                    type: array
                    items:
                        type: string
                        enum: [love, happiness, comfort, sadness, loneliness, anger, fear]
                    maxItems: 6
                    description: 'The moods this broadcast steers away from, for the whole of it. Records a model has judged to be in one are less likely to be picked, half as likely; nothing is ever kept off the air for it. Absent or empty avoids nothing'
                breaks:
                    type: boolean
                    description: "Whether the host talks between the records. Absent is the mode's own answer: a `rotation` talks and a `setlist` does not. Set it true on a `setlist` for a countdown with a host, which talks as often as the station does while the records play exactly as the setlist has them. A `feature` stays silent whatever this says"
                callins:
                    type: boolean
                    description: 'Whether somebody phones in during this broadcast. A call is a short programme rather than a break: a few turns in a few voices, entering the running order as one block, spaced by `rotation.callinEveryMinutes`. Absent is no calls: there is no station-wide default behind it'
                mixInSimilar:
                    type: boolean
                    description: "Whether records that sound like the ones on this playlist are mixed in among them, one every `rotation.mixInEvery` records, found through the similarity plugin. The playlist still plays in full and in its own order around them. Absent takes the station's own setting, which is off. A setlist and a feature never have anything mixed in"
                requestShow:
                    type: boolean
                    description: "Whether this is a request show: the station plays as it otherwise would until a listener's request is placed, then replaces what was planned behind the request with records that sound like it, found through the similarity plugin. A second request waits for the first one's records to play out. Absent is no: there is no station-wide default behind it. A `setlist` or a `feature` never has a request followed, since that would throw its own sequence away"
                requestFollowOn:
                    type: integer
                    minimum: 0
                    maximum: 10
                    description: 'How many records follow each request on a request show. Absent is 4. Ignored unless `requestShow` is true'
                requestCooldownMinutes:
                    type: integer
                    minimum: 0
                    maximum: 1440
                    description: "Minutes one listener waits between requests during this broadcast, in place of the station's `requests.cooldownMinutes`. Absent keeps the station's. A party night wants it short"
                requestMaxOpen:
                    type: integer
                    minimum: 1
                    maximum: 20
                    description: "How many requests may be waiting at once during this broadcast, in place of the station's `requests.maxOpen`. Absent keeps the station's"
                repeatWindowDays:
                    type: integer
                    minimum: 0
                    maximum: 365
                    description: "Days a record rests after airing before this broadcast may play it again, in place of the station's `rotation.repeatWindowDays`. 0 lifts the window. Absent keeps the mode's own answer: the station's for a `rotation`, none for a `setlist` or a `feature`. A lift never reaches a dislike or a never-play rule"
                artistCooldownMinutes:
                    type: integer
                    minimum: 0
                    maximum: 1440
                    description: "Minutes an artist rests after airing during this broadcast, in place of the station's `rotation.artistCooldownMinutes`. 0 lifts the cooldown, which is what an hour of one artist needs first. Absent keeps the mode's own answer, on `repeatWindowDays`' terms"
                maxPerArtist:
                    type: integer
                    minimum: 0
                    maximum: 100
                    description: "Most records by one artist in each batch the station programmes for this broadcast, in place of the station's `rotation.maxPerArtist`. 0 lifts the cap. Absent keeps the mode's own answer, on `repeatWindowDays`' terms"
                writerOrder:
                    type: string
                    enum: [model, station]
                    description: "Which writer is asked first for this broadcast's breaks, in place of the station's `llm.breakWriterOrder`: `model`, with the station's own words underneath, or `station`, the phrasings, headlines and stories as written with the model underneath. Absent keeps the station's setting. Changes nothing while the model is switched off"
                mode:
                    '$ref': '#/components/schemas/StationMode'
                onEnd:
                    '$ref': '#/components/schemas/StationOnEnd'
            description: 'Put the station on air, building its running order from the top'
        SetStationHostInput:
            type: object
            properties:
                personaId:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Who hosts it from here on. Absent hands it back to whichever persona the station has on air, which is what a broadcast that never named one already does'
            description: 'Change who is presenting the broadcast that is on air'
        AddStationSegmentInput:
            type: object
            properties:
                segmentId:
                    type: string
                    minLength: 1
                    maxLength: 100
                atIndex:
                    type: integer
                    minimum: 0
                    description: 'Where to put it. Absent puts it at the end. A position already handed to the player is refused'
                overAtMs:
                    type: integer
                    minimum: 0
                    maximum: 600000
                    description: 'Play it OVER the record that follows, this far into it, rather than in the gap before it. Absent plays it between two records, which is the simpler path'
            required: [segmentId]
            description: 'Put something the station says into the running order'
        AddStationTrackInput:
            type: object
            properties:
                trackId:
                    type: string
                    format: uuid
                atIndex:
                    type: integer
                    minimum: 0
                    description: 'Where to put it. Absent puts it at the end. A position already handed to the player is refused'
            required: [trackId]
            description: 'Put a catalog record into the running order. Refused at the door — 404 for a record the catalog does not hold, 422 for one whose audio is not local yet — rather than accepted and left to fail when it comes round'
        MoveStationItemInput:
            type: object
            properties:
                toIndex:
                    type: integer
                    minimum: 0
            required: [toIndex]
            description: 'Move an item within the running order'
        ExtendStationInput:
            type: object
            properties:
                count:
                    type: integer
                    minimum: 1
                    maximum: 100
            description: 'Add tracks to the running order now, rather than waiting for it to run short'
        ReplanStationInput:
            type: object
            properties:
                count:
                    type: integer
                    minimum: 1
                    maximum: 100
                    description: 'How many records to programme. Absent is roughly an hour'
                brief:
                    type: string
                    maxLength: 500
                    description: "What the station should play from here on, in your own words. Absent keeps whatever this broadcast was already asked for; an empty string CLEARS it, which hands the programming back to the station's ordinary rotation. It steers every later refill too, not just this one batch"
            description: 'Throw away everything the player is not already holding and programme it again. Unlike a shuffle, the records themselves change; unlike putting the station on air, the broadcast continues'
        RequestableBreakKind:
            type: string
            enum: [news, weather, almanac, talkbreak, story, jingle]
            description: 'A kind of break an operator can ask for by name. Only the kinds that need nothing but a moment to be written: a welcome, a changeover or a dedication is ABOUT something that happened, and the station asks for those itself'
        BreakUrgency:
            type: string
            enum: [interrupt, next, soon, whenever]
            description: 'How soon a requested break wants to be heard. `interrupt` and `next` are written and spoken before they take a place in the running order, so they cannot reach their slot unready; `interrupt` lands at the first boundary that leaves time to write and speak it, `next` between the record on air and the one after. `soon` and `whenever` are planted like a break the station planned for itself, within a few records or at the next ordinary slot'
        RequestStationBreakInput:
            type: object
            properties:
                kind:
                    '$ref': '#/components/schemas/RequestableBreakKind'
                urgency:
                    '$ref': '#/components/schemas/BreakUrgency'
                    default: next
                topic:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: "What it is about, as a format clock band names it: a news category's key for a bulletin, a place's key for a forecast. A key that matches nothing is passed over when the break is written rather than read out under the wrong name"
            required: [kind, urgency]
            description: 'Ask the station to say something. The station decides where it goes, and may decline'
        StationBreakRequest:
            type: object
            properties:
                accepted:
                    type: boolean
                    description: 'False is an ordinary answer rather than a failure: breaks are off, there is no voice, nothing on this station writes that kind, the same request was taken moments ago, or the running order has no room'
                requestId:
                    type: string
                    description: 'The request as it was written down. Present whenever accepted'
                segmentId:
                    type: string
                    description: 'The break it became. Present whenever accepted. Accepted is not aired: a bulletin with no story left unread is still passed over when it is written'
                atIndex:
                    type: integer
                    minimum: 0
                    description: 'Where it went in the running order. Absent for `interrupt` and `next`, which take a place only once their audio exists'
                reason:
                    type: string
                    description: "Why it was declined, in the station's own words"
            required: [accepted]
            description: 'What the station made of a request to say something'
        RoutePreviewInput:
            type: object
            properties:
                from:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The artist to start at. The library has to hold a record by them'
                to:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The artist to end at. The library has to hold a record by them'
            required: [from, to]
            description: 'Where a route starts and where it ends, as artist names'
        RouteStop:
            type: object
            properties:
                artist:
                    type: string
                    maxLength: 200
                link:
                    type: string
                    enum: [credit, similar]
                    description: 'How this stop connects to the one before: a record the two are credited on together, or a similarity source naming them alike. Absent on the first stop'
                sharedTitle:
                    type: string
                    maxLength: 500
                    description: 'For a shared credit, the record they share'
                sharedLead:
                    type: string
                    maxLength: 200
                    description: "For a shared credit, that record's lead artist"
                source:
                    type: string
                    maxLength: 200
                    description: 'For a similarity link, the plugin whose answer it was, by id'
                sourceName:
                    type: string
                    maxLength: 200
                    description: 'The same plugin by the name it gives itself, when the station still has it'
            required: [artist]
            description: 'One artist on a route, and how it connects to the one before'
        ArtistRoute:
            type: object
            properties:
                found:
                    type: boolean
                    description: "False when either end is not an artist the library holds a record by, or no route turned up within the search's bounds"
                stops:
                    type: array
                    items:
                        '$ref': '#/components/schemas/RouteStop'
                    description: 'In order, the first artist first. Empty when nothing was found'
                factual:
                    type: integer
                    minimum: 0
                    description: 'How many hops rest on a record the two artists share'
                similar:
                    type: integer
                    minimum: 0
                    description: "How many hops rest on a similarity source's opinion"
            required: [found, stops, factual, similar]
            description: 'A route between two artists, or the news that there is none'
        BlockRule:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    readOnly: true
                field:
                    type: string
                    enum: [genre, tag, version]
                    description: '`genre` refuses any record tagged with this genre or a kind of it (`Punk Rock` under `Punk`, never `Pop` under `Pop Punk`, never `Trap` under `Rap`). `tag` refuses a record carrying exactly this tag. `version` refuses a version of a record, read from the markers on its title and album: `live` refuses a live recording ("War Pigs - Live", anything from "Live in Nottingham"), and never a title that merely says the word ("Live Wire")'
                value:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The genre or tag, as you would write it. For a `version` rule, the version: `live` is the only one'
                seasonFrom:
                    type: string
                    minLength: 5
                    maxLength: 5
                    description: 'First day it holds, as `MM-DD`. With `seasonTo`; a season starting after it ends wraps the year end'
                seasonTo:
                    type: string
                    minLength: 5
                    maxLength: 5
                    description: 'Last day it holds, as `MM-DD`'
                fromHour:
                    type: integer
                    minimum: 0
                    maximum: 23
                    description: "First hour of the station's day it holds. With `untilHour`; a window starting after it ends wraps midnight"
                untilHour:
                    type: integer
                    minimum: 0
                    maximum: 24
                    description: 'The hour it stops holding, exclusive'
                modes:
                    type: array
                    items:
                        type: string
                        enum: [rotation, setlist, feature]
                    description: 'Only while the station is in one of these modes. Absent or empty means every mode'
                slotIds:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 100
                    description: 'Only during these schedule blocks. Absent or empty means whatever is on'
                endsAt:
                    type: string
                    format: date-time
                    description: 'When it stops holding. Absent means until it is removed'
                inForce:
                    type: boolean
                    readOnly: true
                    description: "Whether it holds right now, on the station's clock, for what is on air"
            required: [id, field, value, inForce]
            description: "A never-play rule: a KIND of record the station must not play. Absolute, like a dislike, and\nexclude-only: there is no \"only these\" rule, because one could leave the station nothing to play.\nEvery scope is optional and an absent one means \"always\""
        BlockRuleList:
            type: object
            properties:
                rules:
                    type: array
                    items:
                        '$ref': '#/components/schemas/BlockRule'
            required: [rules]
            description: 'Every rule on the station, newest first'
        GenreSteer:
            type: object
            properties:
                genres:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 100
                    minItems: 1
                    maxItems: 20
                    description: 'What to favour, as genres. A record tagged with any of them, or a kind of one, is preferred'
                endsAt:
                    type: string
                    format: date-time
                    description: 'When the station goes back to choosing as it ordinarily does'
            required: [genres, endsAt]
            description: "A lean toward some genres for a while. The opposite of a rule: the station favours them when it\nchooses records, and still plays anything else rather than run dry"
        GenreSteerReading:
            type: object
            properties:
                steer:
                    '$ref': '#/components/schemas/GenreSteer'
                    description: 'Absent when nothing is leaning the station, including once one has run out'
            description: 'The lean in force, or none'
        GenreSteerInput:
            type: object
            properties:
                genres:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 100
                    minItems: 1
                    maxItems: 20
                hours:
                    type: integer
                    minimum: 1
                    maximum: 24
                    description: 'How long it lasts, from now'
            required: [genres, hours]
            description: 'Lean the station toward some genres for a number of hours'
        EventDestination:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    readOnly: true
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What the operator calls it'
                url:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: "Where events are POSTed. http or https, and allowed to be on the station's own network. A redirect is never followed"
                enabled:
                    type: boolean
                    description: 'Off sends nothing'
                events:
                    type: array
                    items:
                        type: string
                        maxLength: 100
                    description: 'The event types it is sent, from `/events/types`. Empty means every type, including any added later'
                consecutiveFailures:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Deliveries in a row that did not arrive. Any delivery that arrives sets it back to nothing; at twenty the station turns the destination off'
                disabledReason:
                    type: string
                    enum: [failing]
                    readOnly: true
                    description: 'Set when the station turned it off itself, because it kept failing. Turning it back on clears this and the count'
                lastDeliveredAt:
                    type: string
                    format: date-time
                    readOnly: true
                lastFailedAt:
                    type: string
                    format: date-time
                    readOnly: true
                lastFailure:
                    type: string
                    maxLength: 1000
                    readOnly: true
                    description: "What went wrong last time, in the station's words"
                createdAt:
                    type: string
                    format: date-time
                    readOnly: true
                updatedAt:
                    type: string
                    format: date-time
                    readOnly: true
            required: [id, name, url, enabled, events, consecutiveFailures, createdAt, updatedAt]
            description: "Somewhere the station sends what happens on it: an operator's own server, sent a signed POST per event"
        EventDestinationList:
            type: object
            properties:
                destinations:
                    type: array
                    items:
                        '$ref': '#/components/schemas/EventDestination'
            required: [destinations]
            description: 'Every event destination, oldest first'
        EventDestinationCreate:
            type: object
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                url:
                    type: string
                    minLength: 1
                    maxLength: 2000
                enabled:
                    type: boolean
                    description: 'Defaults to on'
                events:
                    type: array
                    items:
                        type: string
                        maxLength: 100
                    description: 'The event types to send it. Absent or empty means every type'
            required: [name, url]
            description: 'A new event destination'
        EventDestinationUpdate:
            type: object
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                url:
                    type: string
                    minLength: 1
                    maxLength: 2000
                enabled:
                    type: boolean
                    description: 'Turning a destination back on also clears why the station turned it off, and its count of failures'
                events:
                    type: array
                    items:
                        type: string
                        maxLength: 100
                    description: 'Empty means every type'
            description: 'Changes to an event destination. Only what is sent changes'
        EventDestinationSecret:
            type: object
            properties:
                secret:
                    type: string
                    description: 'Put this in the receiver. Each delivery carries `Deadair-Webhook-Signature: v1=<hex HMAC-SHA256 of "<Deadair-Webhook-Timestamp>.<body>">`'
            required: [secret]
            description: 'The secret deliveries to a destination are signed with. Shown only when it is made, so keep it'
        EventDestinationCreated:
            allOf:
                - '$ref': '#/components/schemas/EventDestination'
                - '$ref': '#/components/schemas/EventDestinationSecret'
            description: 'A destination just made, with its secret'
        EventDelivery:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                eventId:
                    type: string
                    format: uuid
                    description: "The event's own id, which every attempt at it shares"
                eventType:
                    type: string
                    maxLength: 100
                attempt:
                    type: integer
                    minimum: 1
                outcome:
                    type: string
                    enum: [delivered, failed, dropped]
                    description: '`dropped` is an event no longer worth sending, such as a record that finished playing while its destination was down'
                httpStatus:
                    type: integer
                    description: 'What the destination answered, when it answered at all'
                durationMs:
                    type: integer
                    minimum: 0
                error:
                    type: string
                    maxLength: 1000
                    description: "What went wrong, in the station's words. Never the destination's response body"
                createdAt:
                    type: string
                    format: date-time
            required: [id, eventId, eventType, attempt, outcome, durationMs, createdAt]
            description: 'One attempt at sending an event to a destination'
        EventDeliveryList:
            type: object
            properties:
                deliveries:
                    type: array
                    items:
                        '$ref': '#/components/schemas/EventDelivery'
            required: [deliveries]
            description: "A destination's latest delivery attempts, newest first. The station keeps the latest fifty"
        EventTestResult:
            type: object
            properties:
                delivered:
                    type: boolean
                httpStatus:
                    type: integer
                    description: 'What the destination answered, when it answered at all'
                durationMs:
                    type: integer
                    minimum: 0
                error:
                    type: string
                    maxLength: 1000
                    description: "Why it was not delivered, in the station's words"
            required: [delivered, durationMs]
            description: 'What a test delivery came to'
        EventStation:
            type: object
            properties:
                key:
                    type: string
                name:
                    type: string
            required: [key, name]
            description: 'Which station sent an event'
        EventEnvelope:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    description: "The event's own id. A redelivery of the same event carries the same one"
                type:
                    type: string
                    maxLength: 100
                    description: 'What happened, such as `track.started`'
                occurredAt:
                    type: string
                    description: 'When, as an ISO-8601 instant in UTC'
                station:
                    '$ref': '#/components/schemas/EventStation'
                data:
                    type: object
                    additionalProperties: {}
                    description: 'What the type says it holds. `/events/types` gives an example of each'
            required: [id, type, occurredAt, station, data]
            description: 'One event, as a destination receives it. The same shape for every type: read `type`, then `data`'
        EventType:
            type: object
            properties:
                type:
                    type: string
                    maxLength: 100
                description:
                    type: string
                    description: 'When it is sent, and what its `data` holds'
                subscribable:
                    type: boolean
                    description: 'False for the test event, which only a test delivery sends'
                example:
                    '$ref': '#/components/schemas/EventEnvelope'
            required: [type, description, subscribable, example]
            description: 'One kind of event the station sends'
        EventTypeList:
            type: object
            properties:
                types:
                    type: array
                    items:
                        '$ref': '#/components/schemas/EventType'
            required: [types]
            description: 'Every kind of event the station sends'
        HistoryEntry:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Unique across the history, and half of the cursor below'
                airedAt:
                    type: string
                    format: date-time
                    description: 'When it started, written when it began rather than when it was handed to the player'
                title:
                    type: string
                    minLength: 1
                    maxLength: 500
                artists:
                    type: string
                    minLength: 1
                    maxLength: 1000
                    description: 'The credit as written, whole: one line rather than a list, because that is the shape a release credits itself in and splitting it renames acts with a comma in their name'
                album:
                    type: string
                    maxLength: 500
                    description: 'Absent for anything aired straight from a provider, which the catalog holds no record for'
                artworkUrl:
                    type: string
                    maxLength: 2000
                    description: "The station's own copy where it has one, as a path under the API root, and the upstream URL until then. Resolve it against the base the station is reached at"
                durationMs:
                    type: integer
                    minimum: 0
                    description: 'How long the recording runs, from the catalog rather than from the copy that played'
                trackId:
                    type: string
                    maxLength: 100
                    description: 'The catalog track this was, for a client that wants to ask more about it. Absent for a record the catalog does not hold, and for one it has since forgotten'
            required: [id, airedAt, title, artists]
            description: 'One record the station actually played'
        HistoryQuery:
            type: object
            properties:
                limit:
                    type: integer
                    minimum: 1
                    maximum: 200
                before:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Where the previous page ended. Opaque, and a keyset rather than an offset because rows arrive at the head continuously: an offset would re-show a row on every page as the station kept playing under it. Pass back whatever `nextBefore` said and nothing else'
            description: 'One page of the history, newest first'
        HistoryPage:
            type: object
            properties:
                entries:
                    type: array
                    items:
                        '$ref': '#/components/schemas/HistoryEntry'
                nextBefore:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The cursor for the page after this one, absent once the history has been read to its end'
            required: [entries]
        AsRunKind:
            type: string
            enum: [record, break, programme, gap, onAir, offAir]
            description: "What one line of the as-run log is.\n\n  record, break, programme   something that went out, with when it started and, once the station saw it end, when it ended\n  gap                        the station aired its local bed instead of the running order. Only gaps long enough to matter are recorded\n  onAir, offAir              the station was put on air, or stood down"
        AsRunEntry:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Unique across the log, and half of the cursor below'
                kind:
                    '$ref': '#/components/schemas/AsRunKind'
                at:
                    type: string
                    format: date-time
                    description: 'When it started. For an item, the moment the player said so, not when it was handed over'
                endedAt:
                    type: string
                    format: date-time
                    description: 'When it stopped. Absent while an item is on air, and for one the station never saw end, such as the last item before a crash'
                title:
                    type: string
                    maxLength: 500
                    description: "A record's title or a break's label, as it went out"
                artists:
                    type: string
                    maxLength: 1000
                    description: "A record's credit as written, whole"
                trackId:
                    type: string
                    maxLength: 100
                    description: 'The catalog track a record was'
                segmentId:
                    type: string
                    maxLength: 100
                    description: 'The segment a break or a programme was'
                passedOver:
                    type: integer
                    minimum: 0
                    description: 'How many items already handed to the player it moved past to reach this one. They never aired. Absent when none'
                detail:
                    type: string
                    maxLength: 2000
                    description: "For a gap or an air change, the station's own sentence about it"
                pickedBecause:
                    type: string
                    maxLength: 200
                    description: 'For a record the model picked while asked to say why, its reason in its own words'
            required: [id, kind, at]
            description: 'One line of what actually went out'
        AsRunQuery:
            type: object
            properties:
                limit:
                    type: integer
                    minimum: 1
                    maximum: 500
                before:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Where the previous page ended. Opaque: pass back whatever `nextBefore` said'
                until:
                    type: string
                    format: date-time
                    description: 'Start reading from this moment back, to jump to an hour without paging to it. Ignored when `before` is sent'
            description: 'One page of the as-run log, newest first'
        AsRunPage:
            type: object
            properties:
                entries:
                    type: array
                    items:
                        '$ref': '#/components/schemas/AsRunEntry'
                nextBefore:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The cursor for the page after this one, absent once the log has been read to its end'
            required: [entries]
        ConsoleLanguagePack:
            type: object
            properties:
                format:
                    const: deadair.console-language
                    description: 'Says the file is a console language pack'
                version:
                    type: integer
                    minimum: 1
                    description: "The version of the document's shape. This station reads version 1"
                locale:
                    type: string
                    minLength: 2
                    maxLength: 35
                    description: 'The language, as a BCP 47 tag such as `de` or `pt-BR`. Never English, which is built into the console'
                name:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: "The language's name in itself, as the console's picker shows it: `Deutsch`, not `German`"
                direction:
                    type: string
                    enum: [ltr, rtl]
                    description: 'Which way its text runs'
                madeFor:
                    type: string
                    maxLength: 50
                    description: 'The console version the pack was translated against. Empty when the file did not say'
                catalog:
                    type: object
                    additionalProperties: {}
                    description: "The strings, nested by namespace and then by key, in the English catalog's shape. Every value is text or a further level of nesting"
            required: [format, version, locale, name, direction, madeFor, catalog]
            description: "A language pack: every word the console says, in one language, as the file a translator made. The same document is exported, imported and stored. The console's language only; what the station broadcasts in is the `stream.language` setting"
        ConsoleLanguage:
            type: object
            properties:
                locale:
                    type: string
                    minLength: 2
                    maxLength: 35
                name:
                    type: string
                    minLength: 1
                    maxLength: 100
                direction:
                    type: string
                    enum: [ltr, rtl]
                madeFor:
                    type: string
                    maxLength: 50
                importedAt:
                    type: string
                    format: date-time
                    description: 'When the pack now installed for it was imported'
            required: [locale, name, direction, madeFor, importedAt]
            description: 'A language the console can be shown in on this station, without its strings'
        ConsoleLanguageList:
            type: object
            properties:
                languages:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ConsoleLanguage'
                    description: 'In order of their tags. English is built in and is never listed'
            required: [languages]
        ConsoleLanguageChoice:
            type: object
            properties:
                locale:
                    type: string
                    minLength: 2
                    maxLength: 35
                    description: 'A language this station holds a pack for, or `en` for English whatever the browser prefers'
            description: "The language the signed-in operator chose for the console. Absent means none was chosen, and the console follows the browser's own preference among the languages it has"
        MessagingLinkCode:
            type: object
            properties:
                code:
                    type: string
                    minLength: 6
                    maxLength: 16
                    description: 'The code itself. Case does not matter when it is sent'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When the code stops working. A new code replaces any earlier one'
            required: [code, expiresAt]
            description: "A one-time code that links a chat account to the signed-in station account. Shown once: send it to the station's bot as `/link CODE` in a direct message"
        MessagingLink:
            type: object
            properties:
                pluginId:
                    type: string
                    maxLength: 200
                    description: 'Which messaging plugin the chat account is on, for example `deadair.telegram`'
                platformUserId:
                    type: string
                    maxLength: 200
                    description: "The chat platform's own id for the person"
                displayName:
                    type: string
                    maxLength: 200
                    description: 'What the chat platform called them when they linked'
                createdAt:
                    type: string
                    format: date-time
                    description: 'When the link was made'
            required: [pluginId, platformUserId, displayName, createdAt]
            description: "A chat account linked to the signed-in station account. Operator commands sent from it run with this account's permissions"
        MessagingLinkList:
            type: object
            properties:
                links:
                    type: array
                    items:
                        '$ref': '#/components/schemas/MessagingLink'
            required: [links]
            description: 'Every chat account linked to the signed-in station account, newest first'
        MetricResolution:
            type: string
            enum: [minute, hour]
            description: 'How wide one point is. Chosen by the station from the range asked for: minutes for two days or less, hours beyond'
        MetricSeriesQuery:
            type: object
            properties:
                names:
                    type: string
                    minLength: 1
                    maxLength: 1000
                    description: 'Comma-separated metric names, at most twenty: `station.listeners,work.job.ms`'
                from:
                    type: string
                    format: date-time
                    description: 'The start of the range, inclusive'
                to:
                    type: string
                    format: date-time
                    description: 'The end of the range, exclusive. At most four hundred days after `from`'
            required: [names, from, to]
            description: 'The trends to read, over one range'
        MetricPoint:
            type: object
            properties:
                at:
                    type: string
                    format: date-time
                    description: 'The start of the minute or hour'
                count:
                    type: number
                    minimum: 0
                    description: 'How many observations were folded in'
                sum:
                    type: number
                    description: "Their total: a counter's value, or with `count` a duration's mean"
                min:
                    type: number
                    description: 'The smallest observation'
                max:
                    type: number
                    description: "The largest observation: a duration's worst"
                last:
                    type: number
                    description: "The latest observation: a gauge's value"
            required: [at, count, sum, min, max, last]
            description: 'One series over one minute or hour'
        MetricSeries:
            type: object
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                labels:
                    type: object
                    additionalProperties:
                        type: string
                    description: 'What tells this series from the metric''s others: `{ "queue": "catalog.sync" }`. Empty for a metric with one series'
                source:
                    type: string
                    minLength: 1
                    maxLength: 50
                    description: '`station` for what the station measured itself, `otlp` for what another service sent it'
                points:
                    type: array
                    items:
                        '$ref': '#/components/schemas/MetricPoint'
                    description: 'Only the buckets that hold something. A gap is a stretch nothing was measured, which a chart should draw as a gap'
            required: [name, labels, source, points]
            description: 'One metric and one set of labels, its points oldest first'
        MetricSeriesPage:
            type: object
            properties:
                resolution:
                    '$ref': '#/components/schemas/MetricResolution'
                    description: 'The width the points were read at'
                from:
                    type: string
                    format: date-time
                to:
                    type: string
                    format: date-time
                series:
                    type: array
                    items:
                        '$ref': '#/components/schemas/MetricSeries'
                    description: 'Empty when nothing was measured in the range, which is not an error'
            required: [resolution, from, to, series]
        MetricName:
            type: object
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                source:
                    type: string
                    minLength: 1
                    maxLength: 50
                labelKeys:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                    description: 'Every label any of its series carries, sorted'
                lastSeen:
                    type: string
                    format: date-time
                    description: 'The newest point held for it, at either resolution'
            required: [name, source, labelKeys, lastSeen]
            description: 'A metric the station holds, for a picker'
        MetricNames:
            type: object
            properties:
                names:
                    type: array
                    items:
                        '$ref': '#/components/schemas/MetricName'
                    description: 'Sorted by name'
            required: [names]
        StationSeries:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: "Unique across the station: the plugin's own id for the series, qualified with the plugin that offered it"
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                title:
                    type: string
                    minLength: 1
                    maxLength: 600
                    description: 'What the series is called, which is what a presenter says out loud'
                order:
                    type: string
                    enum: [serial, latest]
                    description: 'How it is worked through: `serial` from the beginning in order, `latest` its newest piece and nothing once that has aired'
                author:
                    type: string
                    maxLength: 600
                description:
                    type: string
                    maxLength: 4000
                    description: 'What the series says about itself, as plain text'
                artworkUrl:
                    type: string
                    maxLength: 2000
                homeUrl:
                    type: string
                    maxLength: 2000
                language:
                    type: string
                    maxLength: 40
                    description: "ISO 639-1, or the source's own tag. Also what the station splits sentences by when it cuts a long piece up"
            required: [id, pluginId, title, order]
            description: 'Something the station can read out, as one installed plugin describes it'
        StationSeriesList:
            type: object
            properties:
                series:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationSeries'
            required: [series]
        StationPiece:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: "The station's own id for this piece"
                seriesId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'Qualified, matching `StationSeries.id`'
                pieceId:
                    type: string
                    minLength: 1
                    maxLength: 1000
                    description: "The plugin's own id for the piece, stable across refreshes"
                seriesTitle:
                    type: string
                    minLength: 1
                    maxLength: 600
                title:
                    type: string
                    minLength: 1
                    maxLength: 1000
                order:
                    type: string
                    enum: [serial, latest]
                    description: 'How its series is worked through, copied onto the piece by every refresh'
                author:
                    type: string
                    maxLength: 600
                summary:
                    type: string
                    maxLength: 4000
                    description: 'What it is about, as plain text'
                url:
                    type: string
                    maxLength: 2000
                    description: "The piece's page, for a person"
                artworkUrl:
                    type: string
                    maxLength: 2000
                ordinal:
                    type: integer
                    minimum: 0
                    description: 'Where it comes in a serial, from 0. Absent for a `latest` series'
                publishedAt:
                    type: string
                    maxLength: 40
                    description: ISO-8601
                wordCount:
                    type: integer
                    minimum: 0
                    description: 'Roughly how many words it runs to, as the plugin counted them'
                seenAt:
                    type: string
                    maxLength: 40
                    description: 'ISO-8601: when a refresh last saw it listed'
                withdrawnAt:
                    type: string
                    maxLength: 40
                    description: 'ISO-8601: when a refresh found its plugin no longer listing it. The station never picks a withdrawn piece; the row is kept so what was done with it is not lost'
                rendered:
                    type: boolean
                    description: 'Whether the station has the spoken audio, ready to air'
                rendering:
                    type: boolean
                    description: 'Whether the words are being spoken right now'
                renderRequestedAt:
                    type: string
                    maxLength: 40
                    description: 'ISO-8601: when the station last asked for it to be spoken'
                renderError:
                    type: string
                    maxLength: 2000
                    description: 'Why the last attempt to speak it failed, when it did'
                scheduledFor:
                    type: string
                    maxLength: 40
                    description: 'ISO-8601: the slot it was made for'
                airedAt:
                    type: string
                    maxLength: 40
                    description: "ISO-8601: when a listener could first have heard it. A piece airs once, and for a serial this is also the station's place in the book"
            required: [id, seriesId, pieceId, seriesTitle, title, order, seenAt, rendered, rendering]
            description: 'One instalment, and what the station has done with it'
        StationPieceQuery:
            type: object
            properties:
                seriesId:
                    type: string
                    maxLength: 400
                    description: "One series' pieces in its own order, or absent for every series' newest first"
                limit:
                    type: integer
                    minimum: 1
                    maximum: 500
        StationPiecePage:
            type: object
            properties:
                pieces:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationPiece'
                    description: 'Empty when the station knows of none, which is not an error'
            required: [pieces]
        StationFeed:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: "Unique across the station: the plugin's own id for the feed, qualified with the plugin that offered it. Two services both calling something `world` stay distinct"
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                category:
                    type: string
                    maxLength: 200
                    description: "Broad subject, in the publisher's own word for it"
                language:
                    type: string
                    maxLength: 10
                    description: 'ISO 639-1, when the plugin knows'
                description:
                    type: string
                    maxLength: 2000
            required: [id, pluginId, name]
            description: 'A feed one installed plugin offers'
        StationFeedList:
            type: object
            properties:
                feeds:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationFeed'
            required: [feeds]
        NewsStory:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 600
                    description: 'Stable for the same entry across calls, which is what lets a reader tell an arrival from something it has already seen'
                feedId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'Qualified, matching `StationFeed.id`'
                feedName:
                    type: string
                    minLength: 1
                    maxLength: 200
                title:
                    type: string
                    minLength: 1
                    maxLength: 600
                summary:
                    type: string
                    maxLength: 2000
                    description: "The publisher's own teaser, as plain text. Never markup: this is written to be read out"
                content:
                    type: string
                    maxLength: 4000
                    description: "The story itself, as the publisher's own paragraphs. Absent when the plugin could not read one, which is ordinary: an entry that links to audio, or a page nothing could be extracted from"
                url:
                    type: string
                    maxLength: 2000
                publishedAt:
                    type: string
                    maxLength: 40
                    description: ISO-8601
                categories:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
            required: [id, feedId, feedName, title]
            description: 'One published entry'
        NewsQuery:
            type: object
            properties:
                feedId:
                    type: string
                    maxLength: 400
                    description: 'One feed, or absent for every feed the station can see, merged newest first'
                limit:
                    type: integer
                    minimum: 1
                    maximum: 100
                since:
                    type: string
                    maxLength: 40
                    description: 'Only entries published after this ISO-8601 instant'
                headlinesOnly:
                    type: boolean
                    description: "Answer with headlines and teasers alone, skipping the story behind each one. A story is read from the publisher's own page, which is by far the slowest thing this route does, so a caller that will not use `content` should say so"
        NewsPage:
            type: object
            properties:
                stories:
                    type: array
                    items:
                        '$ref': '#/components/schemas/NewsStory'
                    description: 'Newest first. Empty when nothing could be read, which is deliberately not an error: the news is something the station may talk about, never something it needs to air'
            required: [stories]
        NowPlayingTrack:
            type: object
            properties:
                kind:
                    type: string
                    enum: [record, break]
                    default: record
                    description: "`record` is music. `break` is the station speaking on its own between two records (an ident, a bulletin, a talk break), with `artist` empty and `title` the break's own label. A presenter talking over the start of a record is not a break: the record is what is on air, and it stays `record`. Absent means `record`, which is all a station older than this field ever reported"
                title:
                    type: string
                    minLength: 1
                    maxLength: 400
                artist:
                    type: string
                    maxLength: 400
                    description: 'Comma-joined, as a display line rather than a list: this is what a player or a device shows, not something to iterate. Empty for a `break`'
                album:
                    type: string
                    maxLength: 400
                artworkUrl:
                    type: string
                    maxLength: 2000
                    description: "The station's own cached cover, as a path under the API root (`art/...`). Absent while the station does not yet hold the cover, which a player answers with the station's logo; never a provider's URL"
                durationMs:
                    type: integer
                    minimum: 0
                startedAt:
                    type: integer
                    minimum: 0
                    description: 'Unix epoch millis, as observed when the player reported the track started'
                remainingMs:
                    type: integer
                    minimum: 0
                    description: 'Absent when the decoder cannot say. It leads the listener by the encoder and client buffers, so it is a display value and not a schedule'
            required: [kind, title, artist, startedAt]
            description: 'What a listener is hearing right now: a record, or the station talking'
        NowPlayingMount:
            type: object
            properties:
                format:
                    type: string
                    enum: [mp3, opus, aac, flac, hls]
                    description: '`hls` is the master playlist rather than an Icecast mount, which is why this enum has an arm `PlayoutMount` does not'
                path:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Same-origin path, leading slash included. A path and not a URL: the station is reached through whatever edge served this answer, never at the address the app itself uses'
                bitrateKbps:
                    type: integer
                    minimum: 1
                    description: "Absent for FLAC, which is lossless and has no rate to set, and for HLS, whose rate is the AAC variant's"
            required: [format, path]
            description: 'One way to listen to this station right now'
        NowPlayingShow:
            type: object
            properties:
                name:
                    type: string
                    maxLength: 200
                    description: "What this broadcast is called. It changes the moment the station changes programme, which can be one record before the new programme's first record is heard: a changeover never cuts a listener off mid-record"
                host:
                    type: string
                    maxLength: 200
                    description: "Who is presenting, by the name they go by on air. Absent when there is no name to give: no persona on air with one, and no station-wide presenter name set. Never the persona's console label"
                hostArtUrl:
                    type: string
                    maxLength: 2000
                    description: "A picture of whoever is presenting, when the operator gave their persona one. A path under the API root, like a cover's. Absent for a persona with no picture, which a player answers by showing the record's cover as before"
            required: [name]
            description: 'The programme on air, as a listener would be told it'
        NowPlaying:
            type: object
            properties:
                station:
                    type: string
                    maxLength: 200
                    description: "The station's on-air name"
                onAir:
                    type: boolean
                    description: 'False means the station is not broadcasting. `track` is absent in that case, which is an ordinary state and not an error'
                listeners:
                    type: integer
                    minimum: 0
                    description: "How many people are listening right now. Public because it says only what Icecast's own status document already says to anyone who asks, and a station page should not need a session to show it"
                mounts:
                    type: array
                    items:
                        '$ref': '#/components/schemas/NowPlayingMount'
                    description: 'Every way to listen, MP3 first. Never empty: MP3 has no switch. A format the operator has not switched on is ABSENT rather than present and disabled, because a client asking this wants the mounts that are actually there — and a client that had to find out by connecting to each one would put an audience-gated station on air to do it'
                show:
                    '$ref': '#/components/schemas/NowPlayingShow'
                    description: 'Present whenever `track` is and the station has said what programme it belongs to. Absent off air, and while a station warming up has nothing airing yet'
                track:
                    '$ref': '#/components/schemas/NowPlayingTrack'
            required: [station, onAir, listeners, mounts]
            description: 'What the station is playing, for anything that wants to display it'
        NowPlayingLyrics:
            type: object
            properties:
                onAir:
                    type: boolean
                    description: 'False when nothing is airing, with everything else absent'
                trackId:
                    type: string
                    format: uuid
                    description: 'The catalog record on air. Absent while the station is talking, and for a record the catalog has never held'
                startedAt:
                    type: integer
                    minimum: 0
                    description: 'Unix epoch millis when the record went on air, the same instant `/nowplaying` reports. Match on it before pairing these lyrics with a `/nowplaying` reading'
                cueInMs:
                    type: integer
                    minimum: 0
                    description: 'Where in the file the record started playing. Absent means the top of the file'
                cueOutMs:
                    type: integer
                    minimum: 0
                    description: "Where in the file the record stops playing. A line's `atMs` counts from the top of the file and the decoder's `remainingMs` counts down to this point, so the position to highlight is this (or the record's `durationMs` when absent) minus `remainingMs`. Absent for a record nothing has measured, which plays to the end of the file"
                lyrics:
                    '$ref': '#/components/schemas/TrackLyrics'
                    description: "The station's answer for that record. Absent with no `trackId`"
            required: [onAir]
            description: 'The words of whatever record is on air, and where it is in them'
        OAuthAuthorizationQuery:
            type: object
            properties:
                query:
                    type: string
                    maxLength: 8192
                    description: 'The query string the app sent the browser to the consent page with, as `window.location.search` holds it'
            required: [query]
            description: "An app's authorization request, as the consent page received it"
        OAuthClientKind:
            type: string
            enum: [preregistered, dynamic, metadata_document]
            description: 'How the station knows an app: registered by an operator, registered by itself, or described by a document on its own website'
        OAuthAuthorizationContext:
            type: object
            properties:
                kind:
                    const: context
                    description: Discriminator
                requestId:
                    type: string
                    maxLength: 200
                    description: 'What approving or denying names. Good for a few minutes, and only for the person it was shown to'
                clientId:
                    type: string
                    description: "The app's client id"
                clientKind:
                    '$ref': '#/components/schemas/OAuthClientKind'
                    description: 'How the station knows the app'
                clientName:
                    type: string
                    description: 'What the app calls itself'
                clientUri:
                    type: string
                    description: "The app's own website, when it gave one"
                logoUri:
                    type: string
                    description: "The app's logo, when it gave one"
                redirectHost:
                    type: string
                    description: 'The host the browser is sent back to, which is who actually receives the approval'
                loopbackOnly:
                    type: boolean
                    description: "Whether every address the app registered is this computer's own, which only an app running on it should use"
                scope:
                    type: array
                    items:
                        type: string
                    description: 'What the app asked for. The person chooses what it gets when approving, whatever this says'
                resource:
                    type: string
                    description: "What the app will be able to reach: the station's MCP endpoint"
            required:
                - kind
                - requestId
                - clientId
                - clientKind
                - redirectHost
                - loopbackOnly
                - scope
                - resource
            description: 'A valid request, stashed for the signed-in person to approve or deny'
        OAuthAuthorizationRedirect:
            type: object
            properties:
                kind:
                    const: redirect
                    description: Discriminator
                redirectUrl:
                    type: string
                    description: 'Where to send the browser'
            required: [kind, redirectUrl]
            description: 'A request with something wrong that the app should be told about: send the browser back to it'
        OAuthAuthorizationRefusal:
            type: object
            properties:
                kind:
                    const: refuse
                    description: Discriminator
                error:
                    type: string
                    description: 'The OAuth error code'
                description:
                    type: string
                    description: 'What was wrong, in words'
            required: [kind, error, description]
            description: 'A request that names no app the station knows, or an address the app did not register. Never sent anywhere'
        OAuthAuthorizationContextResult:
            oneOf:
                - '$ref': '#/components/schemas/OAuthAuthorizationContext'
                - '$ref': '#/components/schemas/OAuthAuthorizationRedirect'
                - '$ref': '#/components/schemas/OAuthAuthorizationRefusal'
            discriminator:
                propertyName: kind
                mapping:
                    context: '#/components/schemas/OAuthAuthorizationContext'
                    redirect: '#/components/schemas/OAuthAuthorizationRedirect'
                    refuse: '#/components/schemas/OAuthAuthorizationRefusal'
        OAuthAuthorizationDecision:
            type: object
            properties:
                requestId:
                    type: string
                    maxLength: 200
                    description: 'From the context'
            required: [requestId]
            description: 'Denying a stashed request'
        OAuthGrantScope:
            type: string
            enum: [view, manage]
            description: 'What a connected app may do on the station. `view` reads it; `manage` changes it and includes `view`. Never more than the person approving it may do'
        OAuthAuthorizationApproval:
            type: object
            properties:
                requestId:
                    type: string
                    maxLength: 200
                    description: 'From the context'
                scopes:
                    type: array
                    items:
                        '$ref': '#/components/schemas/OAuthGrantScope'
                    description: 'What the person lets the app do. At least one; `manage` includes `view`. Replaces whatever the app asked for'
            required: [requestId, scopes]
            description: 'Approving a stashed request, with what the app may do'
        OAuthAuthorizationOutcome:
            type: object
            properties:
                redirectUrl:
                    type: string
                    description: "The app's own address, carrying the code or the refusal"
            required: [redirectUrl]
            description: 'Where to send the browser now'
        OAuthClientAuthMethod:
            type: string
            enum: [none, client_secret_post, client_secret_basic]
            description: "How the app proves itself at the token endpoint. `none` is a public client, which is what apps on somebody's own device are"
        OAuthClientSummary:
            type: object
            properties:
                clientId:
                    type: string
                    description: 'Its client id'
                kind:
                    type: string
                    enum: [preregistered, dynamic]
                    description: 'Created by an operator, or registered by itself'
                name:
                    type: string
                    description: 'What it is called'
                redirectUris:
                    type: array
                    items:
                        type: string
                    description: 'Where it may be sent back to'
                tokenEndpointAuthMethod:
                    '$ref': '#/components/schemas/OAuthClientAuthMethod'
                    description: 'How it proves itself'
                createdAt:
                    type: string
                    format: date-time
                    description: 'When it was registered'
                lastUsedAt:
                    type: string
                    format: date-time
                    description: 'When it last obtained a token'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When a self-registered app lapses unless used again'
            required: [clientId, kind, redirectUris, tokenEndpointAuthMethod, createdAt]
            description: 'An app registered with the station'
        OAuthClientList:
            type: object
            properties:
                clients:
                    type: array
                    items:
                        '$ref': '#/components/schemas/OAuthClientSummary'
                    description: 'Newest first. Apps that describe themselves are not listed: nothing is stored for them'
            required: [clients]
        OAuthClientCreate:
            type: object
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'What to call it'
                redirectUris:
                    type: array
                    items:
                        type: string
                        maxLength: 2048
                    description: "Where it may be sent back to. At least one; https, or this computer's own address"
                tokenEndpointAuthMethod:
                    '$ref': '#/components/schemas/OAuthClientAuthMethod'
                    description: "`none` for an app on somebody's own device, otherwise a secret it keeps"
            required: [name, redirectUris, tokenEndpointAuthMethod]
            description: 'An app an operator registers by hand, for a client that cannot register itself'
        OAuthClientIssued:
            type: object
            properties:
                client:
                    '$ref': '#/components/schemas/OAuthClientSummary'
                    description: 'The app as it will appear in the list'
                clientSecret:
                    type: string
                    description: 'Present for an app that keeps a secret. Store it now: nothing can show it again'
            required: [client]
            description: 'A registered app, with its secret. The only time the secret is ever returned'
        OAuthGrant:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    description: 'For disconnecting it'
                clientId:
                    type: string
                    description: "The app's client id"
                clientName:
                    type: string
                    description: 'What the app calls itself, when the station can still find out'
                resource:
                    type: string
                    description: 'What it can reach'
                scope:
                    type: array
                    items:
                        type: string
                    description: 'What it was granted: `mcp`, and the station scopes it may use (`view`, `manage`)'
                createdAt:
                    type: string
                    format: date-time
                    description: 'When it was first approved'
                lastUsedAt:
                    type: string
                    format: date-time
                    description: 'When it last obtained a token'
            required: [id, clientId, resource, scope, createdAt]
            description: 'An app the signed-in person has let act as them'
        OAuthGrantList:
            type: object
            properties:
                grants:
                    type: array
                    items:
                        '$ref': '#/components/schemas/OAuthGrant'
                    description: 'Most recent first'
            required: [grants]
        OnboardingRequirementKey:
            type: string
            enum: [admin.account]
        CoreOnboardingRequirement:
            type: object
            properties:
                key:
                    '$ref': '#/components/schemas/OnboardingRequirementKey'
                    description: 'The key of the requirement'
                title:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                    description: 'Human-readable label for the onboarding checklist'
                description:
                    type: string
                    readOnly: true
                    description: 'Optional longer explanation'
                optional:
                    type: boolean
                    readOnly: true
                    description: 'Whether the requirement is optional for onboarding'
            required: [key, title, optional]
            description: 'A single onboarding requirement'
        AdminAccountOnboardingRequirement:
            allOf:
                - '$ref': '#/components/schemas/CoreOnboardingRequirement'
                - type: object
                  properties:
                      key:
                          const: admin.account
                      value:
                          type: object
                          properties:
                              email:
                                  type: string
                                  format: email
                              password:
                                  type: string
                                  minLength: 8
                                  maxLength: 256
                                  description: 'The password'
                          required: [email, password]
                          writeOnly: true
                  required: [key, value]
        OnboardingRequirement:
            '$ref': '#/components/schemas/AdminAccountOnboardingRequirement'
        OutputMount:
            type: object
            properties:
                format:
                    type: string
                    enum: [mp3, opus, aac, flac, hls]
                path:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Same-origin path, leading slash included, as `/nowplaying` gives it'
            required: [format, path]
            description: "One of the station's mounts a speaker can play"
        OutputDevice:
            type: object
            properties:
                pluginId:
                    type: string
                    maxLength: 200
                    description: 'The plugin that drives it, for example `deadair.cast`'
                deviceId:
                    type: string
                    maxLength: 400
                    description: "The plugin's own id for the speaker. Stable across restarts"
                name:
                    type: string
                    maxLength: 200
                    description: 'What the operator calls it'
                model:
                    type: string
                    maxLength: 200
                    description: 'The make or model, where the speaker says'
                address:
                    type: string
                    maxLength: 400
                    description: 'How the plugin reaches it, for recognising rather than dialling'
                protocol:
                    type: string
                    maxLength: 50
                    description: 'How it is driven, for a plugin that speaks several: `chromecast`, `upnp`, `bluos`'
                mounts:
                    type: array
                    items:
                        '$ref': '#/components/schemas/OutputMount'
                    description: "The station's mounts this speaker can play, MP3 first. Empty when it plays none of the ones switched on"
                casting:
                    type: boolean
                    description: 'Whether the station is meant to be playing on it now. `/outputs/casts` says how that is going'
            required: [pluginId, deviceId, name, address, mounts, casting]
            description: 'A speaker the station can play on, as an `output` plugin listed it'
        OutputProblem:
            type: object
            properties:
                pluginId:
                    type: string
                    maxLength: 200
                message:
                    type: string
                    maxLength: 1000
            required: [pluginId, message]
            description: 'A plugin that could not list its speakers'
        OutputDeviceList:
            type: object
            properties:
                devices:
                    type: array
                    items:
                        '$ref': '#/components/schemas/OutputDevice'
                problems:
                    type: array
                    items:
                        '$ref': '#/components/schemas/OutputProblem'
                    description: 'Plugins that did not answer. Their speakers are missing from `devices` rather than the whole list failing'
                discoverySeesNothing:
                    type: boolean
                    description: 'True when the station has looked for speakers on its network and never found one, which on a container usually means its network cannot carry multicast (a bridge network). Speakers added by address still work'
            required: [devices, problems, discoverySeesNothing]
            description: 'Every speaker every `output` plugin can play the station on'
        OutputCast:
            type: object
            properties:
                pluginId:
                    type: string
                    maxLength: 200
                deviceId:
                    type: string
                    maxLength: 400
                deviceName:
                    type: string
                    maxLength: 200
                    description: 'What the speaker was called when the cast started'
                mountPath:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Which mount it plays'
                startedAt:
                    type: string
                    format: date-time
                phase:
                    type: string
                    enum: [idle, opening, buffering, playing, stopped, unreachable]
                    description: "As the speaker reports it now. `opening` and `buffering` are a stream starting, not a failure; `stopped` with the station's stream still loaded is played again on its own; `unreachable` is a speaker that did not answer, which the station waits out"
                detail:
                    type: string
                    maxLength: 1000
                    description: 'A sentence about the phase when it needs one, such as why a speaker is unreachable'
            required: [pluginId, deviceId, deviceName, mountPath, startedAt, phase]
            description: 'A speaker the station is meant to be playing on, and how it is doing'
        OutputCastList:
            type: object
            properties:
                casts:
                    type: array
                    items:
                        '$ref': '#/components/schemas/OutputCast'
            required: [casts]
            description: 'Every speaker the station is meant to be playing on'
        OutputCastRequest:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                deviceId:
                    type: string
                    minLength: 1
                    maxLength: 400
                mountPath:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "Which mount, from the speaker's `mounts`. Absent means its first, which is MP3 wherever the speaker takes it"
            required: [pluginId, deviceId]
            description: 'Play the station on a speaker'
        Persona:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                key:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'A stable slug, unique per station. What a log line names and what a seeded persona is recognised by'
                kind:
                    type: string
                    enum: [host, caller, newsreader, guest]
                    description: 'The one of `kinds` that ranks highest, host first, kept for clients built before a character could be several things. Sent without `kinds`, it is a character of this one kind; sent with it, `kinds` wins. Absent means `host`'
                kinds:
                    type: array
                    items:
                        type: string
                        enum: [host, caller, newsreader, guest]
                    minItems: 1
                    maxItems: 4
                    description: "What this character may be cast as, in any combination. A `host` presents, which is the station's own voice or a show's; a `caller` phones in to a production and a `guest` drops by the studio on a `visit`, both cast per programme and never onto a show the character is presenting that night; the `newsreader` reads every news bulletin, in its own character and voice, whoever is hosting, and the station has at most one. Absent means `kind` alone, or `host`"
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                style:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: 'Completes "You are …". Who they ARE; the sheet below carries how they talk'
                djName:
                    type: string
                    maxLength: 200
                    description: "The name this character goes by on air, overriding the station's own while it is active"
                voice:
                    type: string
                    maxLength: 200
                    description: "The station voice that speaks this persona, as the id a speech plugin maps. Empty means that plugin's default"
                soundboard:
                    type: string
                    maxLength: 200
                    description: 'The soundboard this character has to hand, as the name of a board in the pad library. Empty for a presenter who works without one. What reaches a model is the names of the pads on that board, never this word'
                diction:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                    description: 'The dialect: grammar and substitutions that apply to every sentence rather than to a subject'
                dictionMarkers:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 100
                    description: "Words whose presence proves the dialect survived. What a model's answer is checked against"
                quirks:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaQuirk'
                    description: 'What they always and never do on air. One with a cadence is something they do only now and then, and the station decides which breaks'
                preoccupations:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                    description: 'The standing subjects they keep coming back to. Exactly ONE reaches any one break, chosen by rotation, which is what makes a character sound like it has things on its mind rather than one thing'
                catchphrases:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                    description: 'Signature phrases, asked for sparingly'
                avoid:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                    description: 'Wording that breaks the character'
                exclusiveSubjects:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                    description: 'Subjects this character takes one at a time. Each entry is ONE subject, written as the comma-separated words that mean it ("bigfoot, sasquatch, yeti"), and a break that brings up words from two of them is refused and written again. A word inside a record''s title does not count'
                background:
                    type: string
                    maxLength: 2000
                    description: 'A couple of grounded facts they may self-reference'
                brevity:
                    type: string
                    enum: [short, one-line]
                    description: "How much this character says. Absent for the station's ordinary length; the rung above it is `latitude`, which is a different kind of thing rather than a longer one"
                latitude:
                    type: string
                    enum: [loose, unleashed]
                    description: "How much room this character is given, above the station's ordinary discipline: a bigger word ceiling, a licence to follow the thought instead of making one point, and at `unleashed` no restraint on how it says it. Offered only by the ordinary talk break, always outranked by the station's content policy, and it switches off no refusal"
                chattiness:
                    type: string
                    enum: [reserved, sparing, ordinary, chatty, relentless]
                    description: "How often this character talks, as a scale on the station's own interval between breaks. Absent is `ordinary`, which is that interval unchanged. The quietest rung is half as often and never silence: turning the station's breaks off is a station setting, and two switches for one thing can disagree"
                storytelling:
                    type: string
                    enum: [never, occasionally, often]
                    description: 'How readily this character works one of its own stories into an ordinary talk break. Absent is `occasionally`, which offers one only where the station knows nothing about the records either side. The stories themselves are their own list, and a `story` band on the clock outranks this whatever it says'
                growth:
                    type: string
                    enum: [proposes, self-directed]
                    description: 'Whether the nightly passes may write this character new material outright, or only ever propose it for you to accept. Absent is `proposes`, which is what every character does until somebody says otherwise. It reaches no prompt: the character is never told which it is'
                trivia:
                    type: string
                    enum: [keen, never, always, sometimes]
                    description: "How much this character leans on what the station knows about a record. Absent is the station's ordinary break, where the notes are optional and two at most. At `never` the break is shown none of them and nothing is rested. At `always` the station chooses one fact for every link, where it has one, and asks for it to be said beside the presenter's own patter. At `sometimes` a share of links are treated as `always` and the rest as `never`, drawn per link. At `keen` each record brings up to four, one each about the recording, its album and its artist before a second about any, and the break is built out of them with the room to tell one. Offered only by the ordinary talk break, and the grounding rules do not move: it may still say only what a note says"
                samples:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                    description: 'Lines in their own voice, used as examples and as a console preview'
                sheetLanguage:
                    type: string
                    minLength: 2
                    maxLength: 35
                    description: "The language this character's sheet is written in, as a BCP 47 tag such as `en` or `de`. Every built-in character is `en`. Absent on a save keeps what the character had, and a new character takes the station's language"
                templates:
                    type: string
                    maxLength: 20000
                    description: "This character's own break phrasings, one per line. Empty means the station's own five"
                hosts:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 100
                    description: "The hosts this character rings in to or drops by on, when it is a `caller` or a `guest`, as persona ids. A tied character is cast only into a phone-in or a visit one of them presents; absent or empty turns up on whoever is presenting. Sent on a character that is neither, it is refused, and every id must be one of this station's hosts. Deleting a host, or making it something that cannot present, unties the characters tied to it rather than silencing them. Saving a caller or a guest without it clears its ties"
                defaultHost:
                    type: boolean
                    readOnly: true
                    description: 'The station''s own host: who presents when the broadcast on air names nobody. At most one per station. Was `active` until it was renamed, because a reader who had not read `PersonaRepository.presenting` reasonably took that to mean "on air", which it is not during a show that named its own host'
                presenting:
                    type: boolean
                    readOnly: true
                    description: 'Whether this character is the one writing breaks right now. Derived per request from the running order, falling back to `defaultHost`, through the one place that precedence lives (`PersonaRepository.presenting`). Never stored, so it cannot drift from what the director is actually doing'
                coHosting:
                    type: boolean
                    readOnly: true
                    description: 'Whether this character presents BESIDE the one writing breaks on the broadcast on air: one of the co-hosts the schedule put on for tonight, read from the same running order as `presenting`. Present and true only for them, absent for everybody else, so a client built before it reads no change. Never true alongside `presenting`'
            required: [id, key, label, style, defaultHost, presenting]
            description: 'Who the station is when it opens its mouth: the character a model writes in, the phrasings underneath it, the voice that says them, and what it plays'
        PersonaQuirk:
            type: object
            properties:
                text:
                    type: string
                    minLength: 1
                    maxLength: 500
                cadence:
                    type: string
                    enum: [always, often, occasionally, rarely]
                    description: 'How often it applies. Absent is `always`: a rule, sent on every break. The others are something the character does now and then, and the station picks which ordinary talk breaks, at most one such quirk to a break, so the text should not say "now and then" itself'
            required: [text]
            description: 'One thing a character does on air, and how often it does it'
        PersonaList:
            type: object
            properties:
                personas:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Persona'
            required: [personas]
        PersonaRequest:
            type: object
            properties:
                description:
                    type: string
                    minLength: 1
                    maxLength: 2000
            required: [description]
            description: "A description of a character, in the operator's own words"
        PersonaDraftView:
            type: object
            properties:
                key:
                    type: string
                    minLength: 1
                    maxLength: 100
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                style:
                    type: string
                    minLength: 1
                    maxLength: 2000
                djName:
                    type: string
                    maxLength: 200
                voice:
                    type: string
                    maxLength: 200
                soundboard:
                    type: string
                    maxLength: 200
                diction:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                dictionMarkers:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 100
                quirks:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaQuirk'
                preoccupations:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                catchphrases:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                avoid:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                exclusiveSubjects:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                background:
                    type: string
                    maxLength: 2000
                brevity:
                    type: string
                    enum: [short, one-line]
                latitude:
                    type: string
                    enum: [loose, unleashed]
                chattiness:
                    type: string
                    enum: [reserved, sparing, ordinary, chatty, relentless]
                storytelling:
                    type: string
                    enum: [never, occasionally, often]
                trivia:
                    type: string
                    enum: [keen, never, always, sometimes]
                samples:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                sheetLanguage:
                    type: string
                    minLength: 2
                    maxLength: 35
                templates:
                    type: string
                    maxLength: 20000
            required: [key, label, style]
            description: "A persona as a form's contents rather than a row: no id and not on air, because nothing has been\nsaved. The console opens this in the editor and the operator saves it through POST /personas, which\nis what keeps generating a way of filling in the form rather than a second writer of the table"
        GeneratedPersona:
            type: object
            properties:
                persona:
                    '$ref': '#/components/schemas/PersonaDraftView'
                stories:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaStoryWrite'
                    description: "A couple of things that have happened to this character. Beside the form rather than in it, because they are their own table: the console saves the persona and then writes these through the stories route, so they go through the same validation an operator's own typing does"
                droppedMarkers:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 100
                    description: 'Words the model called markers that its own sample lines never used. Dropped, because the samples are the evidence and the marker list is the claim — a marker nothing says declines every break and looks exactly like a model that is switched off'
                droppedTemplates:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                    description: 'Phrasings naming a value the vocabulary does not have. Dropped by the LINE, since five good phrasings and one broken one is five phrasings'
            required: [persona, stories, droppedMarkers, droppedTemplates]
            description: 'What a model wrote, and what had to be dropped to make it usable'
        PersonaNote:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                kind:
                    type: string
                    enum: [said, trait]
                    description: "`said` is what this character did, rendered beside the show's memory. `trait` is who it has become, rendered beside the sheet"
                note:
                    type: string
                    minLength: 1
                    maxLength: 500
                    description: 'One sentence, because it shares a system turn with the grounding rules'
                state:
                    type: string
                    enum: [active, suggested, rejected]
                    readOnly: true
                    description: '`active` is carried into breaks. `rejected` outlives the pass that proposed it, or the same scripts propose it again forever'
                origin:
                    type: string
                    enum: [operator, model]
                    readOnly: true
                    description: "Who says so. `model` is the distil pass reading this character's own history back"
                sourceScriptId:
                    type: string
                    maxLength: 100
                    readOnly: true
                    description: 'The attempt this was drawn from, while that row still exists. The nightly sweep takes it and the quote below stays'
                sourceQuote:
                    type: string
                    maxLength: 2000
                    readOnly: true
                    description: 'The words that support it, as the station said them. What an operator actually accepts or rejects on, and required of anything a model wrote'
                lastUsedAt:
                    type: string
                    maxLength: 40
                    readOnly: true
                    description: 'When it was last carried into a break. Absent means never, which is what puts it at the front of the rotation'
                createdAt:
                    type: string
                    minLength: 1
                    maxLength: 40
                    readOnly: true
            required: [id, kind, note, state, origin, createdAt]
            description: "One thing this character has accumulated that its sheet does not hold. Two kinds and they are two\ndifferent claims: `said` records something it actually put on air and carries the script as its\nevidence, so it is a record and goes straight into use; `trait` infers who the character is\nbecoming, which nothing can verify, so a model's arrives `suggested` and the operator is the check"
        PersonaNoteList:
            type: object
            properties:
                personaId:
                    type: string
                    minLength: 1
                    maxLength: 100
                notes:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaNote'
            required: [personaId, notes]
            description: "One character's whole notebook, oldest first, in every state"
        PersonaNoteWrite:
            type: object
            properties:
                kind:
                    type: string
                    enum: [said, trait]
                note:
                    type: string
                    minLength: 1
                    maxLength: 500
            required: [kind, note]
            description: 'A note an operator is writing by hand. Always active and always theirs; a proposal is something only the distil pass creates'
        PersonaNoteState:
            type: object
            properties:
                state:
                    type: string
                    enum: [active, suggested, rejected]
            required: [state]
            description: 'Accepting a proposal, turning one down, or taking a note out of use without losing it'
        PersonaStory:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                title:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'A short handle. Never spoken; what this list is read by and what a proposal names'
                story:
                    type: string
                    minLength: 1
                    maxLength: 4000
                    description: "The telling itself, in the character's voice. Already speakable, because the floor reads it as it stands"
                state:
                    type: string
                    enum: [active, suggested, rejected]
                    readOnly: true
                    description: '`active` can be told. `rejected` outlives the pass that proposed it, or the same catalogue proposes it forever'
                origin:
                    type: string
                    enum: [operator, model]
                    readOnly: true
                    description: 'Who says so. `model` is the enrichment pass writing from what the station already holds'
                source:
                    type: string
                    maxLength: 1000
                    readOnly: true
                    description: "Where a proposal came from, in the station's own words. Absent for anything an operator wrote"
                kind:
                    type: string
                    enum: [anecdote, arc, bit]
                    readOnly: true
                    description: 'An `anecdote` is told whole, an `arc` a part at a time, a `bit` is a running joke with no end'
                details:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaStoryDetail'
                    readOnly: true
                    description: 'What it has picked up since, in every state'
                beats:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaStoryBeat'
                    readOnly: true
                    description: 'The parts an arc is told in, in order and in every state. Empty for the other two kinds'
                lastToldAt:
                    type: string
                    maxLength: 40
                    readOnly: true
                    description: 'Absent means never told, which is what puts it at the front of the rotation'
                timesTold:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'How often it has gone out, which changes how the model is asked to tell it'
                createdAt:
                    type: string
                    minLength: 1
                    maxLength: 40
                    readOnly: true
            required: [id, title, story, state, origin, kind, details, beats, timesTold, createdAt]
            description: "Something that happened to this character, in its own telling. Not a claim about the world and never\nchecked as one: `source` says where a proposal came from, for the operator reading it, and nothing\ndownstream reads it as evidence — see `persona.story.ts` for why that is the load-bearing difference\nfrom a fact"
        PersonaStoryDetail:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                detail:
                    type: string
                    minLength: 1
                    maxLength: 1000
                state:
                    type: string
                    enum: [active, suggested, rejected]
                    readOnly: true
                origin:
                    type: string
                    enum: [operator, model]
                    readOnly: true
                source:
                    type: string
                    maxLength: 1000
                    readOnly: true
                createdAt:
                    type: string
                    minLength: 1
                    maxLength: 40
                    readOnly: true
            required: [id, detail, state, origin, createdAt]
            description: 'One thing a story has picked up since it was written. A row rather than a rewrite, so an invented clause can be turned down without losing the story'
        PersonaStoryList:
            type: object
            properties:
                personaId:
                    type: string
                    minLength: 1
                    maxLength: 100
                stories:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaStory'
            required: [personaId, stories]
            description: 'Every story one character holds, oldest first, in every state'
        PersonaStoryWrite:
            type: object
            properties:
                title:
                    type: string
                    minLength: 1
                    maxLength: 200
                story:
                    type: string
                    minLength: 1
                    maxLength: 4000
                kind:
                    type: string
                    enum: [anecdote, arc, bit]
                    description: 'What sort of thing this is. Absent means `anecdote`, which is what every story written before arcs existed is'
            required: [title, story]
            description: 'A story an operator is writing by hand. Always active and always theirs; a proposal is something only the enrichment pass creates'
        PersonaStoryBeat:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                storyId:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                ordinal:
                    type: integer
                    minimum: 0
                    description: 'Where it comes in the telling. Gaps are legal: inserting a part between two others must not mean renumbering the rest'
                beat:
                    type: string
                    minLength: 1
                    maxLength: 4000
                state:
                    type: string
                    enum: [active, suggested, rejected]
                    readOnly: true
                origin:
                    type: string
                    enum: [operator, model]
                    readOnly: true
                source:
                    type: string
                    maxLength: 1000
                    readOnly: true
                    description: "Where a proposal came from. Not evidence; see the note on a story's own source"
                createdAt:
                    type: string
                    minLength: 1
                    maxLength: 40
                    readOnly: true
            required: [id, storyId, ordinal, beat, state, origin, createdAt]
            description: 'One part of an arc, in the order it is told. A SCRIPT rather than a summary, because the floor speaks it as it stands'
        PersonaStoryBeatWrite:
            type: object
            properties:
                ordinal:
                    type: integer
                    minimum: 0
                beat:
                    type: string
                    minLength: 1
                    maxLength: 4000
            required: [ordinal, beat]
            description: 'A part to add to an arc, or an edit to one'
        PersonaStoryDetailWrite:
            type: object
            properties:
                detail:
                    type: string
                    minLength: 1
                    maxLength: 1000
            required: [detail]
            description: 'One thing to add to a story that already exists'
        PersonaStoryState:
            type: object
            properties:
                state:
                    type: string
                    enum: [active, suggested, rejected]
            required: [state]
            description: 'Accepting a proposal, turning one down, or taking a story out of the rotation without losing it'
        PersonaFile:
            type: object
            properties:
                format:
                    type: string
                    minLength: 1
                    maxLength: 50
                    description: 'What shape this is, so a file from a later build says so rather than being read wrongly. The shapes below are what an import actually validates; this is for the human reading the failure'
                takenAt:
                    type: string
                    minLength: 1
                    maxLength: 40
                    description: 'When it was exported, ISO-8601'
                station:
                    type: string
                    maxLength: 100
                    description: 'The station it was taken from. Provenance only: an import writes into whichever station it is running as, and the two need not match'
                personas:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaFilePersona'
            required: [format, takenAt, personas]
            description: "A character as a file: everything somebody would have to send to put this presenter on another\nstation, and nothing that belongs to the station it came from"
        PersonaFilePersona:
            allOf:
                - '$ref': '#/components/schemas/PersonaDraftView'
                - type: object
                  properties:
                      kind:
                          type: string
                          enum: [host, caller, newsreader, guest]
                          description: 'The one kind a `deadair.persona/2` file carries, read as a character of that kind alone. Absent, with no `kinds`, means `host`, as everywhere else'
                      kinds:
                          type: array
                          items:
                              type: string
                              enum: [host, caller, newsreader, guest]
                          minItems: 1
                          maxItems: 4
                          description: 'What the character may be cast as, in any combination. Wins over `kind` when a file has both'
                      soundboard:
                          type: string
                          maxLength: 200
                          description: 'The board this character reaches for. Carried even though the receiving station may not hold it: a persona naming a rack that does not exist and one with no rack are the same state, and the import says which it got'
                      stories:
                          type: array
                          items:
                              '$ref': '#/components/schemas/PersonaFileStory'
                  required: [stories]
        PersonaFileStory:
            type: object
            properties:
                title:
                    type: string
                    minLength: 1
                    maxLength: 200
                story:
                    type: string
                    minLength: 1
                    maxLength: 4000
                kind:
                    type: string
                    enum: [anecdote, arc, bit]
                    description: 'Absent means `anecdote`. What sort of thing this is travels because it is part of what the story IS, not part of what this station has done with it'
                state:
                    type: string
                    enum: [active, rejected]
                    description: 'Absent means `active`. A turned-down story travels so the enrichment pass does not propose it again on the far side; an undecided one does not travel at all, because nobody has decided it yet'
                details:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaFileStoryDetail'
                beats:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaFileStoryBeat'
                    description: 'The parts an arc is told in, in order. Empty for the other two kinds'
            required: [title, story, details, beats]
            description: "Something that happened to this character, as a file carries it. No `origin` and no `source`,\nunlike the stored row: whoever exported this stood behind every story in it, so on the far side\nthey are the receiving operator's own, and a sentence about where a proposal came from names a\ncatalogue that station does not have"
        PersonaFileStoryBeat:
            type: object
            properties:
                ordinal:
                    type: integer
                    minimum: 0
                beat:
                    type: string
                    minLength: 1
                    maxLength: 4000
                state:
                    type: string
                    enum: [active, rejected]
                    description: "Absent means `active`, exactly as a story's does"
            required: [ordinal, beat]
            description: "One part of an arc, as a file carries it. No `origin` and no `source`, for the story's own reason"
        PersonaFileStoryDetail:
            type: object
            properties:
                detail:
                    type: string
                    minLength: 1
                    maxLength: 1000
                state:
                    type: string
                    enum: [active, rejected]
            required: [detail]
            description: 'One thing a story picked up after it was written, carried the same way and for the same reasons'
        PersonaImportPlan:
            type: object
            properties:
                format:
                    type: string
                    minLength: 1
                    maxLength: 50
                    readOnly: true
                    description: 'What the file said it was. Reported rather than enforced: this repo edits migrations in place, so a version stamp cannot promise a shape, and the shapes are what was actually validated'
                station:
                    type: string
                    maxLength: 100
                    readOnly: true
                    description: 'The station it was taken from, when it said'
                takenAt:
                    type: string
                    maxLength: 40
                    readOnly: true
                    description: 'When it was taken, when it said'
                notices:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaImportNotice'
                    readOnly: true
                    description: 'About the FILE rather than any one character in it'
                personas:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaImportEntry'
                    readOnly: true
            required: [format, notices, personas]
            description: "What importing a file WOULD do, worked out against this station and written nowhere.\n\nThe same code the import itself runs, so what this reports is what will happen rather than a second\nopinion about it. It answers two questions an operator cannot get from the file alone: which\ncharacters are new here and which would be rewritten, and what this station cannot honour about them"
        PersonaImportEntry:
            type: object
            properties:
                key:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                    description: 'What identifies this character across two installs'
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                kind:
                    type: string
                    enum: [host, caller, newsreader, guest]
                    readOnly: true
                    description: 'The one of `kinds` that ranks highest, host first, for a console built before `kinds`'
                kinds:
                    type: array
                    items:
                        type: string
                        enum: [host, caller, newsreader, guest]
                    readOnly: true
                    description: "What the character will be cast as here: the file's `kinds`, else its one `kind`, else `host`"
                outcome:
                    type: string
                    enum: [create, update, skip]
                    readOnly: true
                    description: 'Whether this station holds a character under this key already, and if so whether the import was asked to replace it. An update rewrites the sheet and adds stories; it never deletes one the operator here wrote. A skip writes nothing at all, and its counts and notices say what replacing it WOULD do, so a console can offer the choice without asking again'
                storiesNew:
                    type: integer
                    minimum: 0
                    readOnly: true
                storiesHeld:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Already here under the same handle, so importing would skip them'
                detailsNew:
                    type: integer
                    minimum: 0
                    readOnly: true
                detailsHeld:
                    type: integer
                    minimum: 0
                    readOnly: true
                notices:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaImportNotice'
                    readOnly: true
            required:
                - key
                - label
                - outcome
                - storiesNew
                - storiesHeld
                - detailsNew
                - detailsHeld
                - notices
            description: 'One character in a file, and what would become of it here'
        PersonaImportResult:
            type: object
            properties:
                plan:
                    '$ref': '#/components/schemas/PersonaImportPlan'
                    readOnly: true
                    description: 'What it decided to do, notices and all, so the answer carries its own explanation'
                created:
                    type: integer
                    minimum: 0
                    readOnly: true
                updated:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Characters whose sheet was rewritten. An update replaces the sheet and ADDS stories; it never deletes one the operator here wrote'
                skipped:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Characters this station already held and was not asked to replace, left exactly as they were'
                storiesWritten:
                    type: integer
                    minimum: 0
                    readOnly: true
                detailsWritten:
                    type: integer
                    minimum: 0
                    readOnly: true
                personas:
                    '$ref': '#/components/schemas/PersonaList'
                    readOnly: true
                    description: "The roster as it now stands, on this file's own rule: every mutation answers the whole list, because more than the named row can change"
            required: [plan, created, updated, skipped, storiesWritten, detailsWritten, personas]
            description: "What importing actually did, with the plan it did it from.\n\nAll or nothing: a file whose import failed part-way leaves the station exactly as it was, on\n`PUT /settings`' own rule. The preview is what stands between an operator and a surprise, so a\npartial landing would be the one outcome nothing had described"
        PersonaImportNotice:
            type: object
            properties:
                kind:
                    type: string
                    enum: [format, duplicate, on-air, clears, voice, soundboard, phrasing, markers]
                    readOnly: true
                    description: 'Which sort, so a console can group or ignore by it rather than parsing the sentence'
                message:
                    type: string
                    minLength: 1
                    maxLength: 500
                    readOnly: true
                    description: "The whole of it, in the station's own words, because its destination is a person"
            required: [kind, message]
            description: "Something to know before pressing Import. Not a refusal: every one of these describes a state the\nstation can be in perfectly well, and the point of saying it is that each one is otherwise\ndiscovered by putting the character on air"
        PersonaRehearsalAttempt:
            type: object
            properties:
                writer:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Which binding was asked, as `segments.writer` would record it'
                outcome:
                    type: string
                    minLength: 1
                    maxLength: 20
                    description: 'written, declined or failed. Declined is the station working; failed is something to go and fix'
                durationMs:
                    type: integer
                    minimum: 0
                    description: 'Kept for every writer rather than only a slow one: "the model got slower" can only be asked of numbers gathered before anybody suspected it'
                script:
                    type: string
                    maxLength: 5000
                    description: 'What it produced, when it produced anything usable'
                reason:
                    type: string
                    maxLength: 1000
                    description: 'Why it did not, when it did not. A sentence, because its destination is a person'
            required: [writer, outcome, durationMs]
            description: "One writer's turn at a rehearsal. Every writer asked is reported and not only the one that won: a\nmodel that declined and a floor that covered for it are two facts, and the second on its own reads\nas a station that never had a model configured"
        PersonaRehearsal:
            type: object
            properties:
                personaId:
                    type: string
                    minLength: 1
                    maxLength: 100
                previous:
                    type: string
                    minLength: 1
                    maxLength: 500
                    description: 'The invented record the break follows. Fixed, so two readings of the same sheet can be compared'
                next:
                    type: string
                    minLength: 1
                    maxLength: 500
                    description: 'The invented record it leads into'
                attempts:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaRehearsalAttempt'
                script:
                    type: string
                    maxLength: 5000
                    description: 'The words a listener would have heard, from whichever writer answered first'
                writer:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Which one that was. Present exactly when `script` is'
                reason:
                    type: string
                    maxLength: 1000
                    description: 'Why there are no words, when every writer had nothing. Not a fault: a break nothing could write is one the station does not take'
            required: [personaId, previous, next, attempts]
            description: 'What a persona says when it is asked for a break it will never air'
        PersonaAuditionRequest:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Which catalog plugin the playlist belongs to. Required alongside `playlistId`'
                playlistId:
                    type: string
                    minLength: 1
                    maxLength: 400
                stationPlaylistId:
                    type: string
                    format: uuid
                    description: 'A playlist the station owns to audition over instead. An ALTERNATIVE to `pluginId` and `playlistId`, and to `chartId`. A row the library does not hold yet is still a record the host can talk about, so it is kept'
                chartId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'A published chart to audition over instead, as `pluginId:chartId`, from its top. An ALTERNATIVE to the other sources. Its entries are never looked up at a provider, since nothing in an audition airs'
                name:
                    type: string
                    maxLength: 400
                    description: 'What the source is called, kept as a caption for the run. The console already holds it, and a run whose source is later renamed or deleted stays readable'
                limit:
                    type: integer
                    minimum: 1
                    maximum: 50
                    default: 10
                    description: 'How many breaks to write. One more record than this is taken off the source, since a break sits between two'
            required: [limit]
            description: "What an operator asks for when they put a character through a playlist or a chart. Exactly one\nsource: a provider's playlist, a playlist the station owns, or a published chart. It is READ at the\nmoment of asking and its records are stored on the run, so a list edited afterwards does not change\nwhat was measured"
        PersonaAuditionSource:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The plugin whose playlist it was. Present exactly when `playlistId` is'
                playlistId:
                    type: string
                    minLength: 1
                    maxLength: 400
                stationPlaylistId:
                    type: string
                    format: uuid
                    description: 'A playlist the station owns'
                chartId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'A published chart, as `pluginId:chartId`'
                name:
                    type: string
                    maxLength: 400
            description: "Where the records came from: exactly one of the provider's pair, `stationPlaylistId` or `chartId`.\nA snapshot of the name rather than a reference, so a source renamed or deleted afterwards leaves a\nfinished audition readable"
        PersonaAuditionRecord:
            type: object
            properties:
                title:
                    type: string
                    minLength: 1
                    maxLength: 500
                artist:
                    type: string
                    maxLength: 500
                    description: 'The lead, as it should be read'
                trackId:
                    type: string
                    maxLength: 100
                    description: 'The catalog row, when the station holds this copy. Absent for a record it has never seen'
                year:
                    type: integer
                    minimum: 0
                    maximum: 3000
                album:
                    type: string
                    maxLength: 500
                durationMs:
                    type: integer
                    minimum: 0
            required: [title, artist]
            description: 'One record, exactly as the writers were shown it'
        PersonaAuditionBreak:
            type: object
            properties:
                ordinal:
                    type: integer
                    minimum: 0
                    description: 'Which transition, from 0'
                previous:
                    '$ref': '#/components/schemas/PersonaAuditionRecord'
                    description: 'The record this break follows'
                next:
                    '$ref': '#/components/schemas/PersonaAuditionRecord'
                    description: 'The one it leads into'
                attempts:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaRehearsalAttempt'
                script:
                    type: string
                    maxLength: 5000
                    description: 'The words a listener would have heard, from whichever writer answered first'
                writer:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Which one that was. Present exactly when `script` is'
                reason:
                    type: string
                    maxLength: 1000
                    description: 'Why there are none, when every writer had nothing. On air this break is skipped'
                told:
                    type: boolean
                    description: "Whether the writer's read-back found the story this break was handed. Absent means it carried none, which is most of them. On air this is what decides whether a story in parts owes the next one, so a run is how you check the reading is right before trusting an arc to it"
            required: [ordinal, previous, next, attempts]
            description: "One transition, and everything the writers said about it. Every writer asked is reported and not\nonly the one that won, on the rehearsal's own argument: a model that declined and a floor that\ncovered for it are two facts"
        PersonaAuditionSummary:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                personaId:
                    type: string
                    minLength: 1
                    maxLength: 100
                personaKey:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: "The character's own key, as `script_history` records it"
                source:
                    '$ref': '#/components/schemas/PersonaAuditionSource'
                state:
                    type: string
                    enum: [queued, running, done, failed, cancelled]
                    description: '`cancelled` keeps whatever breaks were already written'
                transitions:
                    type: integer
                    minimum: 0
                    description: 'How many breaks this run writes in total'
                written:
                    type: integer
                    minimum: 0
                    description: 'How many it has written so far, which is how far along it is'
                error:
                    type: string
                    maxLength: 2000
                    description: 'Why writing it stopped, when it did'
                cancelledAt:
                    type: string
                    maxLength: 40
                    description: ISO-8601
                finishedAt:
                    type: string
                    maxLength: 40
                    description: 'ISO-8601, whichever way the run ended'
                createdAt:
                    type: string
                    minLength: 1
                    maxLength: 40
                    description: ISO-8601
            required: [id, personaId, personaKey, source, state, transitions, written, createdAt]
            description: 'A run of one character over one playlist, without its breaks: what a list draws'
        PersonaAudition:
            allOf:
                - '$ref': '#/components/schemas/PersonaAuditionSummary'
                - type: object
                  properties:
                      breaks:
                          type: array
                          items:
                              '$ref': '#/components/schemas/PersonaAuditionBreak'
                  required: [breaks]
        PersonaAuditionList:
            type: object
            properties:
                auditions:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaAuditionSummary'
            required: [auditions]
        PersonaTelling:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                storyId:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                title:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                    description: 'The handle of the story this told, so a timeline reads as something rather than as ids'
                source:
                    type: string
                    enum: [break, production, backfill]
                    readOnly: true
                    description: 'What wrote it. `backfill` is the rows migration 0034 reconstructed from the two columns it replaced'
                mode:
                    type: string
                    enum: [offered, told]
                    readOnly: true
                    description: 'Whether the story was handed over as something the writer MAY use, or as the thing the break was for'
                told:
                    type: boolean
                    readOnly: true
                    description: 'Whether it actually went out, as the WRITER read its own answer back. An offered story may simply be ignored'
                said:
                    type: string
                    maxLength: 2000
                    readOnly: true
                    description: 'The words that carried it, kept here because the script history they came from is swept nightly'
                segmentId:
                    type: string
                    maxLength: 100
                    readOnly: true
                    description: 'The break that carried it, while that row still exists'
                airedAt:
                    type: string
                    maxLength: 40
                    readOnly: true
                    description: 'When a listener could first have heard it. Absent means written but not yet aired, or never aired at all'
                at:
                    type: string
                    minLength: 1
                    maxLength: 40
                    readOnly: true
                    description: 'When it was written. Hand this back as `to` to roll back to just before it'
            required: [id, storyId, title, source, mode, told, at]
            description: "One time a character actually told one of its own stories. What the timeline lists, and what a\nrollback is chosen from: the moment on each row is the exact string the station compares against,\nnot a rounding of it"
        PersonaMemoryTimeline:
            type: object
            properties:
                personaId:
                    type: string
                    minLength: 1
                    maxLength: 100
                tellings:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaTelling'
            required: [personaId, tellings]
            description: 'What one character has told, newest first'
        PersonaMemoryChange:
            type: object
            properties:
                tellings:
                    type: integer
                    minimum: 0
                    description: 'Tellings forgotten. Every one, whatever wrote it: a telling is a record of something the station did rather than a claim somebody made'
                notes:
                    type: integer
                    minimum: 0
                    description: 'Notes the distil pass wrote. Nothing an operator typed is ever counted here or deleted'
                stories:
                    type: integer
                    minimum: 0
                    description: 'Stories the enrichment pass proposed'
                details:
                    type: integer
                    minimum: 0
                    description: 'Details it proposed. A floor rather than a total: a story that is itself going takes every detail hung on it'
                rejected:
                    type: integer
                    minimum: 0
                    description: 'How many of the above were proposals somebody turned down. Deleting one lets the nightly pass offer it again'
                touched:
                    type: integer
                    minimum: 0
                    description: 'How many the operator had since accepted or edited. They still go, and this is the one loss they did not cause'
            required: [tellings, notes, stories, details, rejected, touched]
            description: "What a rollback would undo, or did. Counted with the same predicates the delete uses, so a preview\ncannot promise one thing and do another"
        PersonaMemoryRollback:
            type: object
            properties:
                to:
                    type: string
                    maxLength: 40
                    description: 'The moment to go back to, as a timeline row reports it. Absent means all of it, which is a reset'
                relearn:
                    type: boolean
                    description: "Also drag the distil pass's watermark back, so it reads that window again. Right for testing and wrong for undoing a character that drifted, so it is asked for rather than assumed"
            description: 'Undo what this character accumulated on its own'
        PersonaMemory:
            type: object
            properties:
                personaId:
                    type: string
                    minLength: 1
                    maxLength: 100
                undone:
                    '$ref': '#/components/schemas/PersonaMemoryChange'
                tellings:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PersonaTelling'
            required: [personaId, undone, tellings]
            description: 'What was undone, and where the timeline stands now'
        PlaylistPermission:
            type: string
            enum: [read, edit]
            description: "An action a source will permit on one playlist's items. Item-scoped: neither value covers the playlist's own name or description"
        CatalogPlaylist:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                pluginName:
                    type: string
                    minLength: 1
                    maxLength: 200
                id:
                    type: string
                    minLength: 1
                    maxLength: 400
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                description:
                    type: string
                    maxLength: 2000
                trackCount:
                    type: integer
                    minimum: 0
                artworkUrl:
                    type: string
                    maxLength: 2000
                permissions:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PlaylistPermission'
                    description: "What the SOURCE permits on this playlist's items, not what this actor may do. Empty means the source permits nothing; absent means it did not say"
                madeByProvider:
                    type: boolean
                    description: 'The source made this playlist itself rather than a person: an editorial list, or one generated for the account like Discover Weekly. Absent when it did not say'
                hidden:
                    type: boolean
                    description: 'An operator hid this playlist from this station, so pickers leave it out and the library sync does not read it. Absent when it is not hidden'
            required: [pluginId, pluginName, id, name]
            description: 'A playlist a catalog-capable plugin offers, tagged with the plugin it came from so an aggregated list is addressable'
        CatalogTrack:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: "The PROVIDER's id for this copy, which is what an import names it by. Never a `deadair.tracks` id"
                title:
                    type: string
                    minLength: 1
                    maxLength: 400
                artists:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                    description: 'Ordered, primary artist first. Empty array if the provider genuinely has none'
                album:
                    type: string
                    maxLength: 400
                durationMs:
                    type: integer
                    minimum: 0
                isrc:
                    type: string
                    maxLength: 100
                artworkUrl:
                    type: string
                    maxLength: 2000
                trackId:
                    type: string
                    maxLength: 100
                    description: 'The canonical `deadair.tracks` row this copy is bound to, when the catalog holds one'
                artistId:
                    type: string
                    maxLength: 100
                    description: 'The canonical artist behind that row'
                albumId:
                    type: string
                    maxLength: 100
                    description: 'The release that row was ingested inside. Absent for a single ingested outside any'
            required: [id, title, artists]
            description: "One record as its PROVIDER describes it, plus what the catalog can say about the same copy.\n\nThe first half mirrors the plugin SDK's `ProviderTrack` and stays the provider's answer: this is a\nlisting of what a playlist holds, not of what the station has ingested. The three ids below are the\nstation's own and are absent for anything it has never seen, which on most playlists is plenty of\nrows — a playlist is a provider's list and the library is what a sync has walked"
        CatalogSourceError:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                pluginName:
                    type: string
                    minLength: 1
                    maxLength: 200
                message:
                    type: string
                    maxLength: 4000
            required: [pluginId, pluginName, message]
            description: 'One catalog-capable plugin that could not be listed'
        CatalogPlaylistSource:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                pluginName:
                    type: string
                    minLength: 1
                    maxLength: 200
                listedAt:
                    type: string
                    format: date-time
                    description: "When the station last read this source's whole list of playlists. The library sync reads it in the background, so this is usually minutes old; a source listed for the first time is read for this answer"
            required: [pluginId, pluginName, listedAt]
            description: 'One music source whose playlists are in this answer, and how old its list is'
        CatalogPlaylistPage:
            type: object
            properties:
                playlists:
                    type: array
                    items:
                        '$ref': '#/components/schemas/CatalogPlaylist'
                sources:
                    type: array
                    items:
                        '$ref': '#/components/schemas/CatalogPlaylistSource'
                    description: 'Every source whose playlists are listed, including one that also has an entry in `errors`: its list is then the last one the station read. Absent from a station that predates it, which asked every source live'
                errors:
                    type: array
                    items:
                        '$ref': '#/components/schemas/CatalogSourceError'
            required: [playlists, errors]
        CatalogPlaylistTracks:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                playlistId:
                    type: string
                    minLength: 1
                    maxLength: 400
                tracks:
                    type: array
                    items:
                        '$ref': '#/components/schemas/CatalogTrack'
            required: [pluginId, playlistId, tracks]
        StationPlaylist:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                prompt:
                    type: string
                    maxLength: 4000
                    description: "What this playlist is for, in the operator's own words. Empty when nobody said"
                originPluginId:
                    type: string
                    maxLength: 200
                    readOnly: true
                    description: 'The plugin this was cloned from, for a badge and nothing else. Absent for one read from a file or made here'
                trackCount:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Every row, placeholders included'
                resolvedCount:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'The rows that name a record in the library, which are the ones that can air'
                createdAt:
                    type: string
                    format: date-time
                    readOnly: true
                updatedAt:
                    type: string
                    format: date-time
                    readOnly: true
            required: [id, name, prompt, trackCount, resolvedCount, createdAt, updatedAt]
            description: "A playlist the station owns: records it holds in its own library, in an order somebody chose, cloned\nfrom somewhere else and free to differ from it afterwards"
        StationPlaylistList:
            type: object
            properties:
                playlists:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationPlaylist'
            required: [playlists]
        StationPlaylistTrack:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: "The row's own id, not the record's"
                position:
                    type: integer
                    minimum: 0
                title:
                    type: string
                    minLength: 1
                    maxLength: 400
                artists:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                    description: 'Ordered, primary artist first'
                album:
                    type: string
                    maxLength: 400
                durationMs:
                    type: integer
                    minimum: 0
                trackId:
                    type: string
                    maxLength: 100
                    description: 'The library record this row plays. Absent on a placeholder'
                artistId:
                    type: string
                    maxLength: 100
                albumId:
                    type: string
                    maxLength: 100
                originPluginId:
                    type: string
                    maxLength: 200
                    description: 'On a placeholder, the plugin whose copy it was cloned from. Absent on one read from a file, which names a record and no copy of it'
            required: [id, position, title, artists]
            description: 'One row of a station playlist: a record in the library, or a placeholder for one it does not hold yet'
        StationPlaylistDetail:
            allOf:
                - '$ref': '#/components/schemas/StationPlaylist'
                - type: object
                  properties:
                      tracks:
                          type: array
                          items:
                              '$ref': '#/components/schemas/StationPlaylistTrack'
                  required: [tracks]
        StationPlaylistUpdate:
            type: object
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                prompt:
                    type: string
                    maxLength: 4000
            description: 'What may change about a station playlist after it exists. Absent fields are left alone'
        PlaylistFileOrigin:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                externalId:
                    type: string
                    minLength: 1
                    maxLength: 400
            required: [pluginId, externalId]
            description: "Where a record in a file came from, when it came from a provider's copy. Carried so a record the\nreceiving library does not hold can still be matched by that copy later"
        PlaylistFileTrack:
            type: object
            properties:
                title:
                    type: string
                    minLength: 1
                    maxLength: 400
                artists:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                    description: 'Ordered, primary artist first'
                album:
                    type: string
                    maxLength: 400
                durationMs:
                    type: integer
                    minimum: 0
                isrc:
                    type: string
                    maxLength: 100
                origin:
                    '$ref': '#/components/schemas/PlaylistFileOrigin'
            required: [title, artists]
            description: "One record as a playlist file names it. By its words and its ISRC, never by an id of this station's:\nids are minted afresh by every library, so a file keyed by them would restore onto nothing"
        PlaylistFile:
            type: object
            properties:
                format:
                    type: string
                    minLength: 1
                    maxLength: 50
                    description: 'What shape this is, so a file from a later build says so rather than being read wrongly'
                takenAt:
                    type: string
                    minLength: 1
                    maxLength: 40
                    description: 'When it was exported, ISO-8601'
                station:
                    type: string
                    maxLength: 100
                    description: 'The station it was taken from. Provenance only'
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                prompt:
                    type: string
                    maxLength: 4000
                tracks:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PlaylistFileTrack'
            required: [format, takenAt, name, tracks]
            description: 'A playlist as a file: everything somebody would need to rebuild it on another station'
        PlaylistProviderRef:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                playlistId:
                    type: string
                    minLength: 1
                    maxLength: 400
            required: [pluginId, playlistId]
            description: "A playlist one of the station's music sources holds, named the way the playlists listing names it"
        PlaylistImportInput:
            type: object
            properties:
                file:
                    '$ref': '#/components/schemas/PlaylistFile'
                    description: 'A playlist exported from a deadair station'
                text:
                    type: string
                    minLength: 1
                    maxLength: 4000000
                    description: 'A playlist another program wrote, as its text: an M3U, a CSV with a header row, or one `Artist - Title` per line'
                format:
                    type: string
                    enum: [m3u, csv, text]
                    description: 'Which of those `text` is. Absent works it out from the text'
                fileName:
                    type: string
                    maxLength: 400
                    description: 'The name of the file `text` came from, which names the playlist when the text does not'
                url:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: "A link to a playlist at one of the station's music sources, as a browser or an app shows it"
                providerPlaylist:
                    '$ref': '#/components/schemas/PlaylistProviderRef'
                    description: 'A playlist a music source lists here, by its plugin and its id'
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What to call the new playlist. Absent keeps the name the source gives it'
            description: 'Something to import a playlist from. Exactly one source'
        PlaylistImportEntry:
            type: object
            properties:
                position:
                    type: integer
                    minimum: 0
                title:
                    type: string
                    minLength: 1
                    maxLength: 400
                artists:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                outcome:
                    type: string
                    enum: [matched, toAdd, toLookUp]
                    description: "`matched`: the library holds it. `toAdd`: it names a provider's copy, which the station can add to its library. `toLookUp`: it names only a record, which the station has to search its providers for"
                trackId:
                    type: string
                    maxLength: 100
                    description: 'The library record a `matched` row plays'
            required: [position, title, artists, outcome]
            description: 'What importing one record would do here'
        PlaylistImportPlan:
            type: object
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                matched:
                    type: integer
                    minimum: 0
                toAdd:
                    type: integer
                    minimum: 0
                toLookUp:
                    type: integer
                    minimum: 0
                skipped:
                    type: integer
                    minimum: 0
                    description: 'Lines of the source that named no record the station could read'
                entries:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PlaylistImportEntry'
                notices:
                    type: array
                    items:
                        type: string
                        maxLength: 1000
                    description: 'Anything about the source as a whole an operator should know before importing it'
            required: [name, matched, toAdd, toLookUp, skipped, entries, notices]
            description: 'What an import WOULD do, written nowhere'
        PlaylistImportResult:
            type: object
            properties:
                plan:
                    '$ref': '#/components/schemas/PlaylistImportPlan'
                playlist:
                    '$ref': '#/components/schemas/StationPlaylist'
            required: [plan, playlist]
        PlayoutPlaylistInput:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                playlistId:
                    type: string
                    minLength: 1
                    maxLength: 400
                mixInSimilar:
                    type: boolean
                    description: "Whether records that sound like the ones on this playlist are mixed in among them, one every `rotation.mixInEvery` records. The playlist still plays in full and in its own order around them. Absent takes the station's own setting, which is off"
                callins:
                    type: boolean
                    description: 'Whether somebody phones in during this broadcast, exactly as `PutOnAirInput.callins`. Absent is no calls: there is no station-wide default behind it'
            required: [pluginId, playlistId]
            description: 'The plugin playlist to load into the running order'
        PlayoutStationPlaylistInput:
            type: object
            properties:
                stationPlaylistId:
                    type: string
                    format: uuid
                mixInSimilar:
                    type: boolean
                    description: "Whether records that sound like the ones on this playlist are mixed in among them, one every `rotation.mixInEvery` records. Absent takes the station's own setting, which is off"
                callins:
                    type: boolean
                    description: 'Whether somebody phones in during this broadcast, exactly as `PutOnAirInput.callins`. Absent is no calls: there is no station-wide default behind it'
            required: [stationPlaylistId]
            description: 'A playlist the station owns, to load into the running order'
        PlayoutAlbumInput:
            type: object
            properties:
                albumId:
                    type: string
                    format: uuid
            required: [albumId]
            description: 'An album the library holds, to play whole'
        PlayoutChartInput:
            type: object
            properties:
                chartId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'As `pluginId:chartId`, which is how `GET /charts` lists them'
                chartOrder:
                    type: string
                    enum: [countdown, ranked, unordered]
                    description: 'Which way round to play it. Absent is `countdown`, which opens on the lowest rank and ends on number one'
                chartPositions:
                    type: boolean
                    description: 'Whether the host says where the chart placed each record it named: "number seven on the Hot 100". Absent is yes. Set it false to air a chart without its positions read out. A record no chart named has no position to say whatever this says'
                callins:
                    type: boolean
                    description: 'Whether somebody phones in during this broadcast, exactly as `PutOnAirInput.callins`. Absent is no calls: there is no station-wide default behind it'
            required: [chartId]
            description: 'The published chart to build the running order from'
        PlayoutItem:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: "deadair's own id for this item, not the provider's: a playlist may hold the same track twice"
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                externalId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: "The track's id in its plugin's id space"
                title:
                    type: string
                    minLength: 1
                    maxLength: 400
                artists:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                durationMs:
                    type: integer
                    minimum: 0
                    description: 'Integer milliseconds. Deliberately not the `duration` scalar, which is a Luxon `Duration` over an ISO-8601 string'
                album:
                    type: string
                    maxLength: 400
                artworkUrl:
                    type: string
                    maxLength: 2000
                    description: "The station's own cover, as a path under the API root. Never a provider's URL"
                year:
                    type: integer
                    minimum: 0
                    description: 'First release year, when the catalog knows one'
                trackId:
                    type: string
                    maxLength: 100
                    description: 'The canonical `deadair.tracks` id, when this item is a track the catalog holds. Absent for anything the catalog has never seen'
            required: [id, pluginId, externalId, title, artists]
            description: 'One item in the running order, as the console sees it'
        PlayoutNowPlaying:
            type: object
            properties:
                item:
                    '$ref': '#/components/schemas/PlayoutItem'
                startedAt:
                    type: integer
                    minimum: 0
                    description: 'Unix epoch millis, as observed when the player reported it'
                remainingMs:
                    type: integer
                    minimum: 0
                    description: "The decoder's own countdown, absent when it cannot say. It leads the listener by the encoder and client buffers"
            required: [item, startedAt]
            description: 'What the PLAYER says is airing, which is not the same as what was last handed to it'
        StreamConfigWarning:
            type: object
            properties:
                container:
                    type: string
                    enum: [icecast, liquidsoap]
                    description: 'Which one is behind'
                detail:
                    type: string
                    minLength: 1
                    maxLength: 1000
                    description: 'What is wrong and how it is known, in a sentence'
                restart:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The exact command that adopts the new config, which is the only thing that does'
            required: [container, detail, restart]
            description: "A stream container still running config the app has replaced. Icecast and Liquidsoap read\ntheir rendered config ONCE, at startup, and nothing restarts or signals them when it is\nre-rendered — so a reseeded secret leaves a process holding credentials that match nothing,\nand the symptom names something else entirely (every listener refused, or no mount at all).\nThe app cannot restart a sibling container and should not be able to, so it reports."
        SilenceCause:
            type: string
            enum:
                - airing
                - transportStalled
                - controlDenied
                - streamUnreachable
                - configNotAdopted
                - stoodDown
                - noProgramme
                - noAudience
                - warmingUp
                - waitingOnAudio
                - notDriving
                - starved
            description: "Which gate is keeping the station quiet, or `airing` when none of them is. Ordered by cause: a\nstalled transport loop makes every reading under it stale, so it is ruled out first"
        SilenceState:
            type: string
            enum: [ok, waiting, fault]
            description: "How one gate is doing. `waiting` is its own state rather than a mild fault, because a station\nidling for want of a listener and a station that cannot reach its stream are both silent and only\none of them is something to go and fix"
        SilenceCheck:
            type: object
            properties:
                code:
                    '$ref': '#/components/schemas/SilenceCause'
                    description: 'Never `airing`, which is the absence of a blocking gate rather than a gate'
                state:
                    '$ref': '#/components/schemas/SilenceState'
                detail:
                    type: string
                    minLength: 1
                    maxLength: 1000
                    description: 'What this gate is doing right now, whether or not it is the one blocking'
                remedy:
                    type: string
                    maxLength: 500
                    description: 'What would clear it, where there is something an operator can actually do'
            required: [code, state, detail]
            description: "One gate's answer about itself"
        StationSilence:
            type: object
            properties:
                audible:
                    type: boolean
                    description: 'Whether the station believes its programme is reaching the mount. NOT whether anybody is hearing it: a station can be audible with no listeners in `always` mode, and can have listeners while airing the local bed'
                cause:
                    '$ref': '#/components/schemas/SilenceCause'
                detail:
                    type: string
                    minLength: 1
                    maxLength: 1000
                remedy:
                    type: string
                    maxLength: 500
                checks:
                    type: array
                    items:
                        '$ref': '#/components/schemas/SilenceCheck'
                    description: 'Every gate, in the order they are judged, so a console can say what it ruled out. A `configNotAdopted` fault appears here and is never the cause, because a station can air perfectly well while it is true'
            required: [audible, cause, detail, checks]
            description: 'Why the station cannot be heard, as one answer'
        PlayoutMount:
            type: object
            properties:
                format:
                    type: string
                    enum: [mp3, opus, aac, flac]
                path:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Same-origin path, on the same terms as `PlayoutStatus.mountPath`'
                bitrateKbps:
                    type: integer
                    minimum: 1
                    description: 'Absent for FLAC, which is lossless and has no rate to set'
            required: [format, path]
            description: 'One mount the station is publishing right now'
        PlayoutStatus:
            type: object
            properties:
                streamUp:
                    type: boolean
                    description: "Whether Liquidsoap's control API is answering at all. False means nothing can air, whatever the running order holds"
                onAir:
                    type: boolean
                    description: 'Whether the station is actually broadcasting. deadair holds the mount on a lease it renews only while it has a programme, so a reachable stream with nothing to play is up and NOT on air: it is connected, and airing silence'
                mountPath:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Same-origin path of the Icecast MP3 mount, which is always published and is the one a console names when it can only name one. A path rather than a URL: the browser reaches Icecast through whatever edge served the SPA, never at the address the app itself uses'
                mounts:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PlayoutMount'
                    description: 'Every mount being published, MP3 first, so a console can offer the others rather than implying the station is only on one. Never empty: MP3 has no switch. A format the operator has not switched on is absent rather than present and disabled, because every consumer of this wants the mounts that are actually there'
                nowPlaying:
                    '$ref': '#/components/schemas/PlayoutNowPlaying'
                upNext:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PlayoutItem'
                    description: 'Waiting here, in order. Excludes what the player already holds'
                queuedCount:
                    type: integer
                    minimum: 0
                    description: 'How many items are waiting in total, of which `upNext` is the head'
                listeners:
                    type: integer
                    minimum: 0
                    description: 'How many clients Icecast has attached to the mount. Zero both for "nobody is listening" and for an Icecast that is not answering, which `audience` is where to tell apart'
                audience:
                    type: boolean
                    description: 'Whether the station counts as having an audience, which lingers for a minute past the last listener so a reconnecting player does not cut the broadcast'
                staleStreamConfig:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StreamConfigWarning'
                    description: 'Containers running config the app has since replaced. Empty is the ordinary state, and so is empty for anything the app has no evidence about: a warning here has never been a guess'
                silence:
                    '$ref': '#/components/schemas/StationSilence'
                    description: 'Which gate is keeping the station quiet, composed from every one of them rather than inferred from the fields above. `streamUp`, `onAir`, `audience` and `queuedCount` each answer for one gate and a console reading them alone has to guess at the rest'
                live:
                    '$ref': '#/components/schemas/PlayoutLive'
                    description: "The live input, where a presenter's encoder takes the air from the station. Absent when the audio chain has not said, which is a stream that is not answering or one too old to have the input"
            required:
                - streamUp
                - onAir
                - mountPath
                - mounts
                - upNext
                - queuedCount
                - listeners
                - audience
                - staleStreamConfig
                - silence
            description: "The station's transport, as one reading"
        LiveState:
            type: string
            enum: ['off', armed, preroll, onair]
            description: "What the live input is doing. `off`: not armed, whatever is connected to it. `armed`: waiting for real signal from an encoder. `preroll`: signal heard, counting down to the cut. `onair`: the presenter is on the air, above the station's own programme"
        PlayoutLive:
            type: object
            properties:
                state:
                    '$ref': '#/components/schemas/LiveState'
                inMs:
                    type: integer
                    minimum: 0
                    description: 'While `preroll`, how long until the presenter is on the air. What a countdown is drawn from'
                forMs:
                    type: integer
                    minimum: 0
                    description: 'While `onair`, how long the presenter has been on'
            required: [state]
            description: 'The live input, as the audio chain last reported it'
        PlayoutLiveArmInput:
            type: object
            properties:
                title:
                    type: string
                    maxLength: 200
                    description: "What the stream says is on while the presenter is on the air. Left out, it says the station's name"
            description: 'Arming the live input'
        LiveConnection:
            type: object
            properties:
                port:
                    type: integer
                    minimum: 1
                    maximum: 65535
                    description: "The port the station's container publishes for it, as the station sees it. Mapped to another on the host, the encoder uses that one"
                mount:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'The mount to push to'
                user:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'The user name to send. The input accepts any; this is the one encoders default to'
                password:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "The input's password, which the station generated when it was first set up"
            required: [port, mount, user, password]
            description: "What a presenter's encoder needs to connect to the live input. Carries the input's password"
        PlayoutSkipQuery:
            type: object
            properties:
                item:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'The id of the item on air as the caller last saw it (`PlayoutStatus.nowPlaying.item.id`). When it is no longer on air the skip is refused with a 409 and nothing is cut, so a press meant for a record that has just ended never takes off the one after it. Left out, the skip cuts whatever is on air when it arrives'
            description: 'Which item a skip means to cut, as the caller last saw it on air'
        PluginStatus:
            type: string
            enum: [discovered, disabled, misconfigured, active, failed]
            description: 'Lifecycle state of a plugin the host knows about'
        PluginOrigin:
            type: string
            enum: [bundled, installed]
            description: "Where the station found a plugin: shipped inside the image, or installed by the operator into the plugins\ndirectory on the data volume. Says nothing about trust; both kinds run inside the station with its privileges"
        ConfigFieldType:
            type: string
            enum: [string, text, url, secret, number, boolean, select, multiselect, list, note]
        ConfigFieldUnit:
            type: string
            enum: [bytes, fraction]
            description: "What a `number` field's value is measured in. The stored value is always in this unit; only the\ncontrol the operator touches changes, so a byte count stays a byte count everywhere it is read and\na `fraction` stays the share between 0 and 1 that the code multiplying by it wants"
        ConfigFieldControl:
            type: string
            enum: [slider, tags]
            description: "The control a field asks to be drawn with, where the ordinary one for its type reads badly. Opt-in\nper field rather than inferred, because a slider is right for a value you feel for and wrong for\none you have to hit exactly, and `tags` is right for a comma-separated line that is really a SET\nand wrong for one that is prose. Nothing about the stored value changes either way"
        ConfigFieldOption:
            type: object
            properties:
                value:
                    type: string
                    minLength: 1
                    maxLength: 200
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
            required: [value, label]
            description: 'One choice of a `select` config field'
        ConfigFieldOptionSource:
            type: string
            enum:
                - station.newsCategories
                - station.newsFeeds
                - station.podcastShows
                - station.narrationSeries
                - station.ownShows
                - intl.timeZones
                - plugins.speech
                - plugins.llm
                - plugins.mixer
                - plugins.analysis
                - plugins.similarity
                - llm.models
            description: "Where a field's or a column's choices come from when only the console can enumerate them: the\nstation's own tables, the platform's zone list, the enabled plugins that can do one of five jobs,\nor the models the selected model plugin currently offers. Resolved by the console either way"
        ConfigFieldColumn:
            type: object
            properties:
                key:
                    type: string
                    minLength: 1
                    maxLength: 200
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                type:
                    type: string
                    enum: [string, url, select, secret]
                required:
                    type: boolean
                placeholder:
                    type: string
                    maxLength: 400
                options:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ConfigFieldOption'
                optionsFrom:
                    '$ref': '#/components/schemas/ConfigFieldOptionSource'
                dependsOn:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "Key of another column in the same list. This cell applies only to a row whose cell there holds one of `dependsOnValues`. Stronger than a field's `dependsOn`, which only hides a control: a cell that does not apply is neither sent by the console nor read by the host, so a `url` column that does not apply to a row contributes no hostname to the plugin's allowlist. A target this list does not declare, or a target cell still empty, shows the cell"
                dependsOnValues:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                    description: 'The values of the `dependsOn` cell this one applies to. Omitted means any non-empty value; ignored without a target'
                sentTo:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "`secret` only: key of the address column in the same list this credential is sent to. A save that keeps the stored credential while that row's address moves to another origin is refused"
                multiline:
                    type: boolean
                    description: '`secret` only: line breaks are part of this credential, so a save keeps them while it strips every other control character'
            required: [key, label, type]
            description: "One column of a `list` field. Every ordinary cell is stored as a string in the row, so this describes the\ncontrol rather than the value; a `secret` cell is encrypted on its own and is never in the row at all"
        ConfigFieldPreset:
            type: object
            properties:
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What the operator picks it by'
                cells:
                    type: object
                    additionalProperties:
                        type: string
                        maxLength: 2000
                    description: "Cell values by column key. A key with no column, or a `secret` column's, is ignored"
            required: [label, cells]
            description: 'A row a `list` field offers to start from instead of an empty one. Adding a row from it fills the cells it names, by column key, and nothing records which preset a row came from'
        ConfigFieldDescriptor:
            type: object
            properties:
                key:
                    type: string
                    minLength: 1
                    maxLength: 200
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                type:
                    '$ref': '#/components/schemas/ConfigFieldType'
                required:
                    type: boolean
                default:
                    oneOf:
                        - type: string
                        - type: number
                        - type: boolean
                unit:
                    '$ref': '#/components/schemas/ConfigFieldUnit'
                    description: '`number` only, and ignored elsewhere'
                control:
                    '$ref': '#/components/schemas/ConfigFieldControl'
                    description: '`slider` for a `number` with both `min` and `max`, `tags` for a `string` holding a comma-separated set'
                step:
                    type: number
                    description: "How coarsely a `control` moves, in the field's own unit. Ignored without one, and defaults to 1"
                min:
                    type: number
                    description: '`number` only: the smallest value that will be accepted, inclusive'
                max:
                    type: number
                    description: '`number` only: the largest value that will be accepted, inclusive'
                placeholder:
                    type: string
                    maxLength: 400
                help:
                    type: string
                    maxLength: 2000
                options:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ConfigFieldOption'
                optionsFrom:
                    '$ref': '#/components/schemas/ConfigFieldOptionSource'
                    description: "Choices only the console can enumerate. Merged where a plugin's own suggestions are, and outranked by them"
                columns:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ConfigFieldColumn'
                    description: '`list` only, and ignored elsewhere'
                presets:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ConfigFieldPreset'
                    description: '`list` only: rows the Add button offers to start from, beside an empty one'
                dependsOn:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Key of the field this one is only relevant to'
                rangeWith:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Key of the `number` field that is the upper end of the range this one opens, declared on the lower end only. Still two settings, each validated by name; the console draws them as one control whose handles cannot cross'
                sentTo:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: '`secret` only: key of the address field this credential is sent to. A save that keeps the stored credential while that address moves to another origin is refused'
                multiline:
                    type: boolean
                    description: '`secret` only: line breaks are part of this credential, so a save keeps them while it strips every other control character'
            required: [key, label, type]
            description: "Mirrors the plugin SDK's `ConfigField`: enough for a console to render the settings form with no per-plugin code"
        PluginSummary:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 200
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                version:
                    type: string
                    minLength: 1
                    maxLength: 100
                capabilities:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 100
                usesTrackFetcher:
                    type: boolean
                    description: "Whether the manifest declares the `trackFetcher` permission, so its records reach air through the station's own track fetcher and that fetcher needs its own authorization. Not the same as the `stream` capability, which a plugin that mints its own stream URLs declares too. Absent means it does not"
                status:
                    '$ref': '#/components/schemas/PluginStatus'
                origin:
                    '$ref': '#/components/schemas/PluginOrigin'
                enabled:
                    type: boolean
                description:
                    type: string
                    maxLength: 2000
                icon:
                    type: string
                    maxLength: 2000
                configFields:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ConfigFieldDescriptor'
                secretsConfigured:
                    type: object
                    additionalProperties:
                        type: boolean
                    description: 'Whether a value is currently stored, per `secret` field under its own key and per `secret` cell under `field/rowId/column`. Never the value itself'
                firstEnabledAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When this plugin was first ever enabled. Absent means it never has been, so the console asks before it is'
                lastError:
                    type: string
                    maxLength: 4000
                    description: 'The last recorded failure. Absent means it is not currently unhappy'
                nextProbeAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When the breaker will probe this plugin again on its own. Absent means no probe is pending'
            required:
                - id
                - name
                - version
                - capabilities
                - status
                - origin
                - enabled
                - configFields
                - secretsConfigured
            description: 'A plugin as the settings list sees it. Carries no configured VALUES, only which secrets are set'
        ProviderMode:
            type: string
            enum: [one, ordered]
            description: "Whether a capability has ONE answer or is asked of everything in turn. `one` stores a plugin id\nand `ordered` stores a list of them; see `plugins/plugin.providers.ts`, which both this and the\nstation read the pairing from"
        ProviderCandidate:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "The plugin's own name, which is what an operator knows it by. The id is what is stored"
                enabled:
                    type: boolean
                status:
                    '$ref': '#/components/schemas/PluginStatus'
                position:
                    type: integer
                    minimum: 1
                    description: 'Where in the asking order this plugin sits, counting from 1. Absent when it cannot currently answer, which is every status but `active`'
                listed:
                    type: boolean
                    description: 'Whether the operator named this plugin, as opposed to it being here because it is installed. False everywhere when nothing is set'
                inUse:
                    type: boolean
                    description: 'Whether the station reaches this plugin for this capability. Every active candidate for an `ordered` capability, and only the chosen one for a `one`'
                declaredPriority:
                    type: integer
                    description: "`enrichment` only: the number the plugin's AUTHOR gave it, which orders whatever the operator did not. Lower wins a conflicting fact"
            required: [pluginId, name, enabled, status, listed, inUse]
            description: "One plugin's standing for one capability, as the Providers section draws it"
        ProviderCapabilityState:
            type: object
            properties:
                capability:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: "The manifest capability, which is also the console's anchor for this block"
                mode:
                    '$ref': '#/components/schemas/ProviderMode'
                settingKey:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The `deadair.settings` key the console writes. Its descriptor carries the wording'
                configured:
                    type: string
                    maxLength: 8000
                    description: 'The raw stored value, so the console can tell a default order from one somebody set. Empty when nothing is stored'
                candidates:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ProviderCandidate'
                    description: 'Active plugins first, in the order the station asks them, then the ones that cannot answer'
                stale:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                    description: 'Ids named in the setting that no active plugin answers to. Ordering never gates, so these cost nothing but say nothing either until they are shown'
                unanswered:
                    type: boolean
                    description: '`one` only: a plugin is named and is not an active candidate, so the station has NO provider for this. The dangerous state, because naming one is an instruction and never falls back'
            required: [capability, mode, settingKey, configured, candidates, stale, unanswered]
            description: 'One capability, who can answer it, and what the operator has said about the order'
        ProviderCatalogue:
            type: object
            properties:
                capabilities:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ProviderCapabilityState'
            required: [capabilities]
            description: "Every capability an operator chooses between. Capabilities that fan out and merge without\nranking are deliberately absent: order changes nothing about a union"
        PluginImport:
            type: object
            properties:
                file:
                    type: string
                    format: binary
                    description: 'The gzip tarball npm pack writes: every entry under package/, holding package.json and the built code, at most 64 MB'
            required: [file]
            description: "A plugin handed over from the browser. The generated client types the body as `FormData`, so\nnothing checks this shape. It says what to send"
        PluginImportResult:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The id the imported plugin claimed'
                restartRequired:
                    type: boolean
                    description: 'The same version was already loaded, so the station runs the build it had until it restarts. False for a new plugin and for a new version'
                plugins:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PluginSummary'
                    description: 'Every plugin, as the catalogue now stands. An import can take an older version away as well as add one'
            required: [pluginId, restartRequired, plugins]
            description: 'What an import did'
        PluginLogLevel:
            type: string
            enum: [debug, info, warn, error]
        PluginLogEntry:
            type: object
            properties:
                ts:
                    type: string
                    maxLength: 40
                level:
                    '$ref': '#/components/schemas/PluginLogLevel'
                text:
                    type: string
                    maxLength: 65536
                    description: 'Must match MAX_LINE_BYTES_CEILING in apps/api/src/logging/rotating.log.store.ts. Change both together'
            required: [ts, level, text]
        PluginLogPage:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                level:
                    '$ref': '#/components/schemas/PluginLogLevel'
                entries:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PluginLogEntry'
                    description: 'Newest first, as the activity feed and the script history send. The download is the file as written, oldest first'
            required: [pluginId, level, entries]
        PluginLogQuery:
            type: object
            properties:
                limit:
                    type: integer
                    minimum: 1
                    maximum: 2000
                level:
                    '$ref': '#/components/schemas/PluginLogLevel'
        PluginLogLevelInput:
            type: object
            properties:
                level:
                    '$ref': '#/components/schemas/PluginLogLevel'
            required: [level]
        PluginDetail:
            allOf:
                - '$ref': '#/components/schemas/PluginSummary'
                - type: object
                  properties:
                      dir:
                          type: string
                          minLength: 1
                          maxLength: 4096
                          description: "Absolute path of the plugin's directory on the station"
                      config:
                          type: object
                          additionalProperties: {}
                      oauthConnected:
                          type: boolean
                      logLevel:
                          '$ref': '#/components/schemas/PluginLogLevel'
                  required: [dir, config, logLevel]
        PluginConfigInput:
            type: object
            properties:
                config:
                    type: object
                    additionalProperties: {}
            required: [config]
            description: 'A submitted settings form. Secret values arrive in here and are never echoed back'
        GrantDecision:
            type: string
            enum: [allowed, denied]
            description: "What a plugin may do with a capability it asked for. Denied is the default and needs no row: a\ncapability is refused until somebody allows it, so \"never answered\" and \"refused\" are one state"
        PluginGrant:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                pluginName:
                    type: string
                    minLength: 1
                    maxLength: 200
                capability:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: "The host's own id for it, e.g. `network.open`"
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What the host calls the capability'
                describes:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: "What allowing it opens up, in the station's words"
                reason:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: "Why this plugin says it needs it, in the plugin's words"
                decision:
                    '$ref': '#/components/schemas/GrantDecision'
            required: [pluginId, pluginName, capability, label, describes, reason, decision]
            description: "One capability a plugin asked for, with the station's answer. The ask is the plugin's manifest and\nthe answer is a row, so a plugin that stops asking stops appearing here whatever was stored"
        PluginGrantList:
            type: object
            properties:
                grants:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PluginGrant'
                    description: 'Every capability every installed plugin is asking for, refused ones included'
            required: [grants]
        PluginGrantInput:
            type: object
            properties:
                capability:
                    type: string
                    minLength: 1
                    maxLength: 100
                decision:
                    '$ref': '#/components/schemas/GrantDecision'
            required: [capability, decision]
        PluginTestResult:
            type: object
            properties:
                ok:
                    type: boolean
                message:
                    type: string
                    maxLength: 4000
            required: [ok]
            description: "Outcome of the plugin's own `testConnection()`"
        PluginFieldSuggestions:
            type: object
            properties:
                fields:
                    type: object
                    additionalProperties:
                        type: array
                        items:
                            '$ref': '#/components/schemas/ConfigFieldOption'
                    description: 'Keys the plugin had nothing to say about are simply absent, rather than present and empty'
                supported:
                    type: boolean
                    description: "False when the plugin does not implement suggestions at all, so a console can tell \"nothing to\nsuggest\" from \"asked and got nothing\", and draw a refresh control only where one would do something"
            required: [fields, supported]
            description: "Live choices for a plugin's config fields, keyed by field key, out of the plugin's own\n`suggestConfigOptions()`. What `ConfigFieldDescriptor.options` cannot be: fixed when the manifest\nwas written, where these are whatever the operator's own server currently says"
        PluginOAuthStart:
            type: object
            properties:
                url:
                    type: string
                    format: uri
            required: [url]
            description: "Where the console should send the browser to obtain the operator's consent. Reported rather than\nredirected to: the route is behind the Bearer floor, so a browser cannot follow a redirect from it"
        PluginOAuthResult:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                ok:
                    type: boolean
                message:
                    type: string
                    maxLength: 4000
            required: [pluginId, ok]
            description: 'Outcome of an OAuth callback'
        PluginOAuthCallbackQuery:
            type: object
            properties:
                code:
                    type: string
                    maxLength: 2048
                state:
                    type: string
                    maxLength: 400
                error:
                    type: string
                    maxLength: 400
                ubi:
                    type: string
                    maxLength: 400
                token:
                    type: string
                    maxLength: 2048
                    description: "What a desktop-style flow returns instead of `code`: the provider mints a token before the\nconsent screen and hands the same one back, which the plugin exchanges for a session. Last.fm's\nauth works this way. Listed here because the route parses this query strictly, so an\nundeclared parameter is a 400 before any plugin code runs"
        StationShow:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: "Unique across the station: the plugin's own id for the show, qualified with the plugin that offered it"
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                title:
                    type: string
                    minLength: 1
                    maxLength: 600
                    description: 'What the show is called, which is what a presenter says out loud'
                author:
                    type: string
                    maxLength: 600
                description:
                    type: string
                    maxLength: 4000
                    description: 'What the show says about itself, as plain text'
                artworkUrl:
                    type: string
                    maxLength: 2000
                homeUrl:
                    type: string
                    maxLength: 2000
                feedUrl:
                    type: string
                    maxLength: 2000
                    description: 'Where its feed is, when the plugin reads one'
                language:
                    type: string
                    maxLength: 40
                categories:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                explicit:
                    type: boolean
                    description: 'Whether the publisher marked the whole show explicit. Absent means the publisher did not say, which is not the same as clean'
            required: [id, pluginId, title]
            description: 'A programme the station carries, as one installed plugin describes it'
        StationShowList:
            type: object
            properties:
                shows:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationShow'
            required: [shows]
        StationEpisode:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: "The station's own id for this episode"
                showId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'Qualified, matching `StationShow.id`'
                episodeId:
                    type: string
                    minLength: 1
                    maxLength: 1000
                    description: "The plugin's own id for the episode, stable across refreshes"
                showTitle:
                    type: string
                    minLength: 1
                    maxLength: 600
                title:
                    type: string
                    minLength: 1
                    maxLength: 1000
                summary:
                    type: string
                    maxLength: 4000
                    description: 'What the publisher says it is about, as plain text'
                url:
                    type: string
                    maxLength: 2000
                    description: "The episode's page, for a person"
                publishedAt:
                    type: string
                    maxLength: 40
                    description: ISO-8601
                durationMs:
                    type: integer
                    minimum: 0
                    description: 'How long the publisher says it runs, in milliseconds'
                artworkUrl:
                    type: string
                    maxLength: 2000
                explicit:
                    type: boolean
                seenAt:
                    type: string
                    maxLength: 40
                    description: 'ISO-8601: when a refresh last saw it in its feed'
                fetched:
                    type: boolean
                    description: 'Whether the station holds its own copy of the audio, ready to air'
                fetchRequestedAt:
                    type: string
                    maxLength: 40
                    description: 'ISO-8601: when the station last asked for the audio'
                fetchError:
                    type: string
                    maxLength: 2000
                    description: 'Why the last attempt to fetch the audio failed, when it did'
                scheduledFor:
                    type: string
                    maxLength: 40
                    description: 'ISO-8601: the slot the audio was fetched for'
                airedAt:
                    type: string
                    maxLength: 40
                    description: 'ISO-8601: when a listener could first have heard it. An episode airs once'
            required: [id, showId, episodeId, showTitle, title, seenAt, fetched]
            description: 'One episode of a programme the station carries, and what the station has done with it'
        StationDirectoryEntry:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: "The directory's own id for the show. A key in a list, and nothing more"
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The plugin whose directory answered, which is the plugin a subscription would go to'
                title:
                    type: string
                    minLength: 1
                    maxLength: 600
                feedUrl:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: "Where the show's feed is, which is what subscribing needs"
                author:
                    type: string
                    maxLength: 600
                description:
                    type: string
                    maxLength: 4000
                artworkUrl:
                    type: string
                    maxLength: 2000
                homeUrl:
                    type: string
                    maxLength: 2000
                categories:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                explicit:
                    type: boolean
            required: [id, pluginId, title, feedUrl]
            description: "A show a podcast plugin's directory knows about, which the station may or may not carry"
        StationDirectoryQuery:
            type: object
            properties:
                query:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Words to look a show up by: its name, its publisher, its subject'
                limit:
                    type: integer
                    minimum: 1
                    maximum: 50
            required: [query]
        StationDirectoryPage:
            type: object
            properties:
                results:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationDirectoryEntry'
                    description: 'Empty when nothing matched or no directory could be asked, which is not an error'
            required: [results]
        StationEpisodeQuery:
            type: object
            properties:
                showId:
                    type: string
                    maxLength: 400
                    description: "One show's episodes, or absent for every show's, newest first"
                limit:
                    type: integer
                    minimum: 1
                    maximum: 200
        StationEpisodePage:
            type: object
            properties:
                episodes:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationEpisode'
                    description: 'Newest first. Empty when the station knows of none, which is not an error'
            required: [episodes]
        OwnShow:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                title:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "What the show is called. Each episode's title starts with it"
                description:
                    type: string
                    maxLength: 2000
                    description: 'What the show is, for the console. Never read out'
                subject:
                    type: string
                    maxLength: 4000
                    description: 'What an episode is about when it is asked for with no subject of its own'
                personaId:
                    type: string
                    maxLength: 100
                    description: 'Who presents it. Absent is whoever is presenting when it is made'
                targetMs:
                    type: integer
                    minimum: 60000
                    maximum: 7200000
                    description: "How long an episode runs. Absent is the station's production length"
                writingMode:
                    type: string
                    enum: [quick, outlined, polished]
                    description: "How much of the model an episode is worth. Absent is the station's default"
                newsFeedIds:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 400
                    maxItems: 20
                    description: "The station's news feeds an episode reads, by their qualified ids. Absent or empty is a show that does not read the news"
                newsHours:
                    type: integer
                    minimum: 1
                    maximum: 168
                    description: 'How many hours of news an episode reads. Absent is a day'
                research:
                    type: boolean
                    description: "Whether an episode given nothing to read finds its own sources on the operator's trusted sites"
                createdAt:
                    type: string
                    format: date-time
                    readOnly: true
            required: [id, title, createdAt]
            description: 'A show the station makes for itself: a saved recipe for a podcast, whose every episode is a production'
        OwnShowList:
            type: object
            properties:
                shows:
                    type: array
                    items:
                        '$ref': '#/components/schemas/OwnShow'
            required: [shows]
        OwnEpisodeRequest:
            type: object
            properties:
                topic:
                    type: string
                    maxLength: 4000
                    description: "What this episode is about. Absent is the show's own subject"
                url:
                    type: string
                    maxLength: 2000
                    description: 'A page for it to read first, by its address. The episode states only what it can find there'
                sourceTitle:
                    type: string
                    maxLength: 300
                    description: 'What the pasted text is called'
                text:
                    type: string
                    maxLength: 20000
                    description: 'Something for it to read first. The episode states only what it can find in this. Given text, a show that reads the news reads this instead'
                airAt:
                    type: string
                    format: date-time
                    description: 'When it should air. Absent is as soon as it is made'
            description: "Asks one of the station's own shows for an episode. Everything is optional: a show with a standing subject needs nothing"
        ProductionCastMember:
            type: object
            properties:
                role:
                    type: string
                    enum: [host, caller, guest, cohost]
                name:
                    type: string
                    maxLength: 200
                    description: 'What they are called on air'
                persona:
                    type: string
                    maxLength: 100
                    description: 'The persona key, for a link back to the character'
            required: [role]
            description: "One person in a production: the presenter, or somebody cast to phone in. A snapshot rather than a\nreference, because the persona it names may be edited or deleted while the programme is still being\nmade and what the turns were written as has to be what an operator reads back"
        ProductionSource:
            type: object
            properties:
                title:
                    type: string
                    minLength: 1
                    maxLength: 300
                    description: "What the source is called, for the console and for the research pass's sense of what it is reading"
                url:
                    type: string
                    maxLength: 2000
                    description: 'Where it came from, when it came from somewhere'
                text:
                    type: string
                    maxLength: 20000
                    description: 'What it says. Absent for a source given only by its address, which the research pass reads through whichever installed plugin can open a page'
            required: [title]
            description: 'Something a production was handed to read. The research pass takes the notes it states as fact out of these, keeping only claims whose words really are in the text'
        Production:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                kind:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'What sort of production: podcast, bulletin, feature. Free text, so a station that wants a documentary strand needs no migration'
                title:
                    type: string
                    minLength: 1
                    maxLength: 300
                brief:
                    type: string
                    maxLength: 4000
                    description: "What was asked for, in the operator's own words. Distinct from the title, which is only a label"
                notes:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                    maxItems: 40
                    description: 'What it may state as fact, one short note each. The outline divides them between the beats, and nothing else it says is offered as fact'
                sources:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ProductionSource'
                    maxItems: 6
                    description: 'What it was handed to read. Its notes are taken from these by the research pass when nobody gave it any'
                research:
                    type: boolean
                    readOnly: true
                    description: "Whether it was asked to find its own sources on the operator's trusted sites"
                personaId:
                    type: string
                    maxLength: 100
                    description: "Who presents it. Absent falls back to the station's active persona when a pass runs"
                writingMode:
                    type: string
                    enum: [quick, outlined, polished]
                    description: 'How many passes to spend on it'
                targetMs:
                    type: integer
                    minimum: 1000
                    description: 'How long it should run. What the beat count and the per-beat word budgets are computed from'
                state:
                    type: string
                    enum:
                        - planned
                        - researching
                        - outlining
                        - drafting
                        - checking
                        - rendering
                        - stitching
                        - ready
                        - aired
                        - failed
                        - cancelled
                    readOnly: true
                    description: '`researching` is its sources being read for notes. `stitching` is the beats being joined into one piece of audio, and it leads to `ready` whether that worked or not'
                error:
                    type: string
                    maxLength: 2000
                    readOnly: true
                    description: 'Why making it did not work'
                scheduledFor:
                    type: string
                    format: date-time
                    description: 'When it should air. Absent means as soon as it is made'
                cancelledAt:
                    type: string
                    format: date-time
                    readOnly: true
                beats:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'How many beats exist so far, which is how far along the drafting is'
                showId:
                    type: string
                    maxLength: 100
                    readOnly: true
                    description: "The station's own show this is an episode of, when it is one"
                cast:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ProductionCastMember'
                    readOnly: true
                    description: 'Who is on it, decided by the first pass that ran. Empty for one nobody has started, and for a programme the presenter reads alone'
                createdAt:
                    type: string
                    format: date-time
                    readOnly: true
            required: [id, kind, title, writingMode, targetMs, state, beats, cast, createdAt]
            description: 'Something the station makes rather than something it says: several beats of speech, written in several passes, that airs as one block'
        ProductionList:
            type: object
            properties:
                productions:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Production'
            required: [productions]
        ProductionRequest:
            type: object
            properties:
                kind:
                    type: string
                    minLength: 1
                    maxLength: 100
                title:
                    type: string
                    minLength: 1
                    maxLength: 300
                    description: 'Absent is named after its kind and the moment it was asked for, which is what somebody taking a call now wants rather than a box to fill in'
                brief:
                    type: string
                    maxLength: 4000
                notes:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 500
                    maxItems: 40
                    description: 'What it may state as fact, one short note each. Absent leaves it to general knowledge, said vaguely'
                sources:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ProductionSource'
                    maxItems: 6
                    description: 'What to read before writing it. Given sources and no notes, a research pass takes the notes out of these first'
                research:
                    type: boolean
                    description: "Given nothing to read, search the operator's trusted sites for its subject and read what comes back. Needs an enrichment plugin that can, such as the web search one with trusted sites"
                personaId:
                    type: string
                    maxLength: 100
                writingMode:
                    type: string
                    enum: [quick, outlined, polished]
                    description: "Absent takes the station's `render.productionWritingMode`"
                targetMs:
                    type: integer
                    minimum: 1000
                scheduledFor:
                    type: string
                    format: date-time
            description: 'What an operator asks for. Everything else about a production is decided by the passes that make it'
        Segment:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                kind:
                    type: string
                    minLength: 1
                    maxLength: 50
                    description: 'What sort of element it is: `ident`, `stinger`, `talkbreak`, `news`'
                state:
                    type: string
                    enum: [planned, writing, written, rendering, ready, failed]
                    description: 'One state per stage of making it. Only `ready` can go on air; the station skips anything else rather than waiting for it'
                label:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'What the console calls it, and what the mount is labelled with while it airs'
                source:
                    type: string
                    minLength: 1
                    maxLength: 50
                    description: 'Who made it: `library` for a file dropped into the inbox'
                playable:
                    type: boolean
                    description: 'Whether there is audio behind it yet'
                script:
                    type: string
                    maxLength: 20000
                    description: 'The words, for anything that speaks. Absent for an imported recording'
                spokenScript:
                    type: string
                    maxLength: 20000
                    description: "The words as the speech engine was handed them: symbols said, years read as a person reads them, the station's pronunciation list applied. Absent until something has spoken it"
                sourcePath:
                    type: string
                    maxLength: 1000
                    description: 'The file in the inbox this came from. The bytes were copied, so emptying the inbox does not take it off the air'
                durationMs:
                    type: integer
                    minimum: 0
                    description: 'How long it runs. A display value: the player measures the audio itself'
                error:
                    type: string
                    maxLength: 2000
                    description: 'Why it is `failed`'
                voice:
                    type: string
                    maxLength: 100
                    description: "The station's own name for the voice this is said in, e.g. `host`. Absent means the speech plugin's default"
                delivery:
                    type: string
                    maxLength: 50
                    description: "How the words are read: `hushed` or `frantic`. Absent is the voice's own ordinary reading, which is nearly every segment"
                slotIds:
                    type: array
                    items:
                        type: string
                        format: uuid
                    description: 'The shows this recording is for, as schedule slot ids. Absent or empty with no `personaIds` is every show. Only a recording an operator gave the station is ever scoped'
                personaIds:
                    type: array
                    items:
                        type: string
                        format: uuid
                    description: 'The presenters this recording is for, whichever show they are on. A recording airs on a show when either list names what is on air'
            required: [id, kind, state, label, source, playable]
            description: 'One thing the station can play that is not a record'
        SegmentScope:
            type: object
            properties:
                slotIds:
                    type: array
                    items:
                        type: string
                        format: uuid
                    maxItems: 200
                    description: 'Schedule slot ids: the recording airs while one of these shows is on, whoever presents it'
                personaIds:
                    type: array
                    items:
                        type: string
                        format: uuid
                    maxItems: 200
                    description: 'Persona ids: the recording airs while one of these presenters is on, whichever show it is'
            required: [slotIds, personaIds]
            description: 'Which shows and presenters a recording is for. Both empty is every show'
        SegmentCreate:
            type: object
            properties:
                label:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'What the console calls it, and what the mount is labelled with while it airs'
                script:
                    type: string
                    minLength: 1
                    maxLength: 20000
                    description: 'The words to say'
                kind:
                    type: string
                    minLength: 1
                    maxLength: 50
                    description: 'What sort of element it is. Defaults to `talkbreak`'
                voice:
                    type: string
                    maxLength: 100
                    description: 'A station voice name the speech plugin knows how to map. Absent uses its default'
                delivery:
                    type: string
                    maxLength: 50
                    description: "How to read the words: `hushed` or `frantic`, and refused otherwise. Absent is the voice's own ordinary reading. Dropped at render time by an engine that cannot perform it"
            required: [label, script]
            description: 'Something for the station to say, before anything has said it'
        SegmentUpload:
            type: object
            properties:
                file:
                    type: string
                    format: binary
                    description: 'The audio itself. mp3, wav, ogg, flac or m4a, and at most 50 MB'
                kind:
                    type: string
                    minLength: 1
                    maxLength: 50
                    description: 'What sort of element it is, which is also the directory it is filed under. A kind nothing else uses becomes a bookable band on the format clock'
                label:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: 'What the console calls it, and what the mount is labelled with while it airs. Derived from the filename when absent'
            required: [file, kind]
            description: "A recording arriving from the browser, as multipart form parts.\n\nDocumentation rather than validation: a multipart body reaches the service as the raw parser and\nthe generated client types the body as `FormData`, so nothing checks this shape. It says what to\nsend"
        SegmentList:
            type: object
            properties:
                segments:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Segment'
            required: [segments]
            description: 'Everything the station can play that is not a record'
        Voice:
            type: object
            properties:
                id:
                    type: string
                    maxLength: 100
                    description: "What to pass as a segment's `voice`. Empty means the plugin's own default"
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What the console calls it'
                description:
                    type: string
                    maxLength: 500
                    description: 'What it sounds like, or what it maps to on the engine'
            required: [id, label]
            description: 'A voice the station can be asked to speak in'
        VoiceList:
            type: object
            properties:
                voices:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Voice'
                pluginId:
                    type: string
                    maxLength: 200
                    description: 'Which plugin answered. Absent when nothing can speak'
                reason:
                    type: string
                    maxLength: 500
                    description: 'Why there are no voices, when there are none'
                deliveries:
                    type: array
                    items:
                        type: string
                        maxLength: 50
                    description: 'Which readings that plugin can perform right now, out of `hushed` and `frantic`. Absent or empty means none, which is most engines and is not a fault'
            required: [voices]
            description: "The voices the station's current speech plugin offers"
        ScriptOutcome:
            type: string
            enum: [written, declined, failed]
            description: 'Whether there are words, and if not, which way it went wrong'
        ScriptNeighbour:
            type: object
            properties:
                title:
                    type: string
                    minLength: 1
                    maxLength: 500
                artist:
                    type: string
                    minLength: 1
                    maxLength: 500
                facts:
                    type: array
                    items:
                        type: string
                        maxLength: 1000
                    description: 'What it was shown about the record. A break that said nothing interesting and one that was TOLD nothing interesting read the same from the script alone'
            required: [title, artist]
            description: 'A record a writer was told about, kept as it was told'
        ScriptUsage:
            type: object
            properties:
                inputTokens:
                    type: integer
                    minimum: 0
                outputTokens:
                    type: integer
                    minimum: 0
                totalTokens:
                    type: integer
                    minimum: 0
            description: 'What the provider said the attempt cost, when it said anything'
        ScriptPromptMessage:
            type: object
            properties:
                role:
                    type: string
                    minLength: 1
                    maxLength: 50
                content:
                    type: string
                    maxLength: 100000
            required: [role, content]
            description: 'One turn of the conversation a writer sent'
        SegmentSource:
            type: object
            properties:
                claim:
                    type: string
                    minLength: 1
                    maxLength: 500
                    description: 'The sentence the writer was handed'
                sourceUrl:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: 'Where a person checks it'
                sourceQuote:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: 'The words there that state it'
                sourceProvider:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The plugin that fetched the page'
                told:
                    type: boolean
                    description: "Whether the break's words said it, as the station read them back. Never the model's own account, and a fact the read-back could not judge counts as not said"
            required: [claim, sourceUrl, sourceQuote, sourceProvider, told]
            description: 'One stored fact a written break was handed, as it stood when the break was written'
        SegmentSourceList:
            type: object
            properties:
                sources:
                    type: array
                    items:
                        '$ref': '#/components/schemas/SegmentSource'
            required: [sources]
        ScriptAttempt:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                at:
                    type: string
                    format: date-time
                kind:
                    type: string
                    minLength: 1
                    maxLength: 50
                    description: 'What sort of break it was for: `talkbreak`, `welcome`, `news`'
                writer:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'The binding that produced or declined it'
                outcome:
                    '$ref': '#/components/schemas/ScriptOutcome'
                personaKey:
                    type: string
                    maxLength: 100
                    description: "Who was presenting, as the persona's own key. Absent means nobody was, which is an ordinary state. Stamped on every attempt including the declined ones, so a character whose model breaks are all being refused is visible rather than hidden behind the floor"
                label:
                    type: string
                    maxLength: 400
                script:
                    type: string
                    maxLength: 20000
                    description: 'The words. Absent for an attempt that produced none'
                delivery:
                    type: string
                    maxLength: 50
                    description: 'How the writer chose to have the words read, `hushed` or `frantic`. Absent for an ordinary reading'
                model:
                    type: string
                    maxLength: 200
                    description: 'The model that said it, for a writer that used one'
                source:
                    type: string
                    maxLength: 200
                    description: 'What the line was rendered from, for a writer working from something an operator can edit'
                reason:
                    type: string
                    maxLength: 2000
                    description: 'Why, for anything that is not `written`'
                segmentId:
                    type: string
                    maxLength: 100
                    description: 'The segment this was for, while it is still known. The row outlives it'
                previous:
                    '$ref': '#/components/schemas/ScriptNeighbour'
                next:
                    '$ref': '#/components/schemas/ScriptNeighbour'
                durationMs:
                    type: integer
                    minimum: 0
                    description: 'How long the attempt took'
                usage:
                    '$ref': '#/components/schemas/ScriptUsage'
                raw:
                    type: string
                    maxLength: 100000
                    description: 'The answer before anything read it. Only while `llm.captureWrites` is on'
                prompt:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ScriptPromptMessage'
                    description: 'What the writer sent. Only while `llm.captureWrites` is on'
                rating:
                    '$ref': '#/components/schemas/ScriptRating'
                    readOnly: true
                    description: 'What the operator thought of it. ABSENT means nobody has said, which `neutral` does not'
            required: [id, at, kind, writer, outcome]
            description: 'One attempt to write something the station would say, including the ones that came to nothing'
        ScriptRating:
            type: string
            enum: [liked, neutral, disliked]
            description: "What an operator thought of something the station said.\n\nThe catalog's three spellings exactly, and deliberately not a second vocabulary: an opinion is an\nopinion whether it is about a record or about a sentence, and `catalog/rating.ts` is the one place\nthe words and the column's numbers meet.\n\n`neutral` is a real answer rather than an absence. Rating something back to nothing is a thing an\noperator does, and it has to be distinguishable from never having listened, which is the field\nbeing absent on the attempt."
        ScriptRatingInput:
            type: object
            properties:
                rating:
                    '$ref': '#/components/schemas/ScriptRating'
            required: [rating]
        ScriptHistoryQuery:
            type: object
            properties:
                limit:
                    type: integer
                    minimum: 1
                    maximum: 200
                before:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Where the previous page ended. Opaque, and a keyset rather than an offset because rows arrive at the head continuously. Pass back whatever `nextBefore` said and nothing else'
                kind:
                    type: string
                    minLength: 1
                    maxLength: 50
                writer:
                    type: string
                    minLength: 1
                    maxLength: 100
                outcome:
                    '$ref': '#/components/schemas/ScriptOutcome'
                personaKey:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Everything ONE character has said. Absent is every character and none'
                segmentId:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Every attempt made for ONE break, which is how a console reaches the words behind an item of the running order. Absent is the whole history'
            description: 'One page of what the station has written, newest first'
        ScriptHistoryPage:
            type: object
            properties:
                attempts:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ScriptAttempt'
                nextBefore:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The cursor for the page after this one, absent once the history has been read to its end'
            required: [attempts]
        SpeechPreviewRequest:
            type: object
            properties:
                text:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: "What to say. Far under a segment's 20000 because this is one break heard once, and the cap is what bounds a cache keyed on the words themselves"
                voice:
                    type: string
                    maxLength: 100
                    description: "A station voice name, as a segment's `voice`. Absent uses the plugin's own default"
                delivery:
                    type: string
                    maxLength: 50
                    description: "How to read it, as a segment's `delivery`: `hushed` or `frantic`, and refused otherwise. Absent is the voice's own ordinary reading"
                soundboard:
                    type: string
                    maxLength: 200
                    description: "The board a `[sfx:name]` in the text is played from, as a character's `soundboard`. Absent, or a hit the board does not hold, and the hit is left out and only the words are spoken"
            required: [text]
            description: 'Words to hear before anything has aired them'
        ScriptHistorySummaryQuery:
            type: object
            properties:
                hours:
                    type: integer
                    minimum: 1
                    maximum: 168
                    description: 'How far back to count. Defaults to 24, and a week at most, because past that the nightly sweep may already have taken the rows and the count would quietly be of what survived rather than of what happened'
            description: 'The window the counts cover'
        ScriptHistorySummaryRow:
            type: object
            properties:
                personaKey:
                    type: string
                    maxLength: 100
                    description: 'Absent means nobody was presenting, which is an ordinary state rather than a gap in the data'
                written:
                    type: integer
                    minimum: 0
                declined:
                    type: integer
                    minimum: 0
                    description: 'A decline is the writer registry working: the model had nothing to say and the floor covered for it'
                failed:
                    type: integer
                    minimum: 0
            required: [written, declined, failed]
            description: "One presenter's attempts in the window"
        ScriptHistorySummary:
            type: object
            properties:
                hours:
                    type: integer
                    minimum: 1
                    maximum: 168
                    description: 'The window actually counted, echoed so a console can label the numbers it draws'
                rows:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ScriptHistorySummaryRow'
            required: [hours, rows]
            description: 'What each presenter has written lately, and over how long'
        ScriptPerformanceQuery:
            type: object
            properties:
                days:
                    type: integer
                    minimum: 1
                    maximum: 365
                    description: 'How far back to read. Defaults to 30. The nightly sweep decides how far back there is anything to read, and ratings go with the rows they rate'
            description: 'The window the figures cover'
        ScriptDeclineReason:
            type: object
            properties:
                reason:
                    type: string
                    maxLength: 2000
                    description: "The station's own sentence for the fault, without any wording it quoted"
                count:
                    type: integer
                    minimum: 0
            required: [reason, count]
            description: "One reason a writer's answer was refused"
        ScriptPerformanceRow:
            type: object
            properties:
                personaKey:
                    type: string
                    maxLength: 100
                    description: 'Absent means nobody was presenting, which is an ordinary state rather than a gap in the data'
                kind:
                    type: string
                    maxLength: 100
                written:
                    type: integer
                    minimum: 0
                declined:
                    type: integer
                    minimum: 0
                failed:
                    type: integer
                    minimum: 0
                liked:
                    type: integer
                    minimum: 0
                neutral:
                    type: integer
                    minimum: 0
                disliked:
                    type: integer
                    minimum: 0
                declineReasons:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ScriptDeclineReason'
                    description: 'Most common first'
            required: [kind, written, declined, failed, liked, neutral, disliked, declineReasons]
            description: "One presenter's writing of one kind of break, and what the operator thought of it"
        ScriptPerformance:
            type: object
            properties:
                days:
                    type: integer
                    minimum: 1
                    maximum: 365
                    description: 'The window actually read, echoed so a console can label what it draws'
                rows:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ScriptPerformanceRow'
            required: [days, rows]
            description: "How each presenter's breaks are doing, by the checks and by the operator"
        SegmentScanResult:
            type: object
            properties:
                scanned:
                    type: integer
                    minimum: 0
                    description: 'Audio files seen, whether or not they were already known'
                imported:
                    type: integer
                    minimum: 0
                    description: 'Segments the station did not have before this pass'
                skipped:
                    type: integer
                    minimum: 0
                    description: 'Files passed over: not audio it can serve, or unreadable'
            required: [scanned, imported, skipped]
            description: 'What one pass over the inbox did'
        Pronunciation:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                written:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What appears in a script. Matched case-insensitively, and whole words only'
                spoken:
                    type: string
                    maxLength: 400
                    description: 'What the engine is handed instead, untouched. EMPTY is meaningful: it drops the words, which is the honest reading for a marker that got into a title and is not a word'
                state:
                    type: string
                    enum: [active, suggested, rejected]
                    description: '`active` is said. `suggested` is proposed and says nothing yet. `rejected` outlives the pass that proposed it, or the same article proposes it again forever'
                origin:
                    type: string
                    enum: [operator, gloss]
                    description: 'Who says so. `gloss` is a pronunciation key an encyclopaedia article printed for itself'
                sourceUrl:
                    type: string
                    maxLength: 2000
                    description: 'The article. Present on anything an operator did not type'
                sourceQuote:
                    type: string
                    maxLength: 2000
                    description: 'The sentence that says so, as it stands in the article, which is what the decision is actually made on'
                subjectKind:
                    type: string
                    enum: [track, album, artist]
                    description: 'What the article was about'
                subjectId:
                    type: string
                    maxLength: 100
                createdAt:
                    type: string
                    minLength: 1
                    maxLength: 40
            required: [id, written, spoken, state, origin, createdAt]
            description: 'One name the station says differently from how it is written'
        PronunciationList:
            type: object
            properties:
                pronunciations:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Pronunciation'
            required: [pronunciations]
            description: "The station's lexicon, oldest first"
        PronunciationWrite:
            type: object
            properties:
                written:
                    type: string
                    minLength: 1
                    maxLength: 200
                spoken:
                    type: string
                    maxLength: 400
                    description: 'Empty drops the words rather than saying them'
            required: [written, spoken]
            description: 'A name and how to say it'
        PronunciationStateWrite:
            type: object
            properties:
                state:
                    type: string
                    enum: [active, suggested, rejected]
            required: [state]
            description: 'Accepting a proposal, turning one down, or taking an entry out of use without losing it'
        PronunciationSampleRequest:
            type: object
            properties:
                written:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What is spoken, with this entry applied to it'
                spoken:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: "How this entry says it. Not empty, unlike a stored entry's: an entry that drops the words has nothing to hear"
                voice:
                    type: string
                    maxLength: 100
                    description: "A station voice name. Absent uses the plugin's own default"
            required: [written, spoken]
            description: 'One entry to hear, whether or not the lexicon holds it yet'
        PronunciationQuery:
            type: object
            properties:
                state:
                    type: string
                    enum: [active, suggested, rejected]
                    description: 'Absent is all of it'
            description: 'Which part of the lexicon to read'
        Pad:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    readOnly: true
                board:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Which directory it arrived in. Provenance: what reaches it is a set'
                sets:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                    readOnly: true
                    description: 'The keys of the sets it is on. Empty means it is in the library and nothing can hit it'
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What a script writes: `[sfx:airhorn]`'
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                durationMs:
                    type: integer
                    minimum: 0
                loudnessLufs:
                    type: number
                    description: 'How loud it came out, once something measured it. Absent on a station with no analyzer, which is ordinary'
                source:
                    type: string
                    minLength: 1
                    maxLength: 50
                    readOnly: true
                    description: 'Who put the file there: `library` for one the operator dropped in, `upload` or `url` for one the console wrote. It decides whether the console may delete it'
                sourcePath:
                    type: string
                    maxLength: 500
                    description: 'The file in the library directory it was imported from, so the console can say where it came from'
                lastUsedAt:
                    type: string
                    format: date-time
                    description: 'When it was last hit. Absent for one nothing has reached for yet'
                state:
                    type: string
                    enum: [active, rejected]
                placements:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PadPlacement'
                    description: 'Where in a break it may land: before the first word, between two, or after the last. Every pad starts with all three'
                cue:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'When to reach for it, in the operator''s words ("right after a punchline"). Shown to the presenter beside the sound; the station''s own writers leave a cued pad alone'
            required: [id, board, sets, name, label, source, state, placements]
            description: "One sound on a soundboard, as the console draws it.\n\n`name` is what a script writes to hit it and `label` is what a person reads: two columns rather\nthan one, because a token for a model and prose for an operator are different things and the\nfilename produces both"
        PadPlacement:
            type: string
            enum: [start, middle, end]
            description: "Where in a break a sound may fall. `start` is before the first word, `end` after the last, and\n`middle` anywhere between two words"
        PadUse:
            type: object
            properties:
                placements:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PadPlacement'
                    minItems: 1
                    description: 'At least one: a sound that may go nowhere is a sound turned down, which is what `PadState` is for'
                cue:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Absent clears it, so the pad is fair game wherever its placements allow'
            required: [placements]
            description: 'Where and when a pad may be hit, written together because the console edits them together'
        PadUpload:
            type: object
            properties:
                file:
                    type: string
                    format: binary
                    description: 'The audio itself. mp3, wav, ogg, flac or m4a, and at most 25 MB'
                board:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The directory it is filed under, which is also the set it joins. A new name makes both'
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What a script will write. Derived from the filename when absent, and the FILE is named after this either way'
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What the console calls it. Derived from the filename when absent'
            required: [file, board]
            description: "A sound arriving from the browser, as multipart form parts.\n\nDocumentation rather than validation: a multipart body reaches the service as the raw parser and\nthe generated client types the body as `FormData`, so nothing checks this shape. It says what to\nsend"
        PadFetch:
            type: object
            properties:
                url:
                    type: string
                    format: uri
                    description: 'Where the audio is. Followed once, bounded, and refused unless what comes back is a format the station serves'
                board:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The directory it is filed under, which is also the set it joins'
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What a script will write. Derived from the address when absent'
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
            required: [url, board]
            description: "A sound the station is being told to go and get.\n\nThe operator names the address, so this is them choosing a file exactly as dropping one in the\nlibrary is. Nothing inspects what comes back and nothing records a claim about its licence -- see\n`docs/internals/render.md` under \"Pads\", whose line is redistribution rather than use"
        PadList:
            type: object
            properties:
                pads:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Pad'
                sets:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PadSet'
            required: [pads, sets]
            description: 'Every sound the station holds, and the sets over it'
        PadSet:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    readOnly: true
                key:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The slug a persona names. A directory in the pad library makes one of these'
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                position:
                    type: integer
                    minimum: 0
                pads:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'How many sounds are on it. Zero is ordinary: it is what a set looks like before anybody drops a file'
                personas:
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 200
                    readOnly: true
                    description: 'Who is pointed at it, so a rename or a delete can say what it is about to unpoint'
            required: [id, key, label, position, pads, personas]
            description: "A named collection of pads: what a presenter is actually handed.\n\nOne library, cut as many ways as an operator likes. `personas.soundboard` holds the `key`, so\nrenaming a set unpoints every persona naming it — which is why `personas` says who those are"
        PadSetWrite:
            type: object
            properties:
                key:
                    type: string
                    minLength: 1
                    maxLength: 200
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                position:
                    type: integer
                    minimum: 0
            required: [key, label]
            description: 'A set an operator is naming, or renaming'
        PadSetMembership:
            type: object
            properties:
                padId:
                    type: string
                    format: uuid
                'on':
                    type: boolean
            required: [padId, 'on']
            description: 'Which pad, and whether it is on the set'
        PadState:
            type: object
            properties:
                state:
                    type: string
                    enum: [active, rejected]
            required: [state]
            description: 'Turning a pad down, or putting one back'
        PadScanResult:
            type: object
            properties:
                scanned:
                    type: integer
                    minimum: 0
                    description: 'Audio files seen, whether or not anything changed'
                imported:
                    type: integer
                    minimum: 0
                    description: 'Sounds the station did not have before'
                replaced:
                    type: integer
                    minimum: 0
                    description: 'Slots whose file changed under them, which every script naming them now plays'
                contested:
                    type: integer
                    minimum: 0
                    description: 'Sounds that reached the library but not their set, because it already answered to their name. In the library and unreachable until somebody says where they go'
                skipped:
                    type: integer
                    minimum: 0
                    description: 'Files passed over: not audio, unreadable, or named something no script could write'
            required: [scanned, imported, replaced, contested, skipped]
            description: 'What one pass over the pad library did'
        SegmentAudioRendition:
            type: string
            enum: [original, share]
            description: "Which copy of a segment's audio. `original` is what the station airs. `share` is a small copy made for a listener to send on, AAC in an .m4a, never aired"
        SegmentAudioQuery:
            type: object
            properties:
                rendition:
                    '$ref': '#/components/schemas/SegmentAudioRendition'
                    default: original
                    description: 'A purpose the station interprets rather than a format the caller picks, so what `share` means can change without any caller changing'
            required: [rendition]
        RequestableSource:
            type: object
            properties:
                pluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The plugin that carries it'
                externalId:
                    type: string
                    minLength: 1
                    maxLength: 400
                    description: "That plugin's own id for the record"
            required: [pluginId, externalId]
            description: "A music provider's copy of a record the station has not taken in yet"
        RequestableTrack:
            type: object
            properties:
                trackId:
                    type: string
                    format: uuid
                    description: 'What to send as `trackId` to make the request. Absent for a record from a provider, which is asked for by `source` instead'
                source:
                    '$ref': '#/components/schemas/RequestableSource'
                    description: 'Where a record the station does not hold yet comes from. Send it as `source` to ask for it'
                sourceName:
                    type: string
                    maxLength: 200
                    description: 'The provider, as the station names it, for a record from one'
                title:
                    type: string
                    maxLength: 400
                artist:
                    type: string
                    maxLength: 400
                    description: 'The lead artist'
                album:
                    type: string
                    maxLength: 400
                year:
                    type: integer
            required: [title, artist]
            description: 'A record the station could be asked for: one it holds, or one a music provider carries'
        RequestableTrackList:
            type: object
            properties:
                tracks:
                    type: array
                    items:
                        '$ref': '#/components/schemas/RequestableTrack'
            required: [tracks]
            description: "Records matching a search, best matches first, the station's own before any a provider carries"
        RequestStatus:
            type: string
            enum: [waiting, pending, queued, aired, declined, expired]
        RequestSource:
            type: string
            enum: [app, chat]
        ListenerRequest:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                trackId:
                    type: string
                    format: uuid
                    description: "The record in the station's library, so it can be asked for again with `POST /requests`. Absent on a refusal answered before a provider's record was taken in"
                status:
                    '$ref': '#/components/schemas/RequestStatus'
                    description: '`waiting` for an operator to approve it, `pending` while its audio is fetched or a place is found for it, `queued` in the running order, `aired` once heard, `declined` or `expired` when it never will be'
                title:
                    type: string
                    maxLength: 400
                    description: 'The record, as it was called when it was asked for'
                artist:
                    type: string
                    maxLength: 400
                requesterName:
                    type: string
                    maxLength: 200
                    description: 'Who asked, by the name their account or chat platform gave'
                source:
                    '$ref': '#/components/schemas/RequestSource'
                    description: 'Whether it came from an app or a chat platform'
                createdAt:
                    type: string
                    format: date-time
                    description: 'When it was asked for'
                reason:
                    type: string
                    maxLength: 400
                    description: "Why it was declined or expired, in the station's words or an operator's"
                airedAt:
                    type: string
                    format: date-time
                    description: 'When it aired'
                dedicateTo:
                    type: string
                    maxLength: 60
                    description: 'Who the listener dedicated it to'
                message:
                    type: string
                    maxLength: 200
                    description: 'What the listener asked to have said with it, in their own words'
                fromParty:
                    type: boolean
                    description: 'True when a guest at a party asked for it, through the party pass. Absent otherwise'
                overrulable:
                    type: boolean
                    description: 'True on a declined request whoever asked may still insist on, with `POST /requests/{id}/insist`: the station turned it down for its own taste (aired lately, a cooldown, a dislike, the period, a length) rather than a rule nobody overrules. Absent otherwise, and once it has been insisted on'
                insisted:
                    type: boolean
                    description: "True when whoever asked insisted on it after the station turned it down, so the station's own taste was overruled. Absent otherwise"
            required: [id, status, title, artist, requesterName, source, createdAt]
            description: 'A record somebody asked the station to play, and what became of it'
        ListenerRequestList:
            type: object
            properties:
                requests:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ListenerRequest'
            required: [requests]
            description: 'Requests, newest first'
        ListenerRequestCreate:
            type: object
            properties:
                trackId:
                    type: string
                    format: uuid
                    description: 'A record from the request search that the station holds. Send this or `source`, never both'
                source:
                    '$ref': '#/components/schemas/RequestableSource'
                    description: 'A record from the request search that a provider carries. The station takes it in, then decides on the request as usual'
                name:
                    type: string
                    minLength: 1
                    maxLength: 60
                    description: 'What the station should call you. Omitted, you are "a listener": your account''s email address is never shown or read out'
                dedicateTo:
                    type: string
                    minLength: 1
                    maxLength: 60
                    description: 'Dedicate it to somebody. The station may say this name on air'
                message:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'A few words to go with it. The presenter may put them in their own words on air, and leaves out anything unfit to broadcast; the words themselves are never read out'
            description: 'Ask the station to play a record'
        ListenerRequestDecline:
            type: object
            properties:
                reason:
                    type: string
                    maxLength: 400
                    description: 'What to tell the listener. Omit for a plain no'
            description: 'Turn a request down'
        PartyPass:
            type: object
            properties:
                token:
                    type: string
                    maxLength: 200
                    description: "The pass itself. Put it after `#` on the station's `/party` page, as `/party#<token>`, and that address is what the QR code holds. Anyone holding it can join until the party ends, so show it only to the room"
                createdAt:
                    type: string
                    format: date-time
                    description: 'When the party started'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When the pass stops letting guests in, and turns away every guest who joined with it'
                guests:
                    type: integer
                    minimum: 0
                    description: 'How many guests have joined with it'
            required: [token, createdAt, expiresAt, guests]
            description: 'A party: the pass guests join with by scanning its QR code, for as long as it lasts'
        PartyState:
            type: object
            properties:
                party:
                    '$ref': '#/components/schemas/PartyPass'
                    description: 'Absent when no party is on'
            description: 'The party, if one is on'
        PartyStart:
            type: object
            properties:
                hours:
                    type: integer
                    minimum: 1
                    maximum: 24
                    description: 'How long the pass lasts. Six when omitted'
            description: 'Start a party'
        PartyJoin:
            type: object
            properties:
                token:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "The pass, as it appears after `#` in the party page's address"
            required: [token]
            description: 'Join a party as a guest, with the pass from its QR code'
        PartyGuestSession:
            type: object
            properties:
                accessToken:
                    type: string
                    description: 'The bearer token. It lets a guest search for records, ask for one and see their own requests, and nothing else'
                expiresAt:
                    type: string
                    format: date-time
                    description: "When it stops working, which is when the party's pass does"
            required: [accessToken, expiresAt]
            description: "A guest's way in: send it as a bearer token on the request routes"
        Festival:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    readOnly: true
                name:
                    type: string
                    minLength: 1
                    maxLength: 120
                    description: 'Said on air as written: `Shaky Knees`, `the Newport Folk Festival`'
                startsOn:
                    type: string
                    pattern: '^\d{4}-\d{2}-\d{2}$'
                    description: "The first day, as `YYYY-MM-DD` on the festival's own calendar"
                endsOn:
                    type: string
                    pattern: '^\d{4}-\d{2}-\d{2}$'
                    description: 'The last day, inclusive. The same as `startsOn` for a one-day festival'
                place:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'Where it is, as a presenter would say it: `Piedmont Park, Atlanta`. Absent says nothing about where'
                url:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: "The festival's own page. Kept as where the facts came from, and never read out"
                acts:
                    type: array
                    items:
                        '$ref': '#/components/schemas/FestivalAct'
                    maxItems: 300
                    description: 'Who is on the bill, in the order they should be listed. A name given twice is kept once'
                state:
                    type: string
                    enum: [upcoming, 'on', over]
                    readOnly: true
                    description: "Where the festival stands on the station's calendar today: still to come, on now, or finished. A finished festival is never talked about"
                sourcePluginId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The plugin a festival was imported from, from `GET /festivals/lookup`. Absent for one an operator typed. Kept as it was when a festival is changed, whatever is sent'
                sourceEventId:
                    type: string
                    minLength: 1
                    maxLength: 200
                    writeOnly: true
                    description: "That plugin's own id for the listing, sent with `sourcePluginId` when adding an imported festival"
            required: [id, name, startsOn, endsOn, acts, state]
            description: 'A music festival the station can build a show around: its dates, where it is, and who is on the bill. What a presenter says about it is read from here, so its dates are the ones an operator typed or checked'
        FestivalAct:
            type: object
            properties:
                artist:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'As the station credits them, which is the name said on air and the name the station looks their records up by'
                day:
                    type: string
                    pattern: '^\d{4}-\d{2}-\d{2}$'
                    description: "The day they play, as `YYYY-MM-DD`, when the bill says. Inside the festival's dates"
                headliner:
                    type: boolean
                    description: 'Whether they top the bill. Absent is no'
            required: [artist]
            description: "One act on a festival's bill"
        FestivalList:
            type: object
            properties:
                festivals:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Festival'
            required: [festivals]
            description: 'Every festival on the station, soonest first'
        FestivalListing:
            type: object
            properties:
                pluginId:
                    type: string
                    description: 'The plugin that listed it, to send back as `sourcePluginId`'
                eventId:
                    type: string
                    description: 'Its own id for the listing, to send back as `sourceEventId`'
                name:
                    type: string
                startsOn:
                    type: string
                    pattern: '^\d{4}-\d{2}-\d{2}$'
                endsOn:
                    type: string
                    pattern: '^\d{4}-\d{2}-\d{2}$'
                place:
                    type: string
                    description: 'The venue and the town, as the service gives them'
                url:
                    type: string
                acts:
                    type: array
                    items:
                        type: string
                    description: 'Who the service lists as performing, in its order'
            required: [pluginId, eventId, name, startsOn, endsOn, acts]
            description: 'A festival as a ticket service lists it, for an operator to check and then add. Nothing here is said on air until it is saved as a festival'
        FestivalLookup:
            type: object
            properties:
                listings:
                    type: array
                    items:
                        '$ref': '#/components/schemas/FestivalListing'
                unanswered:
                    type: array
                    items:
                        type: string
                    description: 'The plugins that were asked and could not answer, so an empty list is not read as nothing being on'
            required: [listings]
            description: 'What looking a festival up found, soonest first'
        Occasion:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    readOnly: true
                words:
                    type: string
                    minLength: 1
                    maxLength: 80
                    description: 'Said on air as written: `Halloween`, `the first day of Hanukkah`'
                ruleKind:
                    type: string
                    enum: [fixed, weekday, easter, calendar, dates]
                    description: '`fixed` is the same date every year, from `month` and `day`. `weekday` is the nth of a weekday in a month, from `month`, `ordinal` and `weekday`. `easter` is a number of days from Western Easter Sunday, from `offsetDays`. `calendar` is a date in the Hebrew or Islamic calendar, from `calendar`, `calendarMonth` and `day`. `dates` is the dates themselves, from `dates`, for what no rule can work out'
                month:
                    type: integer
                    minimum: 1
                    maximum: 12
                day:
                    type: integer
                    minimum: 1
                    maximum: 31
                    description: "The day of the month, in the rule's own calendar"
                ordinal:
                    type: integer
                    minimum: -1
                    maximum: 5
                    description: 'Which of that weekday in the month: 1 to 5, or -1 for the last. The fourth Thursday of November is `4`'
                weekday:
                    type: integer
                    minimum: 0
                    maximum: 6
                    description: '0 is Sunday'
                offsetDays:
                    type: integer
                    minimum: -60
                    maximum: 60
                    description: 'Days from Easter Sunday: 0 is the day itself and -2 is Good Friday'
                calendar:
                    type: string
                    enum: [hebrew, islamic-umalqura]
                    description: '`islamic-umalqura` is calculated, so a community going by the sighted moon may keep the day a day either side of it'
                calendarMonth:
                    type: string
                    minLength: 1
                    maxLength: 40
                    description: 'The month in that calendar, as `calendars` lists it'
                dates:
                    type: array
                    items:
                        type: string
                        minLength: 10
                        maxLength: 10
                    maxItems: 200
                    description: 'As `YYYY-MM-DD`. These run out, so a list needs refreshing'
                mood:
                    type: string
                    enum: [love, happiness, comfort, sadness, loneliness, anger, fear]
                    description: 'What this day leans into, when the show on air names no mood of its own. Records a model has judged to be in it are a little more likely to be picked, and nothing is ever kept off the air for it. Absent leans nothing'
                enabled:
                    type: boolean
                    description: 'Whether the station knows about it. Off, it is never said and never leans anything'
                position:
                    type: integer
                    readOnly: true
                    description: 'Where it comes in the list. When two fall on one date the first wins'
                nextDate:
                    type: string
                    minLength: 10
                    maxLength: 10
                    readOnly: true
                    description: "When it next falls, as `YYYY-MM-DD` on the station's calendar, counting today. Absent when it does not fall again, as a list of dates that has run out"
            required: [id, words, ruleKind, enabled, position]
            description: "What a date means where this station is: a name the presenters can say, and a mood to lean into on a\nday the show on air names none. `ruleKind` says when it falls, and which of the fields beside it count"
        OccasionCalendarMonths:
            type: object
            properties:
                calendar:
                    type: string
                    enum: [hebrew, islamic-umalqura]
                months:
                    type: array
                    items:
                        type: string
            required: [calendar, months]
            description: 'The months of a calendar an occasion can be set in, in the order they come'
        OccasionList:
            type: object
            properties:
                occasions:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Occasion'
                calendars:
                    type: array
                    items:
                        '$ref': '#/components/schemas/OccasionCalendarMonths'
            required: [occasions, calendars]
            description: 'Every occasion on the station, in the order a date is matched against them'
        OccasionOrder:
            type: object
            properties:
                ids:
                    type: array
                    items:
                        type: string
                        format: uuid
                    minItems: 1
                    maxItems: 500
                    description: 'Occasions in the order they should be matched. Any left out stay behind these, in their current order'
            required: [ids]
            description: 'A new order for the list'
        OccasionPack:
            type: object
            properties:
                format:
                    const: deadair.occasions
                    description: 'Says the file is an occasion pack'
                version:
                    type: integer
                    minimum: 1
                    description: "The version of the document's shape. This station reads version 1"
                name:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'What the pack is, as whoever made it would describe it: `Canadian holidays`'
                occasions:
                    type: array
                    items:
                        type: object
                        additionalProperties: {}
                    maxItems: 500
            required: [format, version, name, occasions]
            description: "A set of occasions as one file, to hand to another station. Each entry is read as an `OccasionPackRow`\nwhen it is imported, so one a station cannot use is reported rather than refusing the file"
        OccasionPackDropped:
            type: object
            properties:
                entry:
                    type: integer
                    minimum: 1
                    readOnly: true
                    description: 'Which entry in the file, counting from 1'
                words:
                    type: string
                    readOnly: true
                    description: 'What it says, when it says'
                reason:
                    type: string
                    readOnly: true
                    description: 'Why the station cannot use it'
            required: [entry, reason]
            description: 'An entry in a file that importing it would leave out, and why'
        OccasionImportPlan:
            type: object
            properties:
                name:
                    type: string
                    readOnly: true
                    description: 'What the file says it is'
                adding:
                    type: array
                    items:
                        type: string
                    readOnly: true
                    description: 'The occasions it would add, by their words'
                skipped:
                    type: array
                    items:
                        type: string
                    readOnly: true
                    description: 'The ones this station already has, with the same words and the same rule, which it would leave alone'
                dropped:
                    type: array
                    items:
                        '$ref': '#/components/schemas/OccasionPackDropped'
                    readOnly: true
                    description: 'The ones it cannot use'
            required: [name, adding, skipped, dropped]
            description: 'What importing a file would do. Everything it adds starts switched off'
        OccasionImportResult:
            type: object
            properties:
                plan:
                    '$ref': '#/components/schemas/OccasionImportPlan'
                    readOnly: true
                list:
                    '$ref': '#/components/schemas/OccasionList'
                    readOnly: true
            required: [plan, list]
            description: 'What an import did, and the list as it now stands'
        ScheduleSlot:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                label:
                    type: string
                    maxLength: 200
                    description: "What the operator calls this stretch of the day. Becomes the broadcast's name"
                startsAtMinutes:
                    type: integer
                    minimum: 0
                    maximum: 1439
                    description: "When it starts, as minutes past midnight on the station's clock"
                endsAtMinutes:
                    type: integer
                    minimum: 0
                    maximum: 1439
                    description: 'When it stops, in the same terms. Before the start means the block runs past midnight, which is ordinary for a late show; equal to it means a full twenty-four hours'
                days:
                    type: array
                    items:
                        type: integer
                        minimum: 0
                        maximum: 6
                    description: 'The weekdays it runs on, Sunday 0. Absent or empty means every day'
                sourcePluginId:
                    type: string
                    maxLength: 200
                    description: 'The plugin the records come from. Absent, with no playlist, is a slot the station fills itself'
                sourcePlaylistId:
                    type: string
                    maxLength: 500
                sourceChartId:
                    type: string
                    maxLength: 400
                    description: 'A published chart to play instead, as `pluginId:chartId`. An ALTERNATIVE to the playlist pair rather than a companion, and it wins if both are sent: a playlist names copies the station can already fetch and a chart names records it has to look up'
                sourceChartOrder:
                    type: string
                    enum: [countdown, ranked, unordered]
                    description: 'Which way round that chart is played. Absent is `countdown`, which ends on number one. Ignored without `sourceChartId`'
                sourceStationPlaylistId:
                    type: string
                    format: uuid
                    description: "A playlist the station owns to play instead, read from the station's own library when the block starts rather than from a provider. An ALTERNATIVE to the playlist pair, which it wins over, and to `sourceChartId`, which wins over it"
                personaId:
                    type: string
                    maxLength: 100
                    description: "Who hosts this stretch of the day. Absent means the station's own active persona"
                brief:
                    type: string
                    maxLength: 500
                    description: "What this stretch of the day is asked to play, in the operator's own words. The same ceiling `PutOnAirInput.brief` has, because a changeover builds one of those from this and the two boxes are one field set on the console"
                eraFrom:
                    type: integer
                    minimum: 1900
                    maximum: 2100
                    description: 'The earliest release year this stretch of the day plays. Absent means no lower bound, and a record whose year the catalog does not know is played whatever the period'
                eraTo:
                    type: integer
                    minimum: 1900
                    maximum: 2100
                    description: 'The latest release year, on the same terms. Set with `eraFrom` for a decade; either may stand alone'
                moods:
                    type: array
                    items:
                        type: string
                        enum: [love, happiness, comfort, sadness, loneliness, anger, fear]
                    maxItems: 4
                    description: "The moods this stretch of the day leans into, as stages in order: the first for its opening stretch, the last for its close, each an equal share of the slot. Records a model has judged to be in the stage's mood are a little more likely to be picked; nothing is ever kept off the air for it. One mood leans the whole slot one way. Absent or empty is no lean"
                avoidMoods:
                    type: array
                    items:
                        type: string
                        enum: [love, happiness, comfort, sadness, loneliness, anger, fear]
                    maxItems: 6
                    description: 'The moods this stretch of the day steers away from, for the whole of it. Records a model has judged to be in one are less likely to be picked, half as likely; nothing is ever kept off the air for it, and a never-play rule is the way to refuse a genre outright. Absent or empty avoids nothing'
                breaks:
                    type: boolean
                    description: "Whether the host talks between the records during this stretch of the day. Absent is the mode's own answer: a `rotation` talks and a `setlist` does not. Set it true on a `setlist` for a chart countdown with a host, which talks as often as the station does while the records play exactly as the setlist has them. A `feature` stays silent whatever this says"
                callins:
                    type: boolean
                    description: 'Whether somebody phones in during this stretch of the day. Absent is no calls, exactly as it is when an operator puts a broadcast on air by hand; a `setlist` or a `feature` takes no calls whatever this says'
                mixInSimilar:
                    type: boolean
                    description: "Whether records that sound like this slot's playlist are mixed in among its records, one every `rotation.mixInEvery` records. Absent leaves the station's own setting standing, exactly as it does when an operator airs a playlist by hand; a slot with no playlist, or a `setlist` or a `feature`, never mixes whatever this says"
                chartPositions:
                    type: boolean
                    description: 'Whether the host says where the chart placed each record it named: "number seven on the Hot 100". Absent is yes, exactly as it is when an operator puts a chart on air by hand. Set it false to air this slot''s chart without its positions read out'
                beds:
                    type: boolean
                    description: "Whether the breaks the station writes during this stretch of the day air over a music bed: one of the library's `bed` recordings scoped to this slot or its host, or else one scoped to nobody. Absent is yes, wherever the library holds a bed for it. False keeps this show's breaks dry. A rewrite that leaves it out keeps what the slot had"
                concerts:
                    type: boolean
                    description: "Whether the host may mention an artist's next show near the station, when the record either side of a break is theirs and a concert plugin knows of one. Absent is no"
                festivalId:
                    type: string
                    format: uuid
                    description: 'The festival this stretch of the day is built around, from `GET /festivals`. Its show plays the acts on the bill and its host may talk about the festival, from what the station holds about it, until its last day. Absent is no festival. Removing the festival clears this'
                requestShow:
                    type: boolean
                    description: 'Whether this stretch of the day is a request show: each listener request placed in it is followed by records that sound like it, in place of what was planned. Absent is no. A `setlist` or a `feature` never has a request followed, since that would throw its own sequence away'
                requestFollowOn:
                    type: integer
                    minimum: 0
                    maximum: 10
                    description: 'How many records follow each request on a request show. Absent is 4. Ignored unless `requestShow` is true'
                repeatWindowDays:
                    type: integer
                    minimum: 0
                    maximum: 365
                    description: "Days a record rests after airing before this stretch of the day may play it again, in place of the station's `rotation.repeatWindowDays`. 0 lifts the window. Absent keeps the mode's own answer: the station's for a `rotation`, none for a `setlist` or a `feature`. A lift never reaches a dislike or a never-play rule"
                artistCooldownMinutes:
                    type: integer
                    minimum: 0
                    maximum: 1440
                    description: "Minutes an artist rests after airing during this stretch of the day, in place of the station's `rotation.artistCooldownMinutes`. 0 lifts the cooldown, which is what an hour of one artist needs first. Absent keeps the mode's own answer, on `repeatWindowDays`' terms"
                maxPerArtist:
                    type: integer
                    minimum: 0
                    maximum: 100
                    description: "Most records by one artist in each batch the station programmes for this stretch of the day, in place of the station's `rotation.maxPerArtist`. 0 lifts the cap. Absent keeps the mode's own answer, on `repeatWindowDays`' terms"
                writerOrder:
                    type: string
                    enum: [model, station]
                    description: "Which writer is asked first for this stretch of the day's breaks, in place of the station's `llm.breakWriterOrder`: `model`, with the station's own words underneath, or `station`, the phrasings, headlines and stories as written with the model underneath. Absent keeps the station's setting. Changes nothing while the model is switched off"
                startsOn:
                    type: string
                    pattern: '^\d{4}-\d{2}-\d{2}$'
                    description: 'The first date this slot runs on, as `YYYY-MM-DD`, which makes it a SPECIAL rather than a weekly slot. On its dates a special takes over from the weekly schedule for its hours, and the weekly show resumes when it ends. Sent with `endsOn` or not at all'
                endsOn:
                    type: string
                    pattern: '^\d{4}-\d{2}-\d{2}$'
                    description: 'The last date it runs on, inclusive. `days` still applies in between, so the Fridays in December are a range and a mask'
                recurrence:
                    '$ref': '#/components/schemas/SpecialRecurrence'
                    description: "The rule that says which day this slot runs on, which makes it a SPECIAL that comes round by itself, in place of `startsOn` and `endsOn`. It runs for its hours on each day the rule falls on the station's calendar, and takes over from the weekly schedule as any special does. Sent with no `days`, since the rule says which day. Rewriting a slot that has a rule without naming its dates or a rule keeps the rule"
                nextDate:
                    type: string
                    minLength: 10
                    maxLength: 10
                    readOnly: true
                    description: "When a slot with a `recurrence` next runs, as `YYYY-MM-DD` on the station's calendar, counting today. Absent on any other slot, and when a list of dates has run out"
                coHosts:
                    type: array
                    items:
                        '$ref': '#/components/schemas/SlotCoHost'
                    maxItems: 8
                    description: "Who presents beside the slot's host, in order: every night, on fixed nights, or as a visitor who turns up at random. At most three are on any one night; a visitor who wins a night that is already full sits it out"
                guestHosts:
                    type: array
                    items:
                        '$ref': '#/components/schemas/SlotGuestHost'
                    maxItems: 8
                    description: "Hosts who sit in for this slot's own host on some nights, in precedence order: the first whose night it is takes it. A guest on fixed nights wins over one at random. Absent or empty is a slot its own host presents every time"
                yearly:
                    type: boolean
                    description: 'Whether the special repeats every year on the same month and day, such as Halloween. Absent is a one-off. A yearly range may run past New Year and must be shorter than a year'
                live:
                    type: boolean
                    description: "Whether this special is a LIVE SHOW: a presenter booked to take the air through the live input. At its start the station arms the input with the special's name, exactly as Go live on the Desk does, and its own programme carries on until the encoder is heard; at its end an input still waiting for anybody is disarmed, and a presenter on the air is never cut. Only a special can be one, and it names no source. Absent is no"
                resumePlaylist:
                    type: boolean
                    description: "Whether a playlist slot picks its playlist up where it left off: each time it opens, it starts with the record after the last one from the playlist that aired, rather than from the top. Absent is no. A record no longer on the playlist starts it from the top again, and so does changing the slot's source. Ignored for a chart or a slot with no playlist"
                shufflePlaylist:
                    type: boolean
                    description: "Whether a playlist slot plays its playlist in a shuffled order rather than the playlist's own. The order is drawn afresh each time the block opens, so an operator's takeover that ends inside the block draws it again. A slot that shuffles does not pick its playlist up where it left off, whatever resumePlaylist says. Absent is no. Ignored for a chart or a slot with no playlist"
                enabled:
                    type: boolean
                    description: 'Whether this slot runs. False keeps it without it ever going on air, and leaves it out of overlap until it is turned back on. Absent on a write leaves it as it is, and is on for a new slot'
                mode:
                    type: string
                    enum: [rotation, setlist, feature]
                onEnd:
                    type: string
                    enum: [extend, repeat, stop]
            required: [id, label, startsAtMinutes, endsAtMinutes, mode, onEnd]
            description: "One stretch of the station's day: from this time, on these days, the station plays this"
        SlotGuestHost:
            type: object
            properties:
                personaId:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Who sits in. A host; a caller or a guest who drops by can never present a show'
                days:
                    type: array
                    items:
                        type: integer
                        minimum: 0
                        maximum: 6
                    description: 'The nights they present, by the weekday the night begins on, Sunday 0. Send this or `everyN`, not both'
                everyN:
                    type: integer
                    minimum: 2
                    maximum: 366
                    description: "Or at random: about one of this slot's nights in this many, on nights nobody can predict. 7 is about one in seven"
                cooldownDays:
                    type: integer
                    minimum: 0
                    maximum: 366
                    description: 'With `everyN`, the fewest days between two of their nights. Absent is half of `everyN`, so even one in seven never lands two nights running'
            required: [personaId]
            description: 'A host who sits in on a slot on some nights, saying whose show it usually is'
        SlotCoHost:
            type: object
            properties:
                personaId:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Who co-presents. A host; a caller or a guest who drops by can never present a show'
                days:
                    type: array
                    items:
                        type: integer
                        minimum: 0
                        maximum: 6
                    description: 'The nights they co-present, by the weekday the night begins on, Sunday 0. Absent with no `everyN` is every night. Send this or `everyN`, not both'
                everyN:
                    type: integer
                    minimum: 2
                    maximum: 366
                    description: "Or as a visitor: about one of this slot's nights in this many, on nights nobody can predict"
                cooldownDays:
                    type: integer
                    minimum: 0
                    maximum: 366
                    description: 'With `everyN`, the fewest days between two of their nights. Absent is half of `everyN`'
            required: [personaId]
            description: "Somebody who presents beside a slot's host, every night or some of them"
        SpecialRecurrence:
            type: object
            properties:
                ruleKind:
                    type: string
                    enum: [fixed, weekday, easter, calendar, dates]
                    description: '`fixed` is the same date every year, from `month` and `day`. `weekday` is the nth of a weekday in a month, from `month`, `ordinal` and `weekday`. `easter` is so many days from Western Easter Sunday, from `offsetDays`. `calendar` is a date in another calendar, from `calendar`, `calendarMonth` and `day`. `dates` is a list of dates, for what none of those can work out'
                month:
                    type: integer
                    minimum: 1
                    maximum: 12
                day:
                    type: integer
                    minimum: 1
                    maximum: 31
                    description: "The day of the month, in the rule's own calendar"
                ordinal:
                    type: integer
                    minimum: -1
                    maximum: 5
                    description: 'Which of that weekday in the month: 1 to 5, or -1 for the last. The fourth Thursday of November is `4`'
                weekday:
                    type: integer
                    minimum: 0
                    maximum: 6
                    description: '0 is Sunday'
                offsetDays:
                    type: integer
                    minimum: -60
                    maximum: 60
                    description: 'Days from Easter Sunday: 0 is the day itself and -2 is Good Friday'
                calendar:
                    type: string
                    enum: [hebrew, islamic-umalqura]
                    description: '`islamic-umalqura` is calculated, so a community going by the sighted moon may keep the day a day either side of it'
                calendarMonth:
                    type: string
                    minLength: 1
                    maxLength: 40
                    description: 'The month in that calendar, as `GET /schedule/occasions` lists them'
                dates:
                    type: array
                    items:
                        type: string
                        minLength: 10
                        maxLength: 10
                    maxItems: 100
                    description: 'As `YYYY-MM-DD`. These run out, so a list needs refreshing'
            required: [ruleKind]
            description: 'Which day a special comes round on. `ruleKind` says how, and which of the fields beside it count'
        ScheduleSlotList:
            type: object
            properties:
                slots:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ScheduleSlot'
                    description: 'What the station runs: every slot that is not switched off'
                switchedOff:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ScheduleSlot'
                    description: 'Slots kept but not running, in the same order. Absent when there are none'
            required: [slots]
        ScheduleTimetableQuery:
            type: object
            properties:
                from:
                    type: string
                    minLength: 10
                    maxLength: 10
                    description: "The first day to draw, as `YYYY-MM-DD` on the station's own calendar. Absent means the station's today, which is the only way a caller that does not know the station's timezone can anchor"
                days:
                    type: integer
                    minimum: 1
                    maximum: 31
                    description: 'How many days from `from`. Defaults to a week'
            description: "A window of the station's day to draw"
        ScheduleTimetable:
            type: object
            properties:
                from:
                    type: string
                    minLength: 10
                    maxLength: 10
                    description: "The range actually drawn, echoed so a caller steps forward and back by adding days to a string rather than by knowing the station's timezone"
                days:
                    type: integer
                    minimum: 1
                    maximum: 31
                occurrences:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ScheduleOccurrence'
            required: [from, days, occurrences]
            description: "The station's day as blocks, ready to draw"
        ScheduleOccurrence:
            type: object
            properties:
                slotId:
                    type: string
                    minLength: 1
                    maxLength: 100
                label:
                    type: string
                    maxLength: 200
                start:
                    type: string
                    minLength: 19
                    maxLength: 19
                    description: "`YYYY-MM-DD HH:mm:ss` on the station's own clock, deliberately carrying no timezone offset: it is a reading rather than a moment, so it draws as written wherever the console is running"
                end:
                    type: string
                    minLength: 19
                    maxLength: 19
                    description: 'The same, exclusive. Every block stays inside one day, so a slot running past midnight arrives as two'
                live:
                    type: boolean
                    description: 'Whether the block is a booked live show, when a presenter is meant to take the air through the live input. Absent is no'
            required: [slotId, label, start, end]
            description: 'One block: this slot, on this day, between these two times'
        ScheduleSlotPart:
            type: string
            enum:
                - name
                - brief
                - era
                - moods
                - avoidMoods
                - rules
                - host
                - coHosts
                - source
                - mode
                - onEnd
            description: "Where a slot that resumes its playlist will pick it up. Empty when it would start from the top: the slot does not resume, has no playlist, has aired nothing from it yet, or the last record it aired is no longer on it\nA part of a slot that applying it to the show on air can change, or has to leave for its next occurrence"
        ScheduleSlotApplied:
            type: object
            properties:
                applied:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ScheduleSlotPart'
                    description: 'The parts the show on air follows from now on. Empty when it already matched the slot'
                waiting:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ScheduleSlotPart'
                    description: 'The parts that differ from the show on air and cannot change mid-show: its source, mode and end make a different programme, and its co-hosts are settled for the night. They apply the next time the slot comes round'
                replanning:
                    type: boolean
                    description: 'Whether the records still planned are being chosen again against the new programme. The ones already planned keep playing until the new set is ready, so nothing goes quiet while it is chosen'
            required: [applied, waiting, replanning]
            description: "What applying a slot to the show on air changed now, and what waits for the slot's next occurrence"
        SlotPlaylistPosition:
            type: object
            properties:
                title:
                    type: string
                    maxLength: 500
                    description: "The record the slot opens on next time, as the playlist names it. The station's rules still apply when it opens, so one it will not play by then is passed over"
                artist:
                    type: string
                    maxLength: 500
                    description: 'Its lead artist'
        ScheduleNow:
            type: object
            properties:
                now:
                    type: string
                    minLength: 19
                    maxLength: 19
                    description: "What time it is on the station's own clock, in the same zone-naive `YYYY-MM-DD HH:mm:ss` shape as a block's ends. It is here so a caller can say how much of the block is left without knowing the station's timezone: subtracting two readings taken in one frame is arithmetic, deriving one is not"
                timezone:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: "The IANA zone the station reads its clock in: `station.timezone`, or the machine's own when that is empty. Optional because a station from before it existed does not send it. For a console showing the station's time beside an operator's own when the two differ, which a zone-naive reading cannot tell it"
                slotId:
                    type: string
                    maxLength: 100
                    description: 'The slot in force at this instant. Absent means the station has no schedule'
                hostPersonaId:
                    type: string
                    maxLength: 100
                    description: "Who presents tonight's night of the slot in force: a guest sitting in, or the slot's own host. Absent when it names nobody, which is the station's own host. Only the night that is ON is answered, so a guest who comes at random stays a surprise until their night begins"
                coHostPersonaIds:
                    type: array
                    items:
                        type: string
                        maxLength: 100
                    maxItems: 3
                    description: "Who presents beside tonight's host on the slot in force, in order. Only the night that is ON is answered, so a visitor stays a surprise until their night begins"
                regularPersonaId:
                    type: string
                    maxLength: 100
                    description: "Whose show it usually is, while a guest sits in on the slot in force. Absent on an ordinary night, and while the station's own host would be the regular one"
                airingSlotId:
                    type: string
                    maxLength: 100
                    description: "The slot the running order actually belongs to. Different from the one above while an operator's own choice holds, which it does until the next slot begins"
                upcoming:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ScheduleOccurrence'
                    description: 'The block on now, if there is one, and the few that follow it, earliest first. Empty for a station with nothing scheduled from here on. A gap is simply absent, exactly as it is on the timetable: what plays there is the sustaining source rather than a block'
            required: [now, upcoming]
            description: 'Which slot the clock says should be on right now, and what follows it'
        SchedulePack:
            type: object
            properties:
                format:
                    const: deadair.schedule
                    description: 'Says the file is a schedule file'
                version:
                    type: integer
                    minimum: 1
                    description: "The version of the document's shape. This station reads version 1"
                name:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'What the file is, as whoever made it would describe it'
                slots:
                    type: array
                    items:
                        type: object
                        additionalProperties: {}
                    maxItems: 500
            required: [format, version, name, slots]
            description: "A schedule as one file, to hand to another station. Each entry is a slot as this API writes it, with\n`personaKey` for `personaId`, `stationPlaylistName` for `sourceStationPlaylistId`, and `personaKey` on each\nco-host and guest host, since an id means nothing elsewhere. Each is read when it is imported, so one a\nstation cannot use is reported rather than refusing the file"
        ScheduleImportResult:
            type: object
            properties:
                plan:
                    '$ref': '#/components/schemas/PackImportPlan'
                    readOnly: true
                list:
                    '$ref': '#/components/schemas/ScheduleSlotList'
                    readOnly: true
            required: [plan, list]
            description: 'What an import did, and the schedule as it now stands'
        SettingGroup:
            type: string
            enum:
                - station
                - stream
                - housekeeping
                - mail
                - signin
                - telemetry
                - rotation
                - breaks
                - bulletins
                - playout
                - render
                - llm
                - analysis
                - schedule
                - personas
                - phrasings
                - providers
            description: "Which part of the console owns a setting. Every one of these but `schedule`, `personas`, `phrasings` and `providers` is a section of the settings page; `schedule` is edited on the schedule page, beside the timetable it describes, `personas` on the characters page, beside the names it stands behind, `phrasings` on the Voice page's Phrasings tab, beside everything else about what the station says, and `providers` on the Providers section, which draws each capability beside the plugins that answer it rather than as a form of text fields."
        StationSettingDescriptor:
            allOf:
                - '$ref': '#/components/schemas/ConfigFieldDescriptor'
                - type: object
                  properties:
                      group:
                          '$ref': '#/components/schemas/SettingGroup'
                  required: [group]
        StationSettings:
            type: object
            properties:
                descriptors:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationSettingDescriptor'
                values:
                    type: object
                    additionalProperties: {}
                    description: 'Every NON-secret setting, with defaults filled in for whatever is not stored'
                configured:
                    type: object
                    additionalProperties:
                        type: boolean
                    description: 'One entry per `secret` setting: whether a value is currently stored. Never the value itself'
                derived:
                    type: object
                    additionalProperties:
                        type: string
                    description: "One entry per setting whose EMPTY value is worked out rather than simply absent: the public URL from the address the station was deployed with, the advertised hostname from the public URL, the station's zone from this machine's, each model setting from the model plugin's own default. Also the sign-in redirect address, for the `note` that shows it, since a note holds no value of its own. What the station WOULD use with the box left empty, which is not the same as what is in force — the stored value is deliberately skipped, so a filled-in field still reports what clearing it would fall back to. A key is absent where its derivation lands on nothing. Values only: where each one comes from is in the field's own help text, which has said so since before this map existed"
            required: [descriptors, values, configured, derived]
            description: 'Every station setting, with what it is currently worth'
        StationSettingsInput:
            type: object
            properties:
                values:
                    type: object
                    additionalProperties: {}
            required: [values]
            description: "A submitted settings form. Partial: a key that is present is written, a key that is absent is left\nalone, so a console may send one field. A secret submitted blank clears it"
        SigninProviderCheck:
            type: object
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "The row's name"
                label:
                    type: string
                    maxLength: 200
                    description: 'What its button says'
                issuer:
                    type: string
                    maxLength: 2000
                    description: 'The issuer that was asked'
                ok:
                    type: boolean
                    description: 'Whether the issuer answered with a discovery document naming itself'
                problem:
                    type: string
                    maxLength: 2000
                    description: 'Why not, in a sentence. Absent when it answered'
            required: [name, label, issuer, ok]
            description: 'One identity provider row, and whether its issuer answered as one'
        SigninProvidersCheck:
            type: object
            properties:
                providers:
                    type: array
                    items:
                        '$ref': '#/components/schemas/SigninProviderCheck'
                    description: 'In the order the rows are listed'
                unusable:
                    type: array
                    items:
                        type: string
                        maxLength: 2000
                    description: 'One sentence per row the station drops before asking anybody: a missing cell, a name that is not a slug, an issuer that is not an address'
            required: [providers, unusable]
            description: 'Every identity provider row the station could read, and the ones it could not use at all'
        InvitationPreviewQuery:
            type: object
            properties:
                role:
                    type: string
                    enum: [listener, admin]
                    description: "The role the invitation would be for. Its subject, its guide link and the station's own wording differ between the two"
            required: [role]
            description: 'Which invitation to preview'
        InvitationPreview:
            type: object
            properties:
                subject:
                    type: string
                    maxLength: 2000
                    description: 'The subject line'
                html:
                    type: string
                    maxLength: 500000
                    description: 'The whole HTML part, as a document'
                text:
                    type: string
                    maxLength: 500000
                    description: 'The plain-text part'
                ownWording:
                    type: boolean
                    description: "Whether the station's saved subject or message was used. False when neither is set, or when what is saved cannot be used and the station's own wording is shown instead"
                problem:
                    type: string
                    maxLength: 2000
                    description: 'Why the saved wording cannot be used, in a sentence. Absent when it can, or when nothing is saved'
            required: [subject, html, text, ownWording]
            description: 'An invitation as it would be emailed now, with a sample link, inviter and date in place of a real one'
        Pagination:
            type: object
            properties:
                page:
                    type: integer
                    minimum: 0
                    default: 0
                    description: 'The page number'
                pageSize:
                    type: integer
                    minimum: 1
                    maximum: 100
                    default: 25
                    description: 'The page size'
                sort:
                    type: string
                    enum: [asc, desc]
                    default: desc
                    description: 'The sort order'
                total:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'The total number of items'
            required: [page, pageSize, sort, total]
            description: 'Represents a pagination object'
        PaginationWithActive:
            allOf:
                - '$ref': '#/components/schemas/Pagination'
                - type: object
                  properties:
                      active:
                          type: boolean
                          description: 'Optionally filter by whether the items are active'
        LogLevel:
            type: string
            enum: [trace, debug, info, warn, error]
            description: "Five values, where `PluginLogLevel` next door has four. The plugin enum is the narrower one on\npurpose — that is the vocabulary a plugin's own `PluginLogger` offers — while `api.log` is written\nby `DeadairLogger`, which tees every level the app-wide `Logger` has, `trace` included. Narrowing\nhere would make a `trace` line unrepresentable in the type of the surface that reads the file it\nis in."
        LogSource:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 40
                    description: 'A closed set the API owns: `api`, `liquidsoap`, `shim`. Never a path'
                label:
                    type: string
                    minLength: 1
                    maxLength: 80
                description:
                    type: string
                    maxLength: 300
                    description: 'What writes it, in a sentence, because "shim" means nothing to somebody who has not read the tree'
                present:
                    type: boolean
                    description: 'Whether the file is there at all. A station that never ran the stream has no stream logs, which is a state rather than a fault'
                levels:
                    type: boolean
                    description: 'Whether its lines carry a level, so the console knows whether to offer the filter'
                bytes:
                    type: integer
                    minimum: 0
                    description: 'Retained size across every segment. Zero when absent'
                lastWriteAt:
                    type: string
                    format: date-time
                    description: 'Absent when nothing has ever been written'
            required: [id, label, description, present, levels, bytes]
            description: 'One log file this install has, whether or not anything has been written to it'
        LogSourceList:
            type: object
            properties:
                sources:
                    type: array
                    items:
                        '$ref': '#/components/schemas/LogSource'
                    description: 'Every source, in a fixed order, including the ones that are not present'
            required: [sources]
        LogLine:
            type: object
            properties:
                ts:
                    type: string
                    maxLength: 40
                    description: 'Absent on a line this API did not write, and on one of its own that did not parse'
                level:
                    '$ref': '#/components/schemas/LogLevel'
                    description: 'Absent for the same two reasons'
                text:
                    type: string
                    maxLength: 65536
                    description: 'Must match MAX_LINE_BYTES_CEILING in apps/api/src/logging/rotating.log.store.ts. Change both together'
            required: [text]
            description: 'One line, as far as it could be read back'
        LogPage:
            type: object
            properties:
                sourceId:
                    type: string
                    minLength: 1
                    maxLength: 40
                level:
                    '$ref': '#/components/schemas/LogLevel'
                    description: 'The minimum severity that was applied. Absent when the source carries no levels, so a filter that did nothing cannot look as though it worked'
                truncated:
                    type: boolean
                    description: "Whether the read hit its byte budget, so the oldest line here is not the file's first"
                lines:
                    type: array
                    items:
                        '$ref': '#/components/schemas/LogLine'
                    description: 'Newest first, as the plugin log page, the activity feed and the script history all send'
            required: [sourceId, truncated, lines]
        LogQuery:
            type: object
            properties:
                limit:
                    type: integer
                    minimum: 1
                    maximum: 2000
                level:
                    '$ref': '#/components/schemas/LogLevel'
                    description: 'Ignored by a source whose lines carry no level'
        AttentionEvidence:
            type: object
            properties:
                label:
                    type: string
                    minLength: 1
                    maxLength: 300
                    description: "The thing itself, as an operator would name it: a record's title and who made it"
                reason:
                    type: string
                    minLength: 1
                    maxLength: 600
                    description: "Why THIS one, in the station's own sentence. The row's `detail` says what the category means; this says what happened here"
                route:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The page holding the whole of it. Absent where there is no page for it, which the running order can hold: a record the catalog never ingested has none'
            required: [label, reason]
            description: "One concrete thing an attention row is about, so the reason does not live a page away.\n\nThe row above it counts and categorises; this names. \"4 records have no copy left that will play\"\nis a category an operator can do nothing with until they know WHICH four and WHY each one, and\nevery one of those facts was already stored — the fetch error on `track_audio.last_error`, the\nprovider's refusal on `track_sources.playable` — and reachable only by finding the record and\nhovering a cell on its page. This is that fact travelling with the row that counted it."
        AttentionItem:
            type: object
            properties:
                code:
                    type: string
                    minLength: 1
                    maxLength: 60
                    description: 'What this is, as a stable key: `silence`, `benchedCopies`, `noPersona`. The console groups and counts on it rather than on the sentence'
                severity:
                    type: string
                    enum: [failure, warning, notice]
                    description: '`failure` is the station not doing its job, `warning` is something failing beside a station that is working, and `notice` is a thing nobody has set up yet. A notice is not a fault and must not be drawn as one'
                title:
                    type: string
                    minLength: 1
                    maxLength: 120
                    description: 'The line an operator reads first'
                detail:
                    type: string
                    minLength: 1
                    maxLength: 800
                    description: 'The whole of it, in a sentence. Where the station already has words for a fact, these are those words rather than a second phrasing of them'
                route:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The console page that can do something about it'
                count:
                    type: integer
                    minimum: 0
                    description: 'How many things this is about, where that is a number rather than a state'
                dismissible:
                    type: boolean
                    description: 'The operator may accept this row as it stands, through `POST /station/attention/{code}/dismiss`. It comes back by itself when something new joins it. Absent on a row that only goes away when its cause does'
                evidence:
                    type: array
                    items:
                        '$ref': '#/components/schemas/AttentionEvidence'
                    description: 'A HANDFUL of the things this row is about, never all of them: this answer is polled and a row about four hundred records must not be four hundred sentences. `count` stays the true figure, and a console showing fewer than it says so'
            required: [code, severity, title, detail, route]
            description: "One thing that wants the operator's attention, or the fact that nothing does"
        StationAttention:
            type: object
            properties:
                items:
                    type: array
                    items:
                        '$ref': '#/components/schemas/AttentionItem'
            required: [items]
            description: 'Everything wrong or waiting, worst first'
        StationHeartbeat:
            type: object
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                startedAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When the loop registered, which is when it was last (re)started'
                lastBeat:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When it last completed a pass. Absent until it completes its first'
            required: [name, startedAt]
            description: "One loop the station runs, and when it last came round.\n\nTwo timestamps and no verdict, because the loop cannot supply one: a five-second reconcile and a\nnightly sweep are both healthy and no single threshold describes both. `Heartbeat` itself takes\nthis position — it answers how long it has been and lets the reader decide — and a `stalled`\nboolean here would be this module inventing the threshold that file deliberately refuses to.\n\n`lastBeat` is absent until a loop finishes its first pass, which is why `startedAt` is there: from\nthe two of them a reader can tell a loop that has never completed anything from one that stopped."
        StationBacklog:
            type: object
            properties:
                total:
                    type: integer
                    minimum: 0
                    readOnly: true
                cached:
                    type: integer
                    minimum: 0
                    readOnly: true
                measured:
                    type: integer
                    minimum: 0
                    readOnly: true
            required: [total, cached, measured]
            description: "How much of the library the station has actually looked at.\n\nThe counts `/catalog/tracks` already answers with, lifted out of a page of rows: a check-up wants\nthe sentence \"13 of 581 measured\" without asking for thirteen tracks to get it."
        StationModelHolder:
            type: object
            properties:
                priority:
                    type: string
                    enum: [breaking, air, background, preview]
                    readOnly: true
                    description: 'Whose work it is: `breaking` and `air` have a deadline, `background` (a refill, a production) does not, `preview` is an operator trying something'
                heldSince:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When it took the slot. Every generation is bounded at ten minutes, so a holder older than that is a stream that stopped arriving'
                plugin:
                    type: string
                    minLength: 1
                    maxLength: 200
                    readOnly: true
                    description: 'The model plugin answering it'
            required: [priority, heldSince]
            description: "Who has the station's one model slot, and how many are waiting for it.\n\nThe model is shared by every break, every programme refill and every production, one generation at\na time, so a slot held for far longer than any generation takes is the station's ability to speak\nstuck behind one answer. Nothing else exposes it."
        StationModel:
            type: object
            properties:
                waiting:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Callers queued behind whoever holds the slot'
                holder:
                    '$ref': '#/components/schemas/StationModelHolder'
                    readOnly: true
                    description: 'Absent while the model is free'
            required: [waiting]
            description: 'The model slot and its queue'
        StationCheckup:
            type: object
            properties:
                readAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When this reading was taken, so a stale page cannot pass itself off as now'
                revision:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                    description: "The commit this station was built from, as the image's `org.opencontainers.image.revision` label says it. Unlike the sections below, absent is not a failed reader: it means nothing stamped this build, which is what a development tree and a hand-built image both are"
                version:
                    type: string
                    minLength: 1
                    maxLength: 50
                    readOnly: true
                    description: "The release this station is, as the image's `org.opencontainers.image.version` label says it. Absent on the same terms as `revision` and for a second reason: only a tagged build carries one, so a station following `latest` reports a commit and no version"
                heartbeats:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationHeartbeat'
                    readOnly: true
                backlog:
                    '$ref': '#/components/schemas/StationBacklog'
                    readOnly: true
                model:
                    '$ref': '#/components/schemas/StationModel'
                    readOnly: true
            required: [readAt]
            description: "One reading of the machinery, for a page that assembles the station's health.\n\nIt carries ONLY the signals nothing else exposes. Everything else a check-up shows — the\nsilence verdict, the listener count, what needs somebody, the plugin statuses, the disk — is\nalready on a contract the console reads, and composing them again here would be a second answer\nthat can disagree with the first. `/playout/status` in particular is polled every two seconds for\nthe transport strip, so asking for it a second way would be a second reading of the same fact.\n\nEach section is OPTIONAL and absent means that reader failed. A page saying what is wrong is the\nworst place for one broken reader to take the whole answer down, which is the rule\n`StationAttentionService` already works to. `revision` is the one exception and says so on its\nown line: it cannot fail, so absent there means something else.\n\nThe revision is on THIS contract rather than composed from `/health`, which also reports it, and\nthat is not the second-answer problem the paragraph above describes. Both read one string from one\nplace at boot, so they cannot disagree. What they differ in is who can reach them: `/health` is\n`operation(internal)`, deliberately, so it generates no SDK method and the console cannot call it\n— which would leave \"which build is this\" answerable only from a shell, the one thing carrying it\nhere exists to fix."
        StationRelease:
            type: object
            properties:
                version:
                    type: string
                    minLength: 1
                    maxLength: 50
                    readOnly: true
                    description: 'The release, as its tag names it without the leading `v`'
                date:
                    type: string
                    format: date
                    readOnly: true
                    description: 'The day it went out. Absent where the entry named none'
                notes:
                    type: string
                    maxLength: 40000
                    readOnly: true
                    description: 'What changed, as the Markdown of its changelog entry. Empty for a release that recorded nothing'
                url:
                    type: string
                    format: uri
                    readOnly: true
                    description: "The release's page on GitHub. Present on a release this station does not contain yet, which is where its notes came from"
            required: [version, notes]
            description: 'One release of the station, in the words its changelog entry used'
        StationReleases:
            type: object
            properties:
                current:
                    type: string
                    minLength: 1
                    maxLength: 50
                    readOnly: true
                    description: 'The newest release this build contains, read off the changelog it was built with. Present on a build that follows `main` too, where `version` on the check-up is absent: every build carries the entry of the last release merged before it. Absent only when the build carries no changelog to read'
                notes:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationRelease'
                    readOnly: true
                    description: 'Every release this build contains, newest first'
                checks:
                    type: boolean
                    readOnly: true
                    description: 'Whether the station asks GitHub for newer releases, which the operator switches under Settings, Station'
                checkedAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'When GitHub last answered. Absent until it has, and while the check is switched off'
                available:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StationRelease'
                    readOnly: true
                    description: 'Releases newer than this build, newest first, each with its notes and its page. Empty when there are none, while the check is off, and until GitHub has answered'
            required: [notes, checks, available]
            description: 'What this build is, and what changed in it'
        TraceOutcome:
            type: string
            enum: [ok, failed]
            description: "Whether a call produced what it was asked for. Two values on purpose: every finer distinction —\ntimed out, was preempted, came back empty — is a fact the caller knew and the recorder did not, so\nit lives in `detail` where it can be named"
        TraceSpan:
            type: object
            properties:
                at:
                    type: string
                    format: date-time
                    description: 'When the call ended, which is when its cost was known'
                op:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Dotted and stable: `job.run`, `plugin.invoke`, `llm.generate`'
                target:
                    type: string
                    maxLength: 300
                    description: 'Which one: a plugin and its method, or a model'
                ms:
                    type: integer
                    minimum: 0
                    description: 'How long it held, measured around the call rather than reported by it'
                outcome:
                    '$ref': '#/components/schemas/TraceOutcome'
                error:
                    type: string
                    maxLength: 300
                    description: 'The failure, summarized to a shape rather than a stack'
                detail:
                    type: object
                    additionalProperties: {}
                    description: 'Whatever this `op` is worth reading back: tokens, a finish reason, the bound it was given'
            required: [at, op, ms, outcome]
            description: 'One call inside a decision, and what it cost'
        TraceDecision:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "The job id or the request id. Already the station's correlation id, never generated for this"
                kind:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'A queue name, or a method and path'
                parent:
                    type: string
                    maxLength: 200
                    description: 'The decision that enqueued this one. Absent on a request, a cron job and anything at boot'
                at:
                    type: string
                    format: date-time
                    description: 'When its first recorded call ended'
                ms:
                    type: integer
                    minimum: 0
                    description: 'Wall clock, off the `job.run` span. Zero for a decision recorded before that span existed'
                calls:
                    type: integer
                    minimum: 0
                    description: 'Everything it did, not counting the `job.run` that contains them'
                failed:
                    type: integer
                    minimum: 0
                    description: 'How many of those did not produce what they were asked for'
            required: [id, kind, at, ms, calls, failed]
            description: 'One decision, folded: a job execution or a request'
        TracesQuery:
            type: object
            properties:
                limit:
                    type: integer
                    minimum: 1
                    maximum: 200
                kind:
                    type: string
                    maxLength: 200
                    description: 'An exact queue name or route, for reading one kind of decision on its own'
                failedOnly:
                    type: boolean
                    description: 'Only decisions carrying at least one failed call'
            description: 'Which slice of the kept window to read'
        TracesPage:
            type: object
            properties:
                decisions:
                    type: array
                    items:
                        '$ref': '#/components/schemas/TraceDecision'
                    description: 'Newest first'
                total:
                    type: integer
                    minimum: 0
                    description: 'How many the window holds before `limit`, so a page can say it is showing a slice'
                spans:
                    type: integer
                    minimum: 0
                    description: 'How many calls were read to answer, which is the honest cost of this page'
            required: [decisions, total, spans]
        TraceDetail:
            type: object
            properties:
                decision:
                    '$ref': '#/components/schemas/TraceDecision'
                spans:
                    type: array
                    items:
                        '$ref': '#/components/schemas/TraceSpan'
                    description: 'In the order they happened'
                parent:
                    '$ref': '#/components/schemas/TraceDecision'
                    description: 'What enqueued this, when that decision is still inside the kept window'
                caused:
                    type: array
                    items:
                        '$ref': '#/components/schemas/TraceDecision'
                    description: 'What this one went on to enqueue'
            required: [decision, spans, caused]
            description: 'One decision, its calls, and the decisions on either side of it'
        StorageStoreId:
            type: string
            enum: [tracks, art, segments, voices, archive]
            description: 'Which store, as a stable id the console can key off rather than a name it renders.'
        StorageStore:
            type: object
            properties:
                id:
                    '$ref': '#/components/schemas/StorageStoreId'
                    readOnly: true
                label:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                    description: 'What to call it on a page'
                path:
                    type: string
                    minLength: 1
                    maxLength: 1000
                    readOnly: true
                    description: 'Where it is, so `du` and this can be compared'
                files:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Files actually there'
                bytes:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'What they weigh'
                rows:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Rows pointing at a file. Absent when no table backs this store'
                accountedBytes:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'What those rows say those files weigh. Absent where the table does not record a size'
                capBytes:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'The limit an operator set, where the store has one. Absent means no limit'
                orphanFiles:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Files no row claims. Reported and never cleaned up automatically'
                orphanBytes:
                    type: integer
                    minimum: 0
                    readOnly: true
                rowsWithNoFile:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'Claims whose file is not there. The station re-fetches or re-renders these'
            required: [id, label, path, files, bytes, orphanFiles, orphanBytes, rowsWithNoFile]
            description: "One content store: what is on disk, and what the database says should be.\n\nThe two halves are deliberately separate numbers rather than one reconciled figure. They disagree\nin two directions and each direction means something different — a file nothing claims is what a\ncrash between writing bytes and writing a row leaves behind, and a row whose file is gone is what\nan operator emptying a directory leaves. Reporting one number would hide both."
        StorageReport:
            type: object
            properties:
                readAt:
                    type: string
                    format: date-time
                    readOnly: true
                totalFiles:
                    type: integer
                    minimum: 0
                    readOnly: true
                totalBytes:
                    type: integer
                    minimum: 0
                    readOnly: true
                stores:
                    type: array
                    items:
                        '$ref': '#/components/schemas/StorageStore'
            required: [readAt, totalFiles, totalBytes, stores]
            description: "Every store, plus the number an operator actually wants first.\n\n`readAt` is not decoration: the figures come from walking directories, which is real I/O on a\nstation holding tens of thousands of files, so the answer is cached for a short while and this is\nwhat stops a page mistaking it for live."
        RecordingKind:
            type: string
            enum: [live, hour]
            description: "What a recording holds: a live show, or an hour of the station's own programme."
        Recording:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 64
                    readOnly: true
                    description: 'Names the recording, e.g. `2026-10-27T21-03-12-live`'
                kind:
                    '$ref': '#/components/schemas/RecordingKind'
                    readOnly: true
                title:
                    type: string
                    maxLength: 200
                    readOnly: true
                    description: "The show's name, for a live show armed with one"
                startedAt:
                    type: string
                    format: date-time
                    readOnly: true
                endedAt:
                    type: string
                    format: date-time
                    readOnly: true
                    description: 'Absent while it is still being recorded'
                bytes:
                    type: integer
                    minimum: 0
                    readOnly: true
                recording:
                    type: boolean
                    readOnly: true
                    description: 'Still being written. It cannot be deleted until it ends'
                audioUrl:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    readOnly: true
                    description: 'Where a player can stream it from, signed for a while so an audio element needs no token. Relative to the API'
            required: [id, kind, startedAt, bytes, recording, audioUrl]
            description: "One file in the station's archive of what it aired."
        RecordingList:
            type: object
            properties:
                mode:
                    type: string
                    enum: ['off', live, all]
                    readOnly: true
                    description: 'What the archive is set to keep'
                retentionDays:
                    type: integer
                    minimum: 0
                    readOnly: true
                    description: 'How long a finished recording is kept. Zero keeps all of them'
                recordings:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Recording'
            required: [mode, retentionDays, recordings]
            description: 'Every recording, newest first, and whether the station is recording at all.'
        ListenerConnection:
            type: object
            properties:
                via:
                    type: string
                    enum: [icecast, hls]
                    description: '`icecast` is a player holding a connection open on a mount. `hls` is a player re-fetching a playlist, counted while it keeps asking'
                mount:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The Icecast mount it is on, such as `/live.mp3`. Absent over HLS, whose players are counted across every playlist together'
                address:
                    type: string
                    minLength: 1
                    maxLength: 64
                    description: "The address the station recorded. A listener's own only where the edge in front of the station is trusted to say so; behind a tunnel without `REAL_IP_FROM` it is the tunnel's"
                agent:
                    type: string
                    minLength: 1
                    maxLength: 512
                    description: 'What the player said it was, cut to 512 characters. Absent when it sent nothing'
                connectedMs:
                    type: integer
                    minimum: 0
                    description: 'How long it has been connected, to the second. Over HLS, since the first playlist fetch of this stretch of listening'
            required: [via, address, connectedMs]
            description: "One connection to the station's stream, as it stands at the moment of reading"
        UnreadableMount:
            type: object
            properties:
                mount:
                    type: string
                    minLength: 1
                    maxLength: 200
                reason:
                    type: string
                    enum: [unresolved, refused, unanswered]
                    description: '`unresolved`: the station has not yet found an Icecast 2.5 it can ask. `refused`: Icecast answered 401 or 403. `unanswered`: a timeout, a failed connection, or a reply that was not a client list'
            required: [mount, reason]
            description: 'An Icecast mount whose connections could not be read, so its listeners are missing from the list'
        StreamListeners:
            type: object
            properties:
                readAt:
                    type: string
                    format: date-time
                    description: 'When this was read'
                total:
                    type: integer
                    minimum: 0
                    description: "The audience count the station is acting on, the same figure as the console's tally. It can differ from the number of connections: it is kept by a separate reading, and one HLS entry can stand for two players with the same address and agent"
                connections:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ListenerConnection'
                    description: "Every connection that could be read, Icecast mounts first in the station's mount order, then HLS, each longest-connected first"
                unreadable:
                    type: array
                    items:
                        '$ref': '#/components/schemas/UnreadableMount'
                    description: 'The mounts that could not be read. Empty when every one was. A mount listed here is not an empty mount'
            required: [readAt, total, connections, unreadable]
            description: "Who is connected to the station's stream right now. Read on request and never stored"
        FetcherAuthorization:
            type: object
            properties:
                reachable:
                    type: boolean
                    description: 'Whether the fetcher answered at all. False makes every field below a default rather than a reading, so a fetcher that is merely down is never reported as one that was never authorized'
                configured:
                    type: boolean
                    description: 'Whether this install has a stream half yet. False means there is nothing here to authorize'
                authorized:
                    type: boolean
                    description: "Whether the fetcher holds its OWN stored authorization, which is the only kind Spotify's login accepts. False with a healthy plugin above it is a station that lists playlists perfectly and cannot fetch a single record"
                session:
                    type: boolean
                    description: 'Whether a login is established right now'
                loginError:
                    type: string
                    maxLength: 500
                    description: 'The last reason a login was refused. Present is not the same as fatal: a session may have recovered since'
                audioKeysRefused:
                    type: integer
                    minimum: 1
                    description: 'How many fetches in a row Spotify has refused the audio key for, once that is a run rather than a moment. Absent otherwise. The login is fine throughout, so nothing else here shows it, and a new authorization only helps if it is for a different account'
                pendingUrl:
                    type: string
                    maxLength: 2000
                    description: 'An authorization already started and not yet finished, so an operator who lost the URL is given it back rather than having to start again'
                callbackUrl:
                    type: string
                    maxLength: 2000
                    description: 'The address the browser will be sent to and will not be able to load. Reported so the console can say which page is expected to fail, rather than leaving that looking like a fault. Absent when the fetcher did not answer, since it is the only thing that knows it'
            required: [reachable, configured, authorized, session]
            description: "What the station's track fetcher holds by way of a Spotify login"
        FetcherAuthorizationStart:
            type: object
            properties:
                authorizeUrl:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: 'The Spotify consent page, to be opened by the operator'
                expiresInMs:
                    type: integer
                    minimum: 0
                    description: 'How long this URL is good for. Starting another replaces it'
            required: [authorizeUrl, expiresInMs]
            description: 'An authorization to open in a browser'
        FetcherAuthorizationInput:
            type: object
            properties:
                redirectUrl:
                    type: string
                    minLength: 1
                    maxLength: 2000
                    description: 'The address the browser ended up at, pasted whole. Taken apart by the fetcher rather than here, because two readings of one address is one of them being wrong eventually'
            required: [redirectUrl]
            description: 'The callback the browser could not deliver, handed over by the operator instead'
        FetcherAuthorizationFinished:
            type: object
            properties:
                username:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The Spotify account that was authorized. Reported because an operator with two accounts in two browser profiles wants to know which one this station now is'
            required: [username]
            description: 'Which account the station now fetches as'
        Topic:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    maxLength: 100
                    readOnly: true
                kind:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'Which sort of break this is a subject for, as `segments.kind` spells it'
                key:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'A stable slug, unique within its kind. What the format clock points a band at and what a seeded topic is recognised by'
                label:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'What a break calls it out loud, so it is the phrasing you would want to hear'
                config:
                    type: object
                    additionalProperties: {}
                    description: "This sort of break's own settings for this subject, in the fields its kind declares. Nothing generic reads them"
                position:
                    type: integer
                    minimum: 0
                    description: 'Your own order, for the list. Two subjects never contest anything, so it means nothing else'
            required: [id, kind, key, label, config, position]
            description: "What a break can be about: a news category, and later a weather location. The operator's own vocabulary, per sort of break"
        TopicList:
            type: object
            properties:
                topics:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Topic'
            required: [topics]
        TopicKindDescriptor:
            type: object
            properties:
                kind:
                    type: string
                    minLength: 1
                    maxLength: 100
                nounOne:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'What to call one of these: a news subject is a category and a weather subject is a location'
                nounMany:
                    type: string
                    minLength: 1
                    maxLength: 100
                description:
                    type: string
                    maxLength: 2000
                fields:
                    type: array
                    items:
                        '$ref': '#/components/schemas/ConfigFieldDescriptor'
            required: [kind, nounOne, nounMany, description, fields]
            description: "A sort of break that has subjects at all, and how one of its subjects is edited. `ConfigFieldDescriptor` is the plugins area's, shared for the reason a station setting shares it: one form component renders them all"
        TopicKindList:
            type: object
            properties:
                kinds:
                    type: array
                    items:
                        '$ref': '#/components/schemas/TopicKindDescriptor'
            required: [kinds]
        TopicQuery:
            type: object
            properties:
                kind:
                    type: string
                    maxLength: 100
                    description: 'One sort of break, or absent for every subject this station has named'
        TopicPack:
            type: object
            properties:
                format:
                    const: deadair.topics
                    description: 'Says the file is a topics file'
                version:
                    type: integer
                    minimum: 1
                    description: "The version of the document's shape. This station reads version 1"
                name:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'What the file is, as whoever made it would describe it'
                topics:
                    type: array
                    items:
                        type: object
                        additionalProperties: {}
                    maxItems: 1000
            required: [format, version, name, topics]
            description: "A station's subjects as one file, to hand to another station. Each entry is read as a `TopicPackRow`\nwhen it is imported, so one a station cannot use is reported rather than refusing the file"
        PackImportDropped:
            type: object
            properties:
                entry:
                    type: integer
                    minimum: 1
                    readOnly: true
                    description: 'Which entry in the file, counting from 1'
                words:
                    type: string
                    readOnly: true
                    description: 'What the entry calls itself, when it does'
                reason:
                    type: string
                    readOnly: true
                    description: 'Why the station cannot use it'
            required: [entry, reason]
            description: 'An entry in a file that importing it would leave out, and why'
        PackImportNotice:
            type: object
            properties:
                kind:
                    type: string
                    readOnly: true
                    description: 'What sort of notice, for a caller that treats one differently'
                message:
                    type: string
                    readOnly: true
            required: [kind, message]
            description: "Something to know about a file that does not stop it being imported, in the station's own sentence"
        PackImportPlan:
            type: object
            properties:
                name:
                    type: string
                    readOnly: true
                    description: 'What the file says it is'
                adding:
                    type: array
                    items:
                        type: string
                    readOnly: true
                    description: 'What it would add, in the words a list would show'
                skipped:
                    type: array
                    items:
                        type: string
                    readOnly: true
                    description: 'What this station already has, which it would leave alone'
                dropped:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PackImportDropped'
                    readOnly: true
                    description: 'What it cannot use'
                notices:
                    type: array
                    items:
                        '$ref': '#/components/schemas/PackImportNotice'
                    readOnly: true
            required: [name, adding, skipped, dropped, notices]
            description: 'What importing a file would do. The preview and the import reach it the same way, so what an operator was shown is what happens'
        TopicImportResult:
            type: object
            properties:
                plan:
                    '$ref': '#/components/schemas/PackImportPlan'
                    readOnly: true
                list:
                    '$ref': '#/components/schemas/TopicList'
                    readOnly: true
            required: [plan, list]
            description: 'What an import did, and the subjects as they now stand'
        InvitationState:
            type: string
            enum: [pending, accepted, revoked, expired]
            description: 'Where an invitation stands. `expired` is a pending invitation whose time ran out'
        Invitation:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    description: "The invitation's id"
                email:
                    type: string
                    maxLength: 320
                    description: 'The address the account will have. The person cannot change it while accepting'
                role:
                    '$ref': '#/components/schemas/PlatformRole'
                    description: 'The role the account will hold'
                state:
                    '$ref': '#/components/schemas/InvitationState'
                    description: 'Where it stands'
                createdAt:
                    type: string
                    format: date-time
                    description: 'When it was made'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When the link stops working, if nobody has used it'
                invitedBy:
                    type: string
                    maxLength: 320
                    description: 'The address of the admin who made it. Absent once their account is gone'
                acceptedAt:
                    type: string
                    format: date-time
                    description: 'When somebody accepted it'
                revokedAt:
                    type: string
                    format: date-time
                    description: 'When it was withdrawn, by an admin or by a newer invitation to the same address'
                token:
                    type: string
                    maxLength: 200
                    description: "The invitation itself, only while it is pending. Put it after `#` on the station's `/invite` page, as `/invite#<token>`. Anyone holding it can claim the account, so show it only to the person invited"
            required: [id, email, role, state, createdAt, expiresAt]
            description: 'An invitation for somebody to take an account on the station'
        InvitationList:
            type: object
            properties:
                data:
                    type: array
                    items:
                        '$ref': '#/components/schemas/Invitation'
            required: [data]
            description: "The station's invitations, newest first"
        InvitationCreate:
            type: object
            properties:
                email:
                    type: string
                    format: email
                    description: 'The address the account will have'
                role:
                    '$ref': '#/components/schemas/PlatformRole'
                    description: 'The role the account will hold'
                send:
                    type: boolean
                    description: 'Email the link to the address too. Refused with a 503, and nothing made, when the station has no mail server'
            required: [email, role]
            description: 'Invite somebody by their address'
        InvitationToken:
            type: object
            properties:
                token:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: 'The token'
            required: [token]
            description: "An invitation's link token, as it appears after `#` on the invite page"
        InvitationDetails:
            type: object
            properties:
                email:
                    type: string
                    maxLength: 320
                    description: 'The address the account will have'
                role:
                    '$ref': '#/components/schemas/PlatformRole'
                    description: 'The role it will hold'
                stationName:
                    type: string
                    description: 'What the station calls itself'
                expiresAt:
                    type: string
                    format: date-time
                    description: 'When the link stops working'
            required: [email, role, stationName, expiresAt]
            description: 'What an open invitation is for, shown to the person before they accept'
        InvitationSecondStep:
            type: string
            enum: [authenticator, fido]
            description: 'How the person will prove it is them after their password: an authenticator app, or a passkey'
        InvitationAcceptStart:
            type: object
            properties:
                token:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "The invitation's token"
                password:
                    type: string
                    minLength: 8
                    maxLength: 256
                    description: 'The password the account will have. Refused here if it is too weak, so the person learns before setting anything else up'
                method:
                    '$ref': '#/components/schemas/InvitationSecondStep'
                    description: 'The second step to set up'
            required: [token, password, method]
            description: 'Choose a password and a second step. Nothing is saved yet'
        InvitationAuthenticatorSetup:
            type: object
            properties:
                method:
                    const: authenticator
                    description: Discriminator
                registrationId:
                    type: string
                    description: 'Send this back with the first code'
                secret:
                    type: string
                    description: 'The key, for an app that cannot scan'
                uri:
                    type: string
                    description: 'The `otpauth://` address the QR code holds'
                qrCode:
                    type: string
                    description: 'The QR code, as a data URL'
            required: [method, registrationId, secret, uri, qrCode]
            description: 'An authenticator app to scan, for an invitation being accepted'
        InvitationPasskeySetup:
            type: object
            properties:
                method:
                    const: fido
                    description: Discriminator
                registrationId:
                    type: string
                    description: 'Send this back with the credential'
                attestation:
                    '$ref': '#/components/schemas/FidoFactorAttestation'
                    description: 'What to hand `navigator.credentials.create`'
            required: [method, registrationId, attestation]
            description: 'A passkey to make, for an invitation being accepted'
        InvitationAcceptStartResponse:
            oneOf:
                - '$ref': '#/components/schemas/InvitationAuthenticatorSetup'
                - '$ref': '#/components/schemas/InvitationPasskeySetup'
            discriminator:
                propertyName: method
                mapping:
                    authenticator: '#/components/schemas/InvitationAuthenticatorSetup'
                    fido: '#/components/schemas/InvitationPasskeySetup'
        InvitationAcceptWithAuthenticator:
            type: object
            properties:
                method:
                    const: authenticator
                    description: Discriminator
                token:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "The invitation's token"
                password:
                    type: string
                    minLength: 8
                    maxLength: 256
                    description: 'The same password as at the start'
                registrationId:
                    type: string
                    description: 'From the start'
                code:
                    type: string
                    minLength: 6
                    maxLength: 10
                    description: 'The first code the app shows'
            required: [method, token, password, registrationId, code]
            description: 'Accept with the first code from the authenticator app'
        InvitationAcceptWithPasskey:
            type: object
            properties:
                method:
                    const: fido
                    description: Discriminator
                token:
                    type: string
                    minLength: 1
                    maxLength: 200
                    description: "The invitation's token"
                password:
                    type: string
                    minLength: 8
                    maxLength: 256
                    description: 'The same password as at the start'
                registrationId:
                    type: string
                    description: 'From the start'
                credential:
                    '$ref': '#/components/schemas/PublicKeyCredentialWithAttestation'
                    description: 'What `navigator.credentials.create` answered'
            required: [method, token, password, registrationId, credential]
            description: 'Accept with the passkey the browser just made'
        InvitationAccept:
            oneOf:
                - '$ref': '#/components/schemas/InvitationAcceptWithAuthenticator'
                - '$ref': '#/components/schemas/InvitationAcceptWithPasskey'
            discriminator:
                propertyName: method
                mapping:
                    authenticator: '#/components/schemas/InvitationAcceptWithAuthenticator'
                    fido: '#/components/schemas/InvitationAcceptWithPasskey'
        InvitationAccepted:
            type: object
            properties:
                email:
                    type: string
                    maxLength: 320
                    description: 'The address to sign in with'
                role:
                    '$ref': '#/components/schemas/PlatformRole'
                    description: 'The role it holds'
            required: [email, role]
            description: 'The account made from an invitation. Sign in with it as usual'
        UserQuery:
            allOf:
                - '$ref': '#/components/schemas/PaginationWithActive'
                - type: object
                  properties:
                      search:
                          type: string
                          minLength: 1
                          maxLength: 200
                          description: 'Part of an email address'
                      role:
                          '$ref': '#/components/schemas/PlatformRole'
                          description: 'Only people holding this role'
        UserSummary:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    description: "The person's account id"
                email:
                    type: string
                    maxLength: 320
                    description: 'The address they sign in with. Absent for an account that has none, such as one made through a provider that shared no address'
                role:
                    '$ref': '#/components/schemas/PlatformRole'
                    description: 'The one role they hold. Absent for an account nobody has granted one'
                active:
                    type: boolean
                    description: 'False once the account has been switched off. A switched-off person cannot sign in, and every session they held has ended'
                createdAt:
                    type: string
                    format: date-time
                    description: 'When the account was made'
                lastSignInAt:
                    type: string
                    format: date-time
                    description: 'When they last signed in. Absent if they never have'
                hasStrongFactor:
                    type: boolean
                    description: 'Whether they have an authenticator app or a passkey, which the phone apps need to sign in with'
            required: [id, active, createdAt, hasStrongFactor]
            description: 'A person with an account on the station'
        UserPage:
            type: object
            properties:
                meta:
                    '$ref': '#/components/schemas/Pagination'
                data:
                    type: array
                    items:
                        '$ref': '#/components/schemas/UserSummary'
            required: [meta, data]
            description: 'One page of people'
        UserFactor:
            type: object
            properties:
                method:
                    type: string
                    enum: [email, password, authenticator, fido, oidc, phone]
                    description: 'What kind of factor it is'
                methodId:
                    type: string
                    maxLength: 255
                    description: 'Which factor of that kind'
                kind:
                    type: string
                    enum: [knowledge, possession, biometric]
                    description: 'What it proves'
                label:
                    type: string
                    maxLength: 255
                    description: "How it is shown, such as a masked address or the authenticator's name"
            required: [method, methodId, kind]
            description: 'One way a person signs in. Never the secret itself'
        UserSignIn:
            type: object
            properties:
                occurredAt:
                    type: string
                    format: date-time
                    description: When
                method:
                    type: string
                    maxLength: 64
                    description: 'The factor they signed in with'
                mfaSatisfied:
                    type: boolean
                    description: 'Whether a second factor was proved'
                ip:
                    type: string
                    maxLength: 64
                    description: 'The address the request came from'
                userAgent:
                    type: string
                    maxLength: 512
                    description: 'The app or browser that asked'
            required: [occurredAt, method, mfaSatisfied]
            description: 'One time a person signed in'
        UserDetail:
            allOf:
                - '$ref': '#/components/schemas/UserSummary'
                - type: object
                  properties:
                      factors:
                          type: array
                          items:
                              '$ref': '#/components/schemas/UserFactor'
                          description: 'Every way they can sign in'
                      sessions:
                          type: array
                          items:
                              '$ref': '#/components/schemas/Session'
                          description: 'Where they are signed in now'
                      signIns:
                          type: array
                          items:
                              '$ref': '#/components/schemas/UserSignIn'
                          description: 'Their most recent sign-ins, newest first'
                  required: [factors, sessions, signIns]
        UserRoleChange:
            type: object
            properties:
                role:
                    '$ref': '#/components/schemas/PlatformRole'
                    description: 'Replaces whatever role they held'
            required: [role]
            description: 'The role a person should hold'
