{"openapi":"3.0.3","info":{"title":"Quak API Documentation","description":"Quak is a Sonos-only API focused on fast account linking, target discovery, and playback automation.\n\n## Authentication\n\nTo get an API key:\n\n1. Call `POST /v1/user/signup` (new account) or `POST /v1/user/login` with your email address.\n\n2. Confirm the request via the email link.\n\n3. Exchange the `verifyToken` using `POST /v1/user/login/key` to receive your API key.\n\nUse the API key on protected endpoints with either:\n\n- Header: `Authorization: Bearer <API_KEY>` (raw token also works).\n\n- Query parameter: `?apikey=<API_KEY>`.\n\n## Identifiers\n\n- `id`: stable UUID identifier exposed in public API payloads.\n\n- `slug`: human-friendly identifier on slug-enabled resources (for example Sonos accounts).\n\nFor slug-enabled resources, `/{id}` path params can accept either `id` or `slug`.\n\n## Playback\n\nPlay text (`POST /v1/play/text`), built-in sounds, own clips, URLs, uploaded files and what someone said into a mic (`POST /v1/play/talk`) on your Sonos speakers. Missing parameters come from your defaults (`PATCH /v1/user/defaults`), including quiet hours (default `22-7`): a play during quiet hours is not played, costs nothing and returns `200` with status `SKIPPED`. `preview: true` only produces the audio and returns its `audioUrl`. Every play is kept in the history (`GET /v1/plays`) and can be stopped while it runs.\n\nCredits: 1 when Sonos fetches from the CDN or the source (sound, clip, URL without processing), 2 when the audio goes through the API server (TTS, processed URL, file, talk), plus the voice rate per started 100 characters for TTS and 1 per started 10 s of speech for talk. A TTS cache hit costs 2, the preview skips the base fee. The balance after the play is in the `X-Quak-User-Credits` header.\n\n## Audio formats\n\nEverything Quak plays is mono, a Sonos room plays on one speaker (a stereo pair only on the left one), so mono uploads lose nothing.\n\n- **Uploads** (`POST /v1/play/file`, `POST /v1/play/talk`, `POST /v1/clips`): any common audio format, for example MP3, M4A/AAC, Opus (WebM or Ogg), WAV or FLAC, max. 10 MB and 60 s. Prefer a compressed format (MP3, M4A, Opus), a WAV of 60 s is about 5 MB mono, 10 MB stereo. For talk the browser's `MediaRecorder` output (WebM/Opus) or iOS M4A can be sent as is.\n\n- **URLs with processing** (`POST /v1/play/url`, default): like uploads, the server downloads and converts them.\n\n- **URLs without processing** (`process: false`): Sonos fetches the file itself, so it must be **MP3** (or WAV) on a public HTTPS URL. Use MP3: Sonos does not play WAV files shorter than about one second.\n\n- **What Sonos gets** from Quak is MP3 (128 kbit/s, 44.1 kHz, mono) for generated audio, sounds and clips.\n\n## Responses\n\nThe API can return these status codes across endpoints:\n\n- `200 OK`: request succeeded.\n\n- `201 Created`: a resource was created (for example an API key).\n\n- `202 Accepted`: request is valid but completion is still pending (for example login confirmation wait mode).\n\n- `204 No Content`: request succeeded and no response body is returned (typically delete endpoints).\n\n- `302 Found`: redirect response (for example Sonos connect with `redirect=1`).\n\n- `400 Bad Request`: invalid query/body/path parameters.\n\n- `401 Unauthorized`: API key missing, invalid or deleted (log in again), or an expired/invalid login verify token.\n\n- `402 Payment Required`: not enough credits for the play.\n\n- `403 Forbidden`: the API key is valid but may not do this.\n\n- `404 Not Found`: requested resource does not exist in your scope.\n\n- `409 Conflict`: uniqueness conflict (for example duplicate API key name) or a play that is not running any more.\n\n- `422 Unprocessable Content`: request body failed schema validation.\n\n- `424 Failed Dependency`: no speaker accepted the play (for example offline or gone), or Sonos did not let it stop.\n\n- `503 Service Unavailable`: a service behind Quak failed, for example Sonos or the speech synthesis. Quak never answers with 502 or 504.","version":"1.0.0","contact":{"name":"Quak","url":"https://quak.party","email":"hello@quak.party"}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key as `Authorization: Bearer <API_KEY>`"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"apikey","description":"API key as `?apikey=<API_KEY>`"}},"schemas":{}},"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"servers":[{"url":"https://api.quak.party","description":"Quak API server"}],"tags":[{"name":"User","description":"User login, profile, and account-scoped preferences"},{"name":"Sounds","description":"Built-in sounds for plays, intros and outros"},{"name":"Voices","description":"Voices, models and languages for text plays"},{"name":"Play","description":"Play text, sounds, clips, URLs and files on Sonos speakers"},{"name":"Plays","description":"History of plays, stop running plays"},{"name":"Clips","description":"Own audio clips, uploaded once and played from the CDN"},{"name":"API Keys","description":"Manage API keys"},{"name":"Sonos Accounts","description":"Connected Sonos account management"}],"externalDocs":{"description":"Full documentation with examples and demos","url":"https://quak.party/docs"},"paths":{"/health":{"get":{"tags":["Health"],"summary":"Health check","security":[],"description":"Returns 200 with status ok when the API works, 503 with status error when not.","responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]}},"required":["status"],"additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]}},"required":["status"],"additionalProperties":false}}}}},"operationId":"getHealth"}},"/v1/user/signup":{"post":{"tags":["User"],"summary":"Sign up","security":[],"description":"Starts a sign-up with email (magic link). A welcome email with a confirmation link is sent, the account is created when the link is confirmed, then poll POST /v1/user/login/key like after a login. If the address has an account already, the email is a login link instead; the response looks the same, so nobody can find out whether an address is registered.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"format":"email","type":"string"},"language":{"description":"language of the client (system or browser), e.g. de-DE, de or de_DE. Default for multi-language voices, changeable in PATCH /v1/user/defaults. Without it: Accept-Language, else en-US","examples":["de-DE"]},"timeZone":{"description":"IANA time zone of the client, e.g. Europe/Berlin, for quiet hours. Without it: from the IP, else UTC","examples":["Europe/Berlin"]},"newsletter":{"description":"true: the Quak newsletter, starts once the address is confirmed. Default false","examples":[false]},"platform":{"description":"the client that logs in: WEB, CLI or API (default), stored on the API key","examples":["WEB"]}},"required":["email"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"email":{"format":"email","type":"string"},"language":{"description":"language of the client (system or browser), e.g. de-DE, de or de_DE. Default for multi-language voices, changeable in PATCH /v1/user/defaults. Without it: Accept-Language, else en-US","examples":["de-DE"]},"timeZone":{"description":"IANA time zone of the client, e.g. Europe/Berlin, for quiet hours. Without it: from the IP, else UTC","examples":["Europe/Berlin"]},"newsletter":{"description":"true: the Quak newsletter, starts once the address is confirmed. Default false","examples":[false]},"platform":{"description":"the client that logs in: WEB, CLI or API (default), stored on the API key","examples":["WEB"]}},"required":["email"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"email":{"format":"email","type":"string"},"language":{"description":"language of the client (system or browser), e.g. de-DE, de or de_DE. Default for multi-language voices, changeable in PATCH /v1/user/defaults. Without it: Accept-Language, else en-US","examples":["de-DE"]},"timeZone":{"description":"IANA time zone of the client, e.g. Europe/Berlin, for quiet hours. Without it: from the IP, else UTC","examples":["Europe/Berlin"]},"newsletter":{"description":"true: the Quak newsletter, starts once the address is confirmed. Default false","examples":[false]},"platform":{"description":"the client that logs in: WEB, CLI or API (default), stored on the API key","examples":["WEB"]}},"required":["email"]}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"verifyToken":{"type":"string"},"loginPhrase":{"type":"string"},"expiresAt":{"format":"date-time","type":"string"}},"required":["verifyToken","loginPhrase","expiresAt"]}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{}}}}},"operationId":"postV1UserSignup"}},"/v1/user/login":{"post":{"tags":["User"],"summary":"Login","security":[],"description":"Starts a login with email (magic link). A confirmation email is sent and a verify token is returned for polling POST /v1/user/login/key. The response includes `loginPhrase`, which should match the phrase shown in the email. No account is created, and an unknown address gets no email. The response looks the same, so nobody can find out whether an address is registered. If no email arrives, there may be no account yet: sign up with POST /v1/user/signup.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"format":"email","type":"string"},"platform":{"description":"the client that logs in: WEB, CLI or API (default), stored on the API key","examples":["WEB"]}},"required":["email"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"email":{"format":"email","type":"string"},"platform":{"description":"the client that logs in: WEB, CLI or API (default), stored on the API key","examples":["WEB"]}},"required":["email"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"email":{"format":"email","type":"string"},"platform":{"description":"the client that logs in: WEB, CLI or API (default), stored on the API key","examples":["WEB"]}},"required":["email"]}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"verifyToken":{"type":"string"},"loginPhrase":{"type":"string"},"expiresAt":{"format":"date-time","type":"string"}},"required":["verifyToken","loginPhrase","expiresAt"]}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{}}}}},"operationId":"postV1UserLogin"}},"/v1/user/login/key":{"post":{"tags":["User"],"summary":"Get API key after login","security":[],"description":"Exchanges a verify token for an API key, optionally waiting for email confirmation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"verifyToken":{"description":"Login verify token from /v1/user/login (length 30).","type":"string"},"waitForConfirmation":{"default":false,"type":"boolean"},"waitTimeoutSeconds":{"minimum":1,"maximum":180,"multipleOf":1,"default":60,"type":"number"}},"required":["verifyToken"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"verifyToken":{"description":"Login verify token from /v1/user/login (length 30).","type":"string"},"waitForConfirmation":{"default":false,"type":"boolean"},"waitTimeoutSeconds":{"minimum":1,"maximum":180,"multipleOf":1,"default":60,"type":"number"}},"required":["verifyToken"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"verifyToken":{"description":"Login verify token from /v1/user/login (length 30).","type":"string"},"waitForConfirmation":{"default":false,"type":"boolean"},"waitTimeoutSeconds":{"minimum":1,"maximum":180,"multipleOf":1,"default":60,"type":"number"}},"required":["verifyToken"]}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"format":"uuid","type":"string"}},"required":["apiKey"]}}}},"202":{"description":"Response for status 202","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{}}}}},"operationId":"postV1UserLoginKey"}},"/v1/user/profile":{"get":{"tags":["User"],"summary":"Get user profile","description":"Returns profile information for the authenticated user.","responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"format":"uuid","type":"string"},"email":{"format":"email","type":"string"},"emailToVerify":{"anyOf":[{"format":"email","type":"string"},{"type":"null"}]},"newsletter":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"credits":{"type":"object","properties":{"total":{"type":"number"},"wallet":{"type":"number"},"subscription":{"type":"number"}},"required":["total","wallet","subscription"]},"subscription":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"}},"required":["id","state"]},"timeZone":{"type":"string"},"audioCacheHours":{"description":"How long generated play audio stays on the server: 24, 12, 3, 1 or 0 (no cache).","type":"number"},"defaults":{"type":"object","properties":{"voice":{"type":"string"},"volume":{"type":"number"},"intro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"outro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"string"}},"delay":{"type":"number"},"quietHours":{"type":"string"},"language":{"description":"language of multi-language voices when a play names none, e.g. de-DE","type":"string"}},"required":["voice","volume","intro","outro","targets","delay","quietHours","language"]}},"required":["id","email","emailToVerify","newsletter","createdAt","credits","subscription","timeZone","audioCacheHours","defaults"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"getV1UserProfile"}},"/v1/user/targets":{"get":{"tags":["User"],"summary":"List playback targets","description":"Returns all available targets for the authenticated user.","parameters":[{"name":"type","in":"query","required":false,"schema":{"description":"Optional target type filter. Use CSV with uppercase values. Allowed values: ALL, USER, ACCOUNT, HOUSEHOLD, PLAYER, GROUP. If omitted, defaults to USER,PLAYER,GROUP.","examples":["ALL","USER,PLAYER,GROUP","ACCOUNT,HOUSEHOLD"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"format":"uuid","type":"string"},"slug":{"type":"string"},"type":{"type":"string","enum":["USER","ACCOUNT","HOUSEHOLD","PLAYER","GROUP"]},"name":{"type":"string"},"players":{"type":"array","items":{"type":"object","properties":{"id":{"format":"uuid","type":"string"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]}}},"required":["id","slug","type","name","players"]}},"meta":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"]}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"getV1UserTargets"}},"/v1/user/time-zones":{"get":{"tags":["User"],"summary":"List time zones","description":"Returns supported IANA time zones for user settings. If the user's current time zone is valid but not in the global list, it is included as well.","responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"meta":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"]}},"required":["data","meta"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"getV1UserTime-zones"}},"/v1/user/email":{"patch":{"tags":["User"],"summary":"Update email address","description":"Starts an email change flow for the authenticated user. A verification email is sent and the new email becomes active only after link confirmation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{}},"required":["email"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"email":{}},"required":["email"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"email":{}},"required":["email"]}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"format":"uuid","type":"string"},"email":{"format":"email","type":"string"},"emailToVerify":{"anyOf":[{"format":"email","type":"string"},{"type":"null"}]},"newsletter":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"credits":{"type":"object","properties":{"total":{"type":"number"},"wallet":{"type":"number"},"subscription":{"type":"number"}},"required":["total","wallet","subscription"]},"subscription":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"}},"required":["id","state"]},"timeZone":{"type":"string"},"audioCacheHours":{"description":"How long generated play audio stays on the server: 24, 12, 3, 1 or 0 (no cache).","type":"number"},"defaults":{"type":"object","properties":{"voice":{"type":"string"},"volume":{"type":"number"},"intro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"outro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"string"}},"delay":{"type":"number"},"quietHours":{"type":"string"},"language":{"description":"language of multi-language voices when a play names none, e.g. de-DE","type":"string"}},"required":["voice","volume","intro","outro","targets","delay","quietHours","language"]}},"required":["id","email","emailToVerify","newsletter","createdAt","credits","subscription","timeZone","audioCacheHours","defaults"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"patchV1UserEmail"}},"/v1/user/defaults":{"patch":{"tags":["User"],"summary":"Update playback defaults","description":"Updates user playback defaults. Intro and outro accept a sound slug, \"clip:<slug>\" for one of your clips, or \"none\" to disable them. quietHours sets when nothing plays, in the user time zone and full hours, e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\".","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"voice":{},"volume":{},"intro":{},"outro":{},"targets":{},"delay":{},"language":{"description":"language of multi-language voices when a play names none, e.g. de-DE or de","examples":["de-DE"]},"quietHours":{}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"voice":{},"volume":{},"intro":{},"outro":{},"targets":{},"delay":{},"language":{"description":"language of multi-language voices when a play names none, e.g. de-DE or de","examples":["de-DE"]},"quietHours":{}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"voice":{},"volume":{},"intro":{},"outro":{},"targets":{},"delay":{},"language":{"description":"language of multi-language voices when a play names none, e.g. de-DE or de","examples":["de-DE"]},"quietHours":{}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"format":"uuid","type":"string"},"email":{"format":"email","type":"string"},"emailToVerify":{"anyOf":[{"format":"email","type":"string"},{"type":"null"}]},"newsletter":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"credits":{"type":"object","properties":{"total":{"type":"number"},"wallet":{"type":"number"},"subscription":{"type":"number"}},"required":["total","wallet","subscription"]},"subscription":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"}},"required":["id","state"]},"timeZone":{"type":"string"},"audioCacheHours":{"description":"How long generated play audio stays on the server: 24, 12, 3, 1 or 0 (no cache).","type":"number"},"defaults":{"type":"object","properties":{"voice":{"type":"string"},"volume":{"type":"number"},"intro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"outro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"string"}},"delay":{"type":"number"},"quietHours":{"type":"string"},"language":{"description":"language of multi-language voices when a play names none, e.g. de-DE","type":"string"}},"required":["voice","volume","intro","outro","targets","delay","quietHours","language"]}},"required":["id","email","emailToVerify","newsletter","createdAt","credits","subscription","timeZone","audioCacheHours","defaults"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"patchV1UserDefaults"}},"/v1/user/newsletter":{"patch":{"tags":["User"],"summary":"Update newsletter setting","description":"Updates the newsletter setting for the authenticated user.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newsletter":{}},"required":["newsletter"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"newsletter":{}},"required":["newsletter"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"newsletter":{}},"required":["newsletter"]}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"format":"uuid","type":"string"},"email":{"format":"email","type":"string"},"emailToVerify":{"anyOf":[{"format":"email","type":"string"},{"type":"null"}]},"newsletter":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"credits":{"type":"object","properties":{"total":{"type":"number"},"wallet":{"type":"number"},"subscription":{"type":"number"}},"required":["total","wallet","subscription"]},"subscription":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"}},"required":["id","state"]},"timeZone":{"type":"string"},"audioCacheHours":{"description":"How long generated play audio stays on the server: 24, 12, 3, 1 or 0 (no cache).","type":"number"},"defaults":{"type":"object","properties":{"voice":{"type":"string"},"volume":{"type":"number"},"intro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"outro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"string"}},"delay":{"type":"number"},"quietHours":{"type":"string"},"language":{"description":"language of multi-language voices when a play names none, e.g. de-DE","type":"string"}},"required":["voice","volume","intro","outro","targets","delay","quietHours","language"]}},"required":["id","email","emailToVerify","newsletter","createdAt","credits","subscription","timeZone","audioCacheHours","defaults"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"patchV1UserNewsletter"}},"/v1/user/time-zone":{"patch":{"tags":["User"],"summary":"Update time zone","description":"Updates the user's time zone.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"timeZone":{}},"required":["timeZone"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"timeZone":{}},"required":["timeZone"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"timeZone":{}},"required":["timeZone"]}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"format":"uuid","type":"string"},"email":{"format":"email","type":"string"},"emailToVerify":{"anyOf":[{"format":"email","type":"string"},{"type":"null"}]},"newsletter":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"credits":{"type":"object","properties":{"total":{"type":"number"},"wallet":{"type":"number"},"subscription":{"type":"number"}},"required":["total","wallet","subscription"]},"subscription":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"}},"required":["id","state"]},"timeZone":{"type":"string"},"audioCacheHours":{"description":"How long generated play audio stays on the server: 24, 12, 3, 1 or 0 (no cache).","type":"number"},"defaults":{"type":"object","properties":{"voice":{"type":"string"},"volume":{"type":"number"},"intro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"outro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"string"}},"delay":{"type":"number"},"quietHours":{"type":"string"},"language":{"description":"language of multi-language voices when a play names none, e.g. de-DE","type":"string"}},"required":["voice","volume","intro","outro","targets","delay","quietHours","language"]}},"required":["id","email","emailToVerify","newsletter","createdAt","credits","subscription","timeZone","audioCacheHours","defaults"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"patchV1UserTime-zone"}},"/v1/user/audio-cache":{"patch":{"tags":["User"],"summary":"Update audio cache","description":"Sets how long generated play audio stays on the server after its last use: 24, 12, 3, 1 or 0 hours. 0 means no cache: the audio is deleted once it has played (after 5 minutes at the latest) and every repeat costs the full TTS credits again. A shorter time also applies to audio already in the cache.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audioCacheHours":{"description":"24, 12, 3, 1 or 0 (no cache)"}},"required":["audioCacheHours"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"audioCacheHours":{"description":"24, 12, 3, 1 or 0 (no cache)"}},"required":["audioCacheHours"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"audioCacheHours":{"description":"24, 12, 3, 1 or 0 (no cache)"}},"required":["audioCacheHours"]}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"format":"uuid","type":"string"},"email":{"format":"email","type":"string"},"emailToVerify":{"anyOf":[{"format":"email","type":"string"},{"type":"null"}]},"newsletter":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"credits":{"type":"object","properties":{"total":{"type":"number"},"wallet":{"type":"number"},"subscription":{"type":"number"}},"required":["total","wallet","subscription"]},"subscription":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"}},"required":["id","state"]},"timeZone":{"type":"string"},"audioCacheHours":{"description":"How long generated play audio stays on the server: 24, 12, 3, 1 or 0 (no cache).","type":"number"},"defaults":{"type":"object","properties":{"voice":{"type":"string"},"volume":{"type":"number"},"intro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"outro":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"targets":{"type":"array","items":{"type":"string"}},"delay":{"type":"number"},"quietHours":{"type":"string"},"language":{"description":"language of multi-language voices when a play names none, e.g. de-DE","type":"string"}},"required":["voice","volume","intro","outro","targets","delay","quietHours","language"]}},"required":["id","email","emailToVerify","newsletter","createdAt","credits","subscription","timeZone","audioCacheHours","defaults"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"patchV1UserAudio-cache"}},"/v1/accounts":{"get":{"tags":["Sonos Accounts"],"summary":"List accounts","description":"Returns all connected Sonos accounts for the authenticated user.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"description":"Pagination limit. Default: 100. Allowed range: 1..1000.","default":"100","examples":["100","250","1000"],"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"description":"Pagination offset. Default: 0. Allowed range: 0..n.","default":"0","examples":["0","10","500"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"format":"uuid","type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"playerCount":{"type":"number"},"supportedPlayerCount":{"type":"number"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","slug","name","playerCount","supportedPlayerCount","createdAt"]}},"meta":{"type":"object","properties":{"total":{"type":"number"},"count":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["total","count","limit","offset"]}},"required":["data","meta"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"getV1Accounts"}},"/v1/accounts/sync":{"post":{"tags":["Sonos Accounts"],"summary":"Sync accounts","description":"Refreshes Sonos data for every account connected to the authenticated user.","responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"format":"uuid","type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"playerCount":{"type":"number"},"supportedPlayerCount":{"type":"number"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","slug","name","playerCount","supportedPlayerCount","createdAt"]}},"meta":{"type":"object","properties":{"total":{"type":"number"},"count":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["total","count","limit","offset"]}},"required":["data","meta"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"postV1AccountsSync"}},"/v1/accounts/connect":{"get":{"tags":["Sonos Accounts"],"summary":"Connect Sonos account","description":"Connect your Sonos account to your Quak account to enable playback on your speakers.","parameters":[{"name":"redirect","in":"query","required":false,"schema":{"description":"Set to `1` to immediately redirect to Sonos OAuth. Default: `0` (JSON response with `authUrl` and `expiresAt`). Allowed values: `0` or `1`.","default":"0","examples":["0","1"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"authUrl":{"format":"uri","type":"string"},"expiresAt":{"format":"date-time","type":"string"}},"required":["authUrl","expiresAt"]}},"required":["data"]}}}},"302":{"description":"Response for status 302","content":{"application/json":{"schema":{}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"getV1AccountsConnect"}},"/v1/accounts/{id}":{"delete":{"tags":["Sonos Accounts"],"summary":"Remove Sonos connection","description":"Removes your Sonos connection. Quak will no longer be able to use your Sonos speakers for playback.","parameters":[{"name":"id","in":"path","required":true,"schema":{"description":"Account identifier. Accepts account slug or UUID.","examples":["sonos-account","2f07a8b0-5766-4ebb-b8e8-6b5af57d6f08"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"deleteV1AccountsById"}},"/v1/sounds":{"get":{"tags":["Sounds"],"summary":"List sounds","description":"Returns available sounds.","parameters":[{"name":"tags","in":"query","required":false,"schema":{"description":"Optional CSV sound tag filter (case-insensitive OR match). Example: INTRO,OUTRO","examples":["INTRO","INTRO,OUTRO","ANIMALS,CASH"],"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"description":"Pagination limit. Default: 500. Allowed range: 1..1000.","default":"500","examples":["500","250","1000"],"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"description":"Pagination offset. Default: 0. Allowed range: 0..n.","default":"0","examples":["0","10","500"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"format":"uuid","type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"audioUrl":{"format":"uri","type":"string"},"length":{"type":"number"},"tags":{"type":"array","items":{"type":"string","enum":["INTRO","OUTRO","REACTIONS","ANIMALS","CASH","VEHICLES","SCARY","MELODIES","MISC"]}},"createdAt":{"format":"date-time","type":"string"}},"required":["id","slug","name","audioUrl","length","tags","createdAt"]}},"meta":{"type":"object","properties":{"total":{"type":"number"},"count":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["total","count","limit","offset"]}},"required":["data","meta"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"getV1Sounds"}},"/v1/sounds/tags":{"get":{"tags":["Sounds"],"summary":"List sound tags","description":"Returns all available sound tags.","responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string","enum":["INTRO","OUTRO","REACTIONS","ANIMALS","CASH","VEHICLES","SCARY","MELODIES","MISC"]},"name":{"type":"string"}},"required":["tag","name"]}},"meta":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"]}},"required":["data","meta"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"getV1SoundsTags"}},"/v1/voices":{"get":{"tags":["Voices"],"summary":"List voices","description":"Returns the available voices of AWS Polly, Google (Chirp 3 HD and Gemini), OpenAI and ElevenLabs, see `provider` and `model`. Pass a voice `slug` as `voice` to POST /v1/play/text. Only current models are listed (see `GET /v1/voices/models`). Multi-language voices without a native language have `locale` and `language` `mul` and speak the language of the play (`language`, else the user language); other multi-language voices keep their native accent as `locale`.","parameters":[{"name":"provider","in":"query","required":false,"schema":{"description":"Optional provider filter. Allowed values: AWS, GOOGLE, OPENAI, ELEVENLABS (case-insensitive).","examples":["AWS","google","openai"],"type":"string"}},{"name":"gender","in":"query","required":false,"schema":{"description":"Optional gender filter. Allowed values: MALE, FEMALE, NEUTRAL (case-insensitive).","examples":["MALE","female"],"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"description":"Optional CSV locale filter (case-insensitive OR match). Returns the voices native to the locale and the multi-language voices whose model speaks its language, sorted by latency (fast, normal, slow) and within each class native voices first. Example: de-DE,en-US","examples":["de-DE","de-DE,en-US"],"type":"string"}},{"name":"model","in":"query","required":false,"schema":{"description":"Optional CSV model filter (case-insensitive OR match) on the model id as GET /v1/voices/models lists it. Example: chirp3-hd,gemini-2.5-flash-tts","examples":["eleven_v3","chirp3-hd,gemini-2.5-flash-tts"],"type":"string"}},{"name":"multiLanguage","in":"query","required":false,"schema":{"description":"Optional filter for multi-language voices: true returns only voices that speak every language of their model, false only single-language voices.","examples":["true","false"],"type":"string"}},{"name":"language","in":"query","required":false,"schema":{"description":"Optional CSV language filter (case-insensitive OR match). Multi-language voices match every language their model supports. Sorted by latency (fast, normal, slow), within each class voices whose own language matches first. `mul` returns the multi-language voices without a native language. Example: de,en","examples":["de","de,en"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"provider":{"type":"string","enum":["AWS","GOOGLE","OPENAI","ELEVENLABS"]},"model":{"type":"string"},"latency":{"type":"string","enum":["fast","normal","slow"]},"multiLanguage":{"type":"boolean"},"name":{"type":"string"},"locale":{"type":"string"},"language":{"type":"string"},"languageName":{"type":"string"},"languageNativeName":{"type":"string"},"gender":{"type":"string"},"credits":{"description":"credits per started 100 characters, plus the base fee of a play","type":"number"}},"required":["slug","provider","model","latency","multiLanguage","name","locale","language","languageName","languageNativeName","gender","credits"]}},"meta":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"]}},"required":["data","meta"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"getV1Voices"}},"/v1/voices/locales":{"get":{"tags":["Voices"],"summary":"List voice locales","description":"Returns all available voice locales.","parameters":[{"name":"language","in":"query","required":false,"schema":{"description":"Optional CSV language filter (case-insensitive OR match). Example: de,en","examples":["de","de,en"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"locale":{"type":"string"},"language":{"type":"string"},"languageName":{"type":"string"},"languageNativeName":{"type":"string"}},"required":["locale","language","languageName","languageNativeName"]}},"meta":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"]}},"required":["data","meta"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"getV1VoicesLocales"}},"/v1/voices/languages":{"get":{"tags":["Voices"],"summary":"List voice languages","description":"Returns all available voice languages.","responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"languageName":{"type":"string"},"languageNativeName":{"type":"string"}},"required":["language","languageName","languageNativeName"]}},"meta":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"]}},"required":["data","meta"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"getV1VoicesLanguages"}},"/v1/voices/models":{"get":{"tags":["Voices"],"summary":"List voice models","description":"Returns one entry per model with the number of voices, whether its voices speak several languages, the languages it supports (ISO 639 codes), its credit rate per started 100 characters (plus the base fee of a play) and its `status` (`ga` or `preview`) and `latency` (`fast`: first audio within ~300 ms, `normal`: within ~1.5 s, `slow`: may take a few seconds). For multi-language models `languages` lists every supported language, for the others the languages of their voices.","responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string","enum":["AWS","GOOGLE","OPENAI","ELEVENLABS"]},"model":{"type":"string"},"status":{"type":"string","enum":["ga","preview"]},"latency":{"type":"string","enum":["fast","normal","slow"]},"multiLanguage":{"type":"boolean"},"voices":{"type":"number"},"languages":{"type":"array","items":{"type":"string"}},"credits":{"description":"credits per started 100 characters, plus the base fee of a play","type":"number"}},"required":["provider","model","status","latency","multiLanguage","voices","languages","credits"]}},"meta":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"]}},"required":["data","meta"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"getV1VoicesModels"}},"/v1/play/text":{"post":{"tags":["Play"],"summary":"Play text","description":"Speaks a text with a voice from /v1/voices on the target speakers. Credits: 2 + the voice rate per started 100 characters, 2 on a cache hit, the preview only the voice rate. Returns 200 with status SKIPPED during quiet hours.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"description":"the text, 1-1000 characters (about 60-70 s spoken)","examples":["Dinner is ready!"]},"voice":{"description":"voice slug from /v1/voices, default: the user default"},"language":{"description":"multi-language voices only: the language to speak, e.g. en or de-DE","examples":["en"]},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"skipCache":{"description":"true: produce the audio again instead of using the cache"},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"text":{"description":"the text, 1-1000 characters (about 60-70 s spoken)","examples":["Dinner is ready!"]},"voice":{"description":"voice slug from /v1/voices, default: the user default"},"language":{"description":"multi-language voices only: the language to speak, e.g. en or de-DE","examples":["en"]},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"skipCache":{"description":"true: produce the audio again instead of using the cache"},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"text":{"description":"the text, 1-1000 characters (about 60-70 s spoken)","examples":["Dinner is ready!"]},"voice":{"description":"voice slug from /v1/voices, default: the user default"},"language":{"description":"multi-language voices only: the language to speak, e.g. en or de-DE","examples":["en"]},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"skipCache":{"description":"true: produce the audio again instead of using the cache"},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"424":{"description":"Response for status 424","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"postV1PlayText"}},"/v1/play/sound":{"post":{"tags":["Play"],"summary":"Play a sound","description":"Plays a built-in sound from /v1/sounds, fetched by Sonos from the CDN. Credits: 1.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sound":{"description":"sound slug from /v1/sounds","examples":["quakquak"]},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"sound":{"description":"sound slug from /v1/sounds","examples":["quakquak"]},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"sound":{"description":"sound slug from /v1/sounds","examples":["quakquak"]},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"424":{"description":"Response for status 424","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"postV1PlaySound"}},"/v1/play/clip":{"post":{"tags":["Play"],"summary":"Play a clip","description":"Plays one of your clips from /v1/clips, fetched by Sonos from the CDN. Credits: 1.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clip":{"description":"clip slug from /v1/clips","examples":["front-door"]},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"clip":{"description":"clip slug from /v1/clips","examples":["front-door"]},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"clip":{"description":"clip slug from /v1/clips","examples":["front-door"]},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"424":{"description":"Response for status 424","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"postV1PlayClip"}},"/v1/play/url":{"post":{"tags":["Play"],"summary":"Play a URL","description":"Plays audio from a URL. With process (default) the server downloads it (max. 10 MB and 60 s) and adds intro, outro and effect, credits: 2. With process false Sonos fetches the URL itself, credits: 1.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"http(s) URL of an audio file","examples":["https://example.com/news.mp3"]},"process":{"description":"false: Sonos fetches the URL itself, without intro, outro and effect. Then it must be MP3 (or WAV) on a public HTTPS URL, use MP3: Sonos skips WAV files shorter than about 1 s","examples":[true]},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"skipCache":{"description":"true: produce the audio again instead of using the cache"},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}},"additionalProperties":false}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"url":{"description":"http(s) URL of an audio file","examples":["https://example.com/news.mp3"]},"process":{"description":"false: Sonos fetches the URL itself, without intro, outro and effect. Then it must be MP3 (or WAV) on a public HTTPS URL, use MP3: Sonos skips WAV files shorter than about 1 s","examples":[true]},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"skipCache":{"description":"true: produce the audio again instead of using the cache"},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"url":{"description":"http(s) URL of an audio file","examples":["https://example.com/news.mp3"]},"process":{"description":"false: Sonos fetches the URL itself, without intro, outro and effect. Then it must be MP3 (or WAV) on a public HTTPS URL, use MP3: Sonos skips WAV files shorter than about 1 s","examples":[true]},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"skipCache":{"description":"true: produce the audio again instead of using the cache"},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"424":{"description":"Response for status 424","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"postV1PlayUrl"}},"/v1/play/file":{"post":{"tags":["Play"],"summary":"Play a file","description":"Plays an uploaded audio file (multipart/form-data, field file, max. 10 MB and 60 s, any common audio format). All other parameters (volume, targets, quietHours, priority, preview, intro, outro, delay, effect, intensity, skipCache) are plain form fields in the same request. Credits: 2.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"default":"File","description":"the audio file, max. 10 MB and 60 s, any common audio format (MP3, M4A/AAC, Opus, WAV, FLAC etc.), mono is enough, compressed formats keep the upload small","type":"string","format":"binary"},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"skipCache":{"description":"true: produce the audio again instead of using the cache"},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"file":{"default":"File","description":"the audio file, max. 10 MB and 60 s, any common audio format (MP3, M4A/AAC, Opus, WAV, FLAC etc.), mono is enough, compressed formats keep the upload small","type":"string","format":"binary"},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"skipCache":{"description":"true: produce the audio again instead of using the cache"},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"default":"File","description":"the audio file, max. 10 MB and 60 s, any common audio format (MP3, M4A/AAC, Opus, WAV, FLAC etc.), mono is enough, compressed formats keep the upload small","type":"string","format":"binary"},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"skipCache":{"description":"true: produce the audio again instead of using the cache"},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"424":{"description":"Response for status 424","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"postV1PlayFile"}},"/v1/play/talk":{"post":{"tags":["Play"],"summary":"Talk","description":"Plays what someone said into a mic, after release. Unlike play/file the audio runs through the voice processing (high-pass, noise gate, auto gain, EQ), silence at start and end is cut and at most 60 s of speech are played. Effects that need the whole take (faster, slower, reverse) work here. All other parameters are plain form fields in the same request. Credits: 2 + 1 per started 10 s of speech after trimming, the preview only the speech part.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"default":"File","description":"the spoken audio, max. 10 MB, any common audio format (browser MediaRecorder WebM/Opus, iOS M4A, WAV etc.), mono is enough, Opus or M4A keep the upload small","type":"string","format":"binary"},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"file":{"default":"File","description":"the spoken audio, max. 10 MB, any common audio format (browser MediaRecorder WebM/Opus, iOS M4A, WAV etc.), mono is enough, Opus or M4A keep the upload small","type":"string","format":"binary"},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"default":"File","description":"the spoken audio, max. 10 MB, any common audio format (browser MediaRecorder WebM/Opus, iOS M4A, WAV etc.), mono is enough, Opus or M4A keep the upload small","type":"string","format":"binary"},"intro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["quakquak","clip:front-door"]},"outro":{"description":"sound slug, \"clip:<slug>\" for one of your clips or \"none\", default: the user default","examples":["none"]},"delay":{"description":"pause around the content in ms: 0, 100, ..., 1000","examples":[200]},"effect":{"description":"voice effect: none, vibrato, megaphone, bitcrush, radiodj, station, stadium, f1, airport, tennis, pool, robot, helium, monster, lofi, echo, reverb, reverse, faster, slower","examples":["none","faster","echo"]},"intensity":{"description":"0-100, default 50","examples":[50]},"volume":{"description":"1-100, default: the user's default volume","examples":[30]},"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]},"quietHours":{"description":"when nothing plays, overrides the user default (22-7), e.g. \"22-7\", \"su-th 22-7, fr-sa 23-9\" or \"none\"","examples":["none","22-7"]},"priority":{"description":"true: Sonos priority HIGH, interrupts other clips","examples":[false]},"preview":{"description":"true: only produce the audio (audioUrl), nothing plays on Sonos","examples":[false]}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"424":{"description":"Response for status 424","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"postV1PlayTalk"}},"/v1/play/stop":{"post":{"tags":["Play"],"summary":"Stop the speakers","description":"Stops whatever plays on the targets, also clips of other apps and clips with high priority: a short silent clip replaces the running one. New plays may be refused as busy for about a second afterwards. Free, not part of the history. To stop one play, use POST /v1/plays/:uuid/stop.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"targets":{"description":"target slugs from /v1/user/targets as array or CSV, default: the user's default targets","examples":[["all"],"kitchen,office"]}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}}},"required":["players"]}},"required":["data"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"424":{"description":"Response for status 424","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"postV1PlayStop"}},"/v1/plays/watch":{"ws":{"tags":["Plays"],"summary":"Watch plays (WebSocket)","security":[],"description":"Live status of your plays. Log in with the first message {\"type\":\"auth\",\"apiKey\":\"…\"} (or the Authorization header), then you get {\"type\":\"ready\"}, every running play once and every change of a play as {\"type\":\"play\",\"data\":{…}} (the same object as GET /v1/plays/:uuid), plus {\"type\":\"ping\"} every 25 s. Reconnect after a drop, you get the current state again.","operationId":"wsV1PlaysWatch"}},"/v1/plays":{"get":{"tags":["Plays"],"summary":"List plays","description":"Returns the history of plays, newest first, including previews and plays skipped by quiet hours.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"description":"Pagination limit. Default: 50. Allowed range: 1..1000.","type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"description":"Pagination offset. Default: 0.","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"meta":{"type":"object","properties":{"total":{"type":"number"},"count":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["total","count","limit","offset"]}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"getV1Plays"}},"/v1/plays/{uuid}":{"get":{"tags":["Plays"],"summary":"Show a play","description":"Returns one play with its status per speaker.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"description":"id of the play","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"getV1PlaysByUuid"}},"/v1/plays/{uuid}/stop":{"post":{"tags":["Plays"],"summary":"Stop a play","description":"Stops a running play on all its speakers. Returns 409 when the play is not running any more.","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"description":"id of the play","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"description":"TEXT, SOUND, CLIP, URL or FILE","type":"string"},"status":{"description":"PENDING, ACTIVE, DONE, STOPPED, FAILED or SKIPPED (see skipReason), the best outcome of its speakers","type":"string"},"skipReason":{"description":"SKIPPED only: QUIET_HOURS, or BUSY when every speaker plays a clip with higher priority","anyOf":[{"const":"QUIET_HOURS","type":"string"},{"const":"BUSY","type":"string"},{"type":"null"}]},"preview":{"type":"boolean"},"params":{"description":"the parameters of the play, defaults resolved","type":"object","patternProperties":{"^(.*)$":{}}},"players":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"description":"PENDING (Sonos took the clip), ACTIVE (playing), DONE, STOPPED (ended early), FAILED or SKIPPED (busy with a clip of higher priority)","type":"string"},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"description":"when Sonos started the clip (Sonos event), else null","anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"description":"when the clip ended (Sonos event or stop), else null","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","slug","name","status","error","startedAt","endedAt"]}},"audioUrl":{"description":"the audio Sonos plays, also for the preview","anyOf":[{"type":"string"},{"type":"null"}]},"length":{"description":"seconds, rounded up","anyOf":[{"type":"number"},{"type":"null"}]},"credits":{"type":"number"},"fromCache":{"description":"true when generated audio came from the cache (TTS, processed URL or file)","type":"boolean"},"createdAt":{"type":"string"}},"required":["id","type","status","skipReason","preview","params","players","audioUrl","length","credits","fromCache","createdAt"]}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"postV1PlaysByUuidStop"}},"/v1/clips":{"get":{"tags":["Clips"],"summary":"List clips","description":"Returns your own clips, sorted by name. Play them with POST /v1/play/clip.","responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"length":{"description":"seconds","type":"number"},"audioUrl":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","slug","name","length","audioUrl","createdAt"]}},"meta":{"type":"object","properties":{"total":{"type":"number"}},"required":["total"]}},"required":["data","meta"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"getV1Clips"},"post":{"tags":["Clips"],"summary":"Create a clip","description":"Uploads an own clip (multipart/form-data: file, name, optional slug; max. 10 MB and 60 s, any common audio format). It is converted to MP3 once and then played from the CDN like a sound, or used as intro or outro with clip:<slug>. Creating a clip costs 2 credits (402 when there are not enough), the balance is in X-Quak-User-Credits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"default":"File","description":"the audio file, max. 10 MB and 60 s, any common audio format (MP3, M4A/AAC, Opus, WAV, FLAC etc.), mono is enough, compressed formats keep the upload small","type":"string","format":"binary"},"name":{"description":"display name, unique per user","examples":["Front door"]},"slug":{"description":"optional, derived from the name","examples":["front-door"]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"file":{"default":"File","description":"the audio file, max. 10 MB and 60 s, any common audio format (MP3, M4A/AAC, Opus, WAV, FLAC etc.), mono is enough, compressed formats keep the upload small","type":"string","format":"binary"},"name":{"description":"display name, unique per user","examples":["Front door"]},"slug":{"description":"optional, derived from the name","examples":["front-door"]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"default":"File","description":"the audio file, max. 10 MB and 60 s, any common audio format (MP3, M4A/AAC, Opus, WAV, FLAC etc.), mono is enough, compressed formats keep the upload small","type":"string","format":"binary"},"name":{"description":"display name, unique per user","examples":["Front door"]},"slug":{"description":"optional, derived from the name","examples":["front-door"]}}}}}},"responses":{"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"length":{"description":"seconds","type":"number"},"audioUrl":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","slug","name","length","audioUrl","createdAt"]}},"required":["data"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"postV1Clips"}},"/v1/clips/{slug}":{"delete":{"tags":["Clips"],"summary":"Delete a clip","description":"Deletes one of your clips and its audio.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"],"additionalProperties":false}}}}},"operationId":"deleteV1ClipsBySlug"}},"/v1/keys":{"get":{"tags":["API Keys"],"summary":"List API keys","description":"Returns your manually created API keys with limit/offset pagination.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"description":"Pagination limit. Default: 100. Allowed range: 1..1000.","default":"100","examples":["100","250","1000"],"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"description":"Pagination offset. Default: 0. Allowed range: 0..n.","default":"0","examples":["0","10","500"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"key":{"format":"uuid","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestCount":{"type":"number"},"playCount":{"type":"number"},"lastRequestAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"}},"required":["key","name","requestCount","playCount","lastRequestAt","createdAt"]}},"meta":{"type":"object","properties":{"total":{"type":"number"},"count":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["total","count","limit","offset"]}},"required":["data","meta"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"getV1Keys"},"post":{"tags":["API Keys"],"summary":"Create API key","description":"Creates a new API key. A non-empty name is required. Key names must be unique among your keys (case-insensitive).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"key":{"format":"uuid","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestCount":{"type":"number"},"playCount":{"type":"number"},"lastRequestAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"}},"required":["key","name","requestCount","playCount","lastRequestAt","createdAt"]}},"required":["data"]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"postV1Keys"}},"/v1/keys/{key}":{"patch":{"tags":["API Keys"],"summary":"Update API key","description":"Updates the name of one of your API keys. Key names must be unique among your keys (case-insensitive).","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"key":{"format":"uuid","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestCount":{"type":"number"},"playCount":{"type":"number"},"lastRequestAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"}},"required":["key","name","requestCount","playCount","lastRequestAt","createdAt"]}},"required":["data"]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"patchV1KeysByKey"},"delete":{"tags":["API Keys"],"summary":"Delete API key","description":"Deletes one of your API keys so it no longer appears in your key list.","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"deleteV1KeysByKey"}},"/v1/keys/current":{"delete":{"tags":["API Keys"],"summary":"Delete current API key","description":"Deletes the API key used for the current request.","responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]}}}}},"operationId":"deleteV1KeysCurrent"}}}}