API_DOC

{"swagger": "2.0", "info": {"title": "Toniecloud API", "description": "<p>We use GraphQL for read-only requests and REST for writing requests. Some read-only endpoints\nare also available via REST.</p>\n\n<p>This page documents the REST API. Visit the\n<a href=\"/v2/graphql\"><strong>interactive GraphQL viewer</strong></a> for the GraphQL API.\nYou can start with the query to list Tunes items:\n<a href=\"/v2/graphql?query=%7B%0A%20%20contentTokens%28first%3A%205%2C%20selection%3A%20%22public%22%2C%20region%3A%20%22user%22%29%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20token%0A%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20thumbnail%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D\">\n    <code>{contentTokens(first: 5, selection: &quot;public&quot;, region: &quot;user&quot;) {edges {node {token title thumbnail }}}}</code></a>\n</p>\n\n<h4>Common error codes in the REST API</h4>\n\n<em>These return codes apply to all endpoints, unless otherwise noted.\nThey follow standard HTTP semantics. Unless otherwise noted, the response body is undefined.</em>\n\n<table>\n<thead><tr><th>HTTP code</th><th>Meaning</th></tr></thead>\n<tbody>\n<tr>\n    <td title=\"Authorization Required\">401</td>\n    <td>Login is necessary to access this resource.</td>\n</tr>\n<tr>\n    <td title=\"Forbidden\">403</td>\n    <td>Access denied to the specified resource. Logging in will not help.</td>\n</tr>\n<tr>\n    <td title=\"Not Found\">404</td>\n    <td>The specified resource could not be found (e.g. invalid ID).</td>\n</tr>\n<tr>\n    <td><span title=\"Internal Server Error\">500</span>,\n        <span title=\"Bad Gateway\">502</span>,\n        <span title=\"Gateway Timeout\">504</span></td>\n    <td>\n        A generic server-side failure has occurred.\n        An apology and/or appropriately funny error message should be presented to the user.\n        The distinction between 500, 502 and 504 is only for developers.</td>\n</tr>\n<tr>\n    <td title=\"Service Unavailable\">503</td>\n    <td>The server is in maintenance mode, i.e. no functions are available right now.\n    The message to the user can be among the lines of <em>try again later</em>.</td>\n</tr>\n</tbody></table>\n\n<h4>Authentication</h4>\n\n<p>Send an <code>Authorization: Bearer j.w.t</code> HTTP header on each request, where j.w.t\nis the <code>access_token</code> you get from the SSO login/registration.</p>\n\n<h4>Email domain</h4>\n\n<p>You can set the domain any emails from your request go to by sending a URL of that domain in the\n<code>Origin</code> or <code>Referer</code> header.\nIt is strongly recommended to always send the current URL in the <code>Referer</code> header, as\nthis enables us to associate the original URL during debugging.</p>\n\n<h4 id=\"datatypes\">Data types</h4>\n\n<p>A <strong>household</strong> is used to manage the physical items in, well, a household.\nThe members of the household – which can be any registered <strong>user</strong> – can add, rename, configure, and\nedit the physical items.\nA user can be a member in an arbitrary number of households.\nUsers start without a household, but to meaningfully use the Toniecloud, they will need to join or create at least\none household.<br>\n\nMembers are one of:\n<ol type=\"a\">\n<li><em>Owner</em>. There must always be one owner of the household.\nIf they delete their account they can transfer the household or delete it.\nUsers can only own one household at time.</li>\n<li><em>Full members</em> can do everything a household owner can do, except deleting/transferring the household.\nA user can be a full member in as many households as they want.\n</li>\n<li><em>Limited</em> members (also called <em>guest members</em> in the UI) can only see some Content Tonies and Creative Tonies.\nThis is ideal for users who should just do one task; the stereotypical example is the grandpa who wants to record on one\nCreative Tonie only.\n</li>\n</ol>\n\nOwners and full users can create <strong>invitations</strong> to arbitrary email addresses, whether registered or not.\n</p>\n\n<p><strong>Tonieboxes</strong> are initially not bound to any household.\nOwners and full members can create a <strong>Toniebox setup</strong>, asking the Toniebox to be placed in a household.\nAt the end of the setup process, the Toniebox joins their household.<br/>\nTonieboxes can be set up without creating an account, but that will severely restrict their usability.</p>\n\n<p><strong>Creative Tonies</strong> are figurines which users can upload their own audio content to.<br>\nMost Creative Tonies are of a neutral design.<br>\nEmpty Creative Tonies get assigned to the household of the Toniebox they are put on.<br>\nA Creative Tonie holds up to 99 chapters 90 minutes.<br>\nUsers can also add chapters from <strong>Content Tokens</strong>; free chapters that the user can add at any place.<br>\nWhen the Content of a Creative Tonie changes, it will need to be <em>transcoded</em> for the Toniebox\n(e.g. mp3 needs to be converted to Toniebox audio), which can take between 1 and 60 seconds normally.</p>\n\n<p><strong>Content Tonies</strong> function similarly, but are prerecorded with a specific content, and are often\nlicensed characters like Benjamin Blümchen or Elsa from Frozen.<br>\nBy default, they switch households to whichever Toniebox they were put last on. However, they can be locked in the current household, for example so that a library can keep all the Tonies they loan out in their own household.<p>\n\n<p><strong>Content Tonie <em>Items</em></strong>, <strong>Creative Tonie <em>Items</em></strong>, and <strong>Disc <em>Items</em></strong> describe an article. Users can own multiple Tonies with the same Tonie Item. There are millions of Tonies, but only thousands of Tonie Items.</p>\n\n<p><strong>Tunes</strong> are purchasable digital content.\nA Tune replaces the entire content of a Creative Tonie or Content Tonie temporarily.<br>\nThe underlying content is still there and will appear again when the Tune is removed.<br>\nUnlike Tonies & Tonieboxes, Tunes are associated to the user personally, instead of a household.<br/>\n\n<p>Most Tunes only fit the Content Tonies of the same <strong>series group</strong>. A series group bundles one or more <strong>series</strong>, often revolving around a character. For example, the series group <em>Benjamin Blümchen</em> might contain the series <em>Benjamin Blümchen Classics</em>, <em>Gute Nacht-Geschichten von Benjamin</em>, and <em>Benjamin Blümchen: New Series</em>.<br>\nSome Tunes fit on all Creative Tonies.</p>\n\n<p>Tunes can be bought or gained by redeeming vouchers.<br>\n<strong>Tunes Items</strong> describe articles the user can buy. Right now, every user can buy a TunesItem only once; the result of that sale is a Tune (identified by the user and Tunes Item).</p>\n\n<p>Tonieplay <strong>Discs</strong> are flat covers that are put on top of a Toniebox 2. They can be removed and locked in a household like Content Tonies.</p>\n\n<p>Every Disc comes with a preinstalled Tonieplay <strong>Game Item</strong>, which defines the software that is executed when the disc is put on top of a Toniebox 2.</p>\n\n<p>The <strong>child</strong> data structure lists the kids active in a household, along with their interests and birth dates (to get special offers).</p>\n\n<h4>Related services</h4>\n\n\n\n<p>The Tonies shop now also has an API! Visit <a href=\"https://api.prod.shop.tonies.com/api\">https://api.prod.shop.tonies.com/api</a> to learn more.</p>\n", "version": "v2"}, "host": "api.prod.tcs.toys", "schemes": ["https"], "basePath": "/v2", "consumes": ["application/json"], "produces": ["application/json"], "securityDefinitions": {"sso": {"type": "oauth2", "flow": "implicit", "scopes": {"my-tonies": "Toniecloud API"}, "authorizationUrl": "https://login.tonie.cloud/"}}, "security": [{"sso": []}], "paths": {"/box-item-previews": {"get": {"operationId": "box-item-previews_list", "description": "Get Toniebox item data for \"found Toniebox\" previews (shown by the mobile operating system)", "parameters": [], "responses": {"200": {"description": "Returns a list of all item previews", "schema": {"type": "object", "properties": {"bleColorId": {"title": "Color index from BLE Color field", "type": "integer", "readOnly": true}, "displayName": {"title": "Name of the Toniebox, in the user's locale. E.g. \"rote Toniebox\"", "type": "string", "readOnly": true}, "thumbnail": {"title": "URL to a thumbnail for the given Toniebox", "type": "string", "readOnly": true}}}}}, "tags": ["box-item-previews"]}, "parameters": []}, "/check-tune-status": {"post": {"operationId": "check-tune-status_create", "description": "Filter a list of Tunes Item IDs by whether the user can use them with one of their Tonies\n/ already owns them", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"tunesItemIds": {"title": "A list of Tunes Item UUIDs to check", "type": "array", "items": {"title": "UUID of a TunesItem", "type": "string"}, "example": ["6c3d3865-a0ff-4521-b65e-091b1fe76868", "9943191b-55c6-4887-bc24-2b88299c1300", "763eac27-0147-2510-da89-067620dcbed0"]}, "additionalTonieSalesIdsInCart": {"title": "A list of Tonie items that the user is about to buy", "type": "array", "items": {"title": "Sales ID of a Content Tonie item", "type": "string"}, "example": ["01-0013", "10000254"]}}}}], "responses": {"200": {"description": "Information about the Tune status", "schema": {"type": "object", "properties": {"compatibleTunes": {"title": "List of Tunes Item UUIDs from the passed list that the user can apply", "type": "array", "items": {"title": "UUID of a TunesItem", "type": "string"}, "example": ["9943191b-55c6-4887-bc24-2b88299c1300"]}, "boughtTunes": {"title": "List of Tunes Item UUIDs that the user owns", "type": "array", "items": {"title": "UUID of a TunesItem", "type": "string"}, "example": ["763eac27-0147-2510-da89-067620dcbed0"]}}}}}, "tags": ["check-tune-status"]}, "parameters": []}, "/children": {"post": {"operationId": "children_create", "description": "Submit new child entries, automatically figuring out the household and merging it with existing children.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "array", "items": {"$ref": "#/definitions/Child"}}}], "responses": {"200": {"description": "All children have been created or updated.", "schema": {"type": "array", "items": {"type": "object", "properties": {"childCreated": {"title": "true if a new child was created. false if a child was updated.", "type": "boolean"}, "householdCreated": {"title": "true if a new household was created. false if an existing household was used.", "type": "boolean"}, "householdId": {"title": "Id of the household the child is in", "type": "string", "format": "uuid"}, "child": {"title": "The created or updated child.", "type": "object", "properties": {"id": {"title": "UUID of this child", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "Name of this child. null for no name given.", "type": "string"}, "birthDate": {"title": "Optional birth date. A full ISO date like \"2020-12-31\", or year and month, like \"2020-12\", or unspecified (null).", "type": "string"}, "gender": {"title": "One of \"male\", \"female\", \"diverse\". null for unspecified.", "type": "string", "choices": [null, "male", "female", "diverse"]}, "situations": {"title": "List of situations that this child uses Tonieboxes in.  For example [\"playMovement\", \"singalong\", \"learning\", \"relaxing\", \"travel\", \"bedtimeRoutine\"]. Can be empty. null for unspecified.", "type": "array", "items": {"type": "string"}}, "flowIdentifier": {"title": "Identifier of in which part of which application the child was last updated. Freetext, something like \"app-android-toniebox-v1\" or so. Optional. Write-only, will not be included in responses.", "type": "string"}, "taxonomiesPreferences": {"title": "List of taxonomies the child prefers, e.g.  [\"subject:animals\",\"subject:space\",\"character_name:moana\",\"character_name:elmo\"]", "type": "array", "items": {"type": "string"}}, "taxonomiesAvoid": {"title": "List of taxonomies to avoid, e.g. [\"content_sensitive:ghosts_monsters\",\"content_sensitive:grossout_pottyhumor\"]", "type": "array", "items": {"type": "string"}}, "tonieboxIds": {"title": "Toniebox IDs of the Tonieboxes this child interacts with in this household.", "type": "array", "items": {"type": "string"}}}}}}}}}, "tags": ["children"]}, "parameters": []}, "/config": {"get": {"operationId": "config_list", "description": "Get information about the backend configuration.\nDoes not require authentication.", "parameters": [], "responses": {"200": {"description": "The backend configuration.", "schema": {"type": "object", "properties": {"locales": {"title": "All supported locales in POSIX format (e.g. en_US)", "type": "array", "items": {"title": "Locale, either in the format \"ab\" or \"ab_CD\".", "type": "string"}, "example": ["de", "en", "en_US", "fr"]}, "unicodeLocales": {"title": "All supported locales, in Unicode format (e.g. en-US)", "type": "array", "items": {"title": "Locale in Unicode format, either in the format \"ab\" or \"ab-CD\".", "type": "string"}, "example": ["de", "en", "en-US", "fr"]}, "maxChapters": {"title": "Number of maximum chapters that fit on a Creative Tonie", "type": "integer", "example": 99}, "maxSeconds": {"title": "Maximum total duration of all files per Creative Tonie", "type": "integer", "example": 5400}, "maxBytes": {"title": "Maximum size of an uploaded file, in Byte", "type": "integer", "format": "int64", "example": 1073741824}, "accepts": {"title": "A list of file extensions corresponding to the file types accepted by the Toniecloud. This is a machine-readable format including obscure extensions, and different from the list of file formats the user sees.", "type": "array", "items": {"title": "extension", "type": "string", "example": "mp3"}, "example": ["aac", "aif", "aiff", "flac", "mp3", "m4a", "m4b", "wav", "oga", "ogg", "opus", "wma"]}, "stageWarning": {"title": "Whether to show a warning to the user that this site is for development only.", "type": "boolean", "example": false}, "ssoEnabled": {"title": "SSO status", "type": "boolean", "example": true}, "features": {"title": "List of enabled features for the current user.", "type": "array", "items": {"type": "string"}}}}}}, "tags": ["config"]}, "parameters": []}, "/consents/{consent_type}": {"get": {"operationId": "consents_read", "description": "Get the current consent status.\n\"under3\": Consent that the user's child is under 3 years old.\n", "parameters": [], "responses": {"200": {"description": "The current consent status", "schema": {"$ref": "#/definitions/Consent"}}, "404": {"description": "The specified consent type does not exist. (Should be one of \"under3\".)"}}, "tags": ["consents"]}, "patch": {"operationId": "consents_partial_update", "description": "Change consent status.\n\"under3\": Consent that the user's child is under 3 years old.\n", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"choice": {"title": "\"accepted\" (user consented) or \"declined\" (user declined the consent) or null (no information)", "type": "string", "choices": [null, "declined", "accepted"]}}}}], "responses": {"200": {"description": "The new consent status", "schema": {"$ref": "#/definitions/Consent"}}, "400": {"description": "Invalid consent body"}, "404": {"description": "The specified consent type does not exist. (Should be one of \"under3\".)"}}, "tags": ["consents"]}, "parameters": [{"name": "consent_type", "in": "path", "required": true, "type": "string"}]}, "/contenttonieitems/{sales_id}/compatible-tunes-item-sales-ids": {"get": {"operationId": "contenttonieitems_compatible-tunes-item-sales-ids_list", "description": "", "parameters": [{"name": "limit", "in": "query", "description": "Limit the number of returned Tunes item sales IDs", "required": false, "type": "integer", "default": 200, "maximum": 500, "minimum": 1}, {"name": "sales_id", "in": "path", "description": "Sales ID of the ContentTonieItem", "required": true, "type": "string"}], "responses": {"200": {"description": "Returns an array of Tunes item sales IDs this Content Tonie item is compatible with.", "schema": {"type": "array", "items": {"type": "string"}}}}, "tags": ["contenttonieitems"]}, "parameters": [{"name": "sales_id", "in": "path", "required": true, "type": "string"}]}, "/file": {"post": {"operationId": "file_create", "description": "Create a new pre-signed URL to upload a media file to.", "parameters": [], "responses": {"200": {"description": "Signed URL creation successful. Send a multipart/form-data POST request with the specified parameters (and the file called as the \"file\" parameter) to upload the file.", "schema": {"type": "object", "properties": {"request": {"title": "Configuration for the upload to Amazon S3", "type": "object", "properties": {"url": {"title": "S3 URL to send the PUT request to", "type": "string", "format": "url"}, "fields": {"title": "Form fields to send. Include a MIME part with header'Content-Disposition: form-data; name=\"key\"', where key is the dictionary key, and the MIME part body  is taken from the dictionary value.", "type": "object", "additionalProperties": true}}}, "fileId": {"title": "Id of the file that has been uploaded. Hold on to it; it will identify the file after the upload has finished", "type": "string", "format": "uuid"}}}}, "409": {"description": "The current user has not accepted the Terms of Use. For legal reasons, users must accept the Terms of Use once again before uploading files, even though the Terms of <em>Use</em> are identical to the Terms of <em>Service</em> the user agreed to during registration.<br/><br/> Before entering any upload screen, the frontend should show a dialog with a link to the Terms of Service and a confirmation button (wired to <code>PATCH /v2/me</code> with <code>{\"acceptedTermsOfUse\": true}</code>) unless <code>me {acceptedTermsOfUse}</code> in GraphQL is already set."}}, "tags": ["file"]}, "parameters": []}, "/flags": {"get": {"operationId": "flags_list", "description": "", "parameters": [], "responses": {"200": {"description": "Flags for content display. The resolution of these values is a backend implementation detail", "schema": {"type": "object", "properties": {"contentRegion": {"title": "Region where content should be presented from. \n`dach` (Germany, Austria, Switzerland)\n`usa` (USA)\n`can` (Canada)\n`fra` (France & Territories)\n`uki` (UK & Ireland)\n`eur` (Rest of Europe: Poland, Spain, Benelux, Italy etc.)\n`hkg` (Hong Kong & Macao)\n`aus` (Australia)\n`nzl` (New Zealand)\n`chn` (Mainland China)\n`row` (Rest of World. This is usually handled like the `uki` region)", "type": "string", "enum": ["aus", "can", "chn", "dach", "eur", "fra", "hkg", "nzl", "row", "uki", "usa"], "readOnly": true}, "canBuyTunes": {"title": "Whether the current user can buy Tunes, i.e. whether to show the \"Discover\" tab of the audio library. The precise resolution of this value is an implementation detail.", "type": "boolean", "readOnly": true}, "retailerUrl": {"title": "URL of the retailer portal, if any. null if no retailer shop exists in the current region. The precise resolution of this value is an implementation detail.", "type": "string", "readOnly": true}}}}}, "tags": ["flags"]}, "parameters": []}, "/geoip": {"get": {"operationId": "geoip_list", "description": "", "parameters": [], "responses": {"200": {"description": "The current location of the user as determined via GeoIP, independent of the user's profile or settings", "schema": {"type": "object", "properties": {"country": {"title": "The ISO 3166 Alpha 2 country code, lower-case, e.g. \"de\" for Germany. \"zz\" if the country cannot be determined.", "type": "string", "example": "de"}, "region": {"title": "Region where the user is located, as determined by GeoIP.\n`dach` (Germany, Austria, Switzerland)\n`usa` (USA)\n`can` (Canada)\n`fra` (France & Territories)\n`uki` (UK & Ireland)\n`eur` (Rest of Europe: Poland, Spain, Benelux, Italy etc.)\n`hkg` (Hong Kong & Macao)\n`aus` (Australia)\n`nzl` (New Zealand)\n`chn` (Mainland China)\n`row` (Rest of World. This is usually handled like the `uki` region)", "type": "string", "enum": ["aus", "can", "chn", "dach", "eur", "fra", "hkg", "nzl", "row", "uki", "usa"], "readOnly": true}, "canBuyTunes": {"title": "Deprecated. Use flags.canBuyTunes.", "type": "boolean", "readOnly": true}, "retailerUrl": {"title": "URL of the retailer portal, if any. null if no retailer shop exists in the current region.", "type": "string", "readOnly": true}}}}}, "tags": ["geoip"]}, "parameters": []}, "/households": {"get": {"operationId": "households_list", "description": "List all households the user can access", "parameters": [], "responses": {"200": {"description": "All households the user can access", "schema": {"type": "array", "items": {"type": "object", "properties": {"id": {"title": "The ID of the household", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "The human-readable name of the household", "type": "string", "maxLength": 30, "minLength": 1}, "ownerName": {"title": "First name of the owner, if available", "type": "string", "readOnly": true}, "image": {"title": "name of the household's image", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}, "foreignCreativeTonieContent": {"title": "Can Creative Tonies from other households be played on Tonieboxes in this one?", "type": "boolean", "default": true}, "access": {"title": "The type of access rights the current user has", "type": "string", "enum": ["owner", "full", "limited"], "readOnly": true}, "canLeave": {"title": "Whether the current user can leave the household. Limited and full users can always leave. Owners can only leave if there is somebody they can transfer the household to.", "type": "boolean", "readOnly": true}}}}}}, "tags": ["households"]}, "post": {"operationId": "households_create", "description": "Create a new household", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"name": {"title": "The human-readable name of the household", "type": "string", "maxLength": 30, "minLength": 1}, "image": {"title": "name of the household's image", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}, "foreignCreativeTonieContent": {"title": "Can Creative Tonies from other households be played on Tonieboxes in this one?", "type": "boolean", "default": true}}}}], "responses": {"201": {"description": "Household created. Use /v2/households/{id} to update or delete it.", "schema": {"type": "object", "properties": {"id": {"title": "The ID of the household", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "The human-readable name of the household", "type": "string", "maxLength": 30, "minLength": 1}, "ownerName": {"title": "First name of the owner, if available", "type": "string", "readOnly": true}, "image": {"title": "name of the household's image", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}, "foreignCreativeTonieContent": {"title": "Can Creative Tonies from other households be played on Tonieboxes in this one?", "type": "boolean", "default": true}, "access": {"title": "The type of access rights the current user has", "type": "string", "enum": ["owner", "full", "limited"], "readOnly": true}, "canLeave": {"title": "Whether the current user can leave the household. Limited and full users can always leave. Owners can only leave if there is somebody they can transfer the household to.", "type": "boolean", "readOnly": true}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "409": {"description": "The user has a household already (every user can only own one household). Send requests to /v2/households/{household.id} to update or delete it.", "schema": {"type": "object", "properties": {"currentHouseholdId": {"description": "The id of the current user's household.", "type": "string", "format": "uuid"}, "household": {"type": "object", "properties": {"id": {"title": "The ID of the household", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "The human-readable name of the household", "type": "string", "maxLength": 30, "minLength": 1}, "ownerName": {"title": "First name of the owner, if available", "type": "string", "readOnly": true}, "image": {"title": "name of the household's image", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}, "foreignCreativeTonieContent": {"title": "Can Creative Tonies from other households be played on Tonieboxes in this one?", "type": "boolean", "default": true}, "access": {"title": "The type of access rights the current user has", "type": "string", "enum": ["owner", "full", "limited"], "readOnly": true}, "canLeave": {"title": "Whether the current user can leave the household. Limited and full users can always leave. Owners can only leave if there is somebody they can transfer the household to.", "type": "boolean", "readOnly": true}}, "description": "The already existing household of the user."}}}}}, "tags": ["households"]}, "parameters": []}, "/households/{household_pk}/children": {"get": {"operationId": "households_children_list", "description": "List all children in a household.", "parameters": [], "responses": {"200": {"description": "All children in this household.", "schema": {"type": "array", "items": {"type": "object", "properties": {"id": {"title": "UUID of this child", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "Name of this child. null for no name given.", "type": "string"}, "birthDate": {"title": "Optional birth date. A full ISO date like \"2020-12-31\", or year and month, like \"2020-12\", or unspecified (null).", "type": "string"}, "gender": {"title": "One of \"male\", \"female\", \"diverse\". null for unspecified.", "type": "string", "choices": [null, "male", "female", "diverse"]}, "situations": {"title": "List of situations that this child uses Tonieboxes in.  For example [\"playMovement\", \"singalong\", \"learning\", \"relaxing\", \"travel\", \"bedtimeRoutine\"]. Can be empty. null for unspecified.", "type": "array", "items": {"type": "string"}}, "flowIdentifier": {"title": "Identifier of in which part of which application the child was last updated. Freetext, something like \"app-android-toniebox-v1\" or so. Optional. Write-only, will not be included in responses.", "type": "string"}, "taxonomiesPreferences": {"title": "List of taxonomies the child prefers, e.g.  [\"subject:animals\",\"subject:space\",\"character_name:moana\",\"character_name:elmo\"]", "type": "array", "items": {"type": "string"}}, "taxonomiesAvoid": {"title": "List of taxonomies to avoid, e.g. [\"content_sensitive:ghosts_monsters\",\"content_sensitive:grossout_pottyhumor\"]", "type": "array", "items": {"type": "string"}}, "tonieboxIds": {"title": "Toniebox IDs of the Tonieboxes this child interacts with in this household.", "type": "array", "items": {"type": "string"}}}}}}, "403": {"description": "The user is a limited member in the specified household. Only full members and owners can create, edit, or list household children."}, "404": {"description": "The specified household does not exist, or the current user is not a member in it."}}, "tags": ["households"]}, "post": {"operationId": "households_children_create", "description": "Create a child entry.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"$ref": "#/definitions/Child"}}], "responses": {"201": {"description": "The child has been created.", "schema": {"type": "object", "properties": {"id": {"title": "UUID of this child", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "Name of this child. null for no name given.", "type": "string"}, "birthDate": {"title": "Optional birth date. A full ISO date like \"2020-12-31\", or year and month, like \"2020-12\", or unspecified (null).", "type": "string"}, "gender": {"title": "One of \"male\", \"female\", \"diverse\". null for unspecified.", "type": "string", "choices": [null, "male", "female", "diverse"]}, "situations": {"title": "List of situations that this child uses Tonieboxes in.  For example [\"playMovement\", \"singalong\", \"learning\", \"relaxing\", \"travel\", \"bedtimeRoutine\"]. Can be empty. null for unspecified.", "type": "array", "items": {"type": "string"}}, "flowIdentifier": {"title": "Identifier of in which part of which application the child was last updated. Freetext, something like \"app-android-toniebox-v1\" or so. Optional. Write-only, will not be included in responses.", "type": "string"}, "taxonomiesPreferences": {"title": "List of taxonomies the child prefers, e.g.  [\"subject:animals\",\"subject:space\",\"character_name:moana\",\"character_name:elmo\"]", "type": "array", "items": {"type": "string"}}, "taxonomiesAvoid": {"title": "List of taxonomies to avoid, e.g. [\"content_sensitive:ghosts_monsters\",\"content_sensitive:grossout_pottyhumor\"]", "type": "array", "items": {"type": "string"}}, "tonieboxIds": {"title": "Toniebox IDs of the Tonieboxes this child interacts with in this household.", "type": "array", "items": {"type": "string"}}}}}, "403": {"description": "The user is a limited member in the specified household. Only full members and owners can create, edit, or list household children."}, "404": {"description": "The specified household does not exist, or the current user is not a member in it."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/children/{id}": {"get": {"operationId": "households_children_read", "description": "Get information about a child.", "parameters": [], "responses": {"200": {"description": "Information about this child.", "schema": {"type": "object", "properties": {"id": {"title": "UUID of this child", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "Name of this child. null for no name given.", "type": "string"}, "birthDate": {"title": "Optional birth date. A full ISO date like \"2020-12-31\", or year and month, like \"2020-12\", or unspecified (null).", "type": "string"}, "gender": {"title": "One of \"male\", \"female\", \"diverse\". null for unspecified.", "type": "string", "choices": [null, "male", "female", "diverse"]}, "situations": {"title": "List of situations that this child uses Tonieboxes in.  For example [\"playMovement\", \"singalong\", \"learning\", \"relaxing\", \"travel\", \"bedtimeRoutine\"]. Can be empty. null for unspecified.", "type": "array", "items": {"type": "string"}}, "flowIdentifier": {"title": "Identifier of in which part of which application the child was last updated. Freetext, something like \"app-android-toniebox-v1\" or so. Optional. Write-only, will not be included in responses.", "type": "string"}, "taxonomiesPreferences": {"title": "List of taxonomies the child prefers, e.g.  [\"subject:animals\",\"subject:space\",\"character_name:moana\",\"character_name:elmo\"]", "type": "array", "items": {"type": "string"}}, "taxonomiesAvoid": {"title": "List of taxonomies to avoid, e.g. [\"content_sensitive:ghosts_monsters\",\"content_sensitive:grossout_pottyhumor\"]", "type": "array", "items": {"type": "string"}}, "tonieboxIds": {"title": "Toniebox IDs of the Tonieboxes this child interacts with in this household.", "type": "array", "items": {"type": "string"}}}}}, "403": {"description": "The user is a limited member in the specified household. Only full members and owners can create, edit, or list household children."}, "404": {"description": "The specified household does not exist, or the current user is not a member in it."}}, "tags": ["households"]}, "patch": {"operationId": "households_children_partial_update", "description": "Change a child.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"$ref": "#/definitions/Child"}}], "responses": {"201": {"description": "The child entry was changed.", "schema": {"type": "object", "properties": {"id": {"title": "UUID of this child", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "Name of this child. null for no name given.", "type": "string"}, "birthDate": {"title": "Optional birth date. A full ISO date like \"2020-12-31\", or year and month, like \"2020-12\", or unspecified (null).", "type": "string"}, "gender": {"title": "One of \"male\", \"female\", \"diverse\". null for unspecified.", "type": "string", "choices": [null, "male", "female", "diverse"]}, "situations": {"title": "List of situations that this child uses Tonieboxes in.  For example [\"playMovement\", \"singalong\", \"learning\", \"relaxing\", \"travel\", \"bedtimeRoutine\"]. Can be empty. null for unspecified.", "type": "array", "items": {"type": "string"}}, "flowIdentifier": {"title": "Identifier of in which part of which application the child was last updated. Freetext, something like \"app-android-toniebox-v1\" or so. Optional. Write-only, will not be included in responses.", "type": "string"}, "taxonomiesPreferences": {"title": "List of taxonomies the child prefers, e.g.  [\"subject:animals\",\"subject:space\",\"character_name:moana\",\"character_name:elmo\"]", "type": "array", "items": {"type": "string"}}, "taxonomiesAvoid": {"title": "List of taxonomies to avoid, e.g. [\"content_sensitive:ghosts_monsters\",\"content_sensitive:grossout_pottyhumor\"]", "type": "array", "items": {"type": "string"}}, "tonieboxIds": {"title": "Toniebox IDs of the Tonieboxes this child interacts with in this household.", "type": "array", "items": {"type": "string"}}}}}, "403": {"description": "The user is a limited member in the specified household. Only full members and owners can create, edit, or list household children."}, "404": {"description": "The specified household does not exist, or the current user is not a member in it."}}, "tags": ["households"]}, "delete": {"operationId": "households_children_delete", "description": "Delete a child entry.", "parameters": [], "responses": {"204": {"description": "The child has been removed from the household."}, "403": {"description": "You are not allowed to change children (i.e. you are a limited user)."}, "404": {"description": "The specified household does not exist, or the current user is not a member in it."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/contenttonies/{contenttonie_pk}/permissions/{id}": {"put": {"operationId": "households_contenttonies_permissions_update", "description": "Change the permissions of a specific household member on this Content Tonie.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"required": ["permission"], "type": "object", "properties": {"permission": {"title": "The desired permission: explicit=checked, none=unchecked", "type": "string", "enum": ["explicit", "none"]}}}}], "responses": {"200": {"description": "The new permission of the specified membership.", "schema": {"type": "object", "properties": {"membershipId": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address).", "type": "string", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "permission": {"title": "The permissions of the user on this Content Tonie.\n\"implicit\": the user is a full user or owner and thus has unrestricted access (checkbox checked & readonly).\n \"explicit\": This user is limited and has been granted access to this Content Tonie (checkbox checked).\n \"none\": The user is limited and can not access the Content Tonie (checkbox clear).", "type": "string", "enum": ["implicit", "explicit", "none"]}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "The current user has only limited permissions and tried to view or change a Content Tonie's permissions. Only full users and owners can do that."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Content Tonie does not exist, or the current user is not allowed to access the Content Tonie."}, "409": {"description": "Invalid update: The user whose permissions should be updated is a full user or owner. Downgrade the user to limited if you want to edit the permissions in detail."}}, "tags": ["households"]}, "patch": {"operationId": "households_contenttonies_permissions_partial_update", "description": "Change the permissions of a specific household member on this Content Tonie.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"permission": {"title": "The desired permission: explicit=checked, none=unchecked", "type": "string", "enum": ["explicit", "none"]}}}}], "responses": {"200": {"description": "The new permission of the specified membership.", "schema": {"type": "object", "properties": {"membershipId": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address).", "type": "string", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "permission": {"title": "The permissions of the user on this Content Tonie.\n\"implicit\": the user is a full user or owner and thus has unrestricted access (checkbox checked & readonly).\n \"explicit\": This user is limited and has been granted access to this Content Tonie (checkbox checked).\n \"none\": The user is limited and can not access the Content Tonie (checkbox clear).", "type": "string", "enum": ["implicit", "explicit", "none"]}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "The current user has only limited permissions and tried to view or change a Content Tonie's permissions. Only full users and owners can do that."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Content Tonie does not exist, or the current user is not allowed to access the Content Tonie."}, "409": {"description": "Invalid update: The user whose permissions should be updated is a full user or owner. Downgrade the user to limited if you want to edit the permissions in detail."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "contenttonie_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/contenttonies/{id}": {"patch": {"operationId": "households_contenttonies_partial_update", "description": "Change properties of a Content Tonie.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"$ref": "#/definitions/ContentToniePatchRequest"}}, {"name": "id", "in": "query", "description": "Content Tonie ID", "required": true, "type": "string"}, {"name": "household_pk", "in": "query", "description": "Household ID", "required": true, "type": "string"}], "responses": {"200": {"description": "Updated successfully. (returns the changed data)"}, "204": {"description": "No changes were made."}}, "tags": ["households"]}, "delete": {"operationId": "households_contenttonies_delete", "description": "Remove this Content Tonie from the household.\nThis also deletes all tunes and permissions on the Content Tonie;\nit should require the user's confirmation!", "parameters": [], "responses": {"204": {"description": "The Content Tonie was removed from this household."}, "403": {"description": "The current user is not allowed to delete the Content Tonie, because he is not a superuser in the household."}, "404": {"description": "The household does not exist, or the Content Tonie does not exist or the Content Tonie is not in the household"}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/creativetonies": {"get": {"operationId": "households_creativetonies_list", "description": "List all Creative Tonies", "parameters": [], "responses": {"200": {"description": "All Creative Tonies in this household that the current user can access.", "schema": {"type": "array", "items": {"$ref": "#/definitions/CreativeTonie"}}}, "404": {"description": "The household does not exist, or the current user is not allowed to access it."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/creativetonies/{creativetonie_pk}/chapters": {"post": {"operationId": "households_creativetonies_chapters_create", "description": "Add a new Chapter to the end of the Creative Tonie content", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"$ref": "#/definitions/AddChapter"}}], "responses": {"200": {"description": "The changed Creative Tonie.", "schema": {"$ref": "#/definitions/CreativeTonie"}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `tooMany` - The new chapter will not fit onto the Tonie, because there can only be 99 chapters per Tonie\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["tooMany", "required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "The current user has a limited membership and tried to update name or private mode."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Creative Tonie does not exist, or the current user is not allowed to access the Creative Tonie."}}, "tags": ["households"], "deprecated": true}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "creativetonie_pk", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/creativetonies/{creativetonie_pk}/permissions": {"get": {"operationId": "households_creativetonies_permissions_list", "description": "List the permissions of all household members on this Creative Tonie.", "parameters": [], "responses": {"200": {"description": "All Creative Tonies in this household that the current user can access. The list is sorted: Implicit permissions (=full user/owner) come first, and limited users are sorted by first name.", "schema": {"type": "array", "items": {"type": "object", "properties": {"membershipId": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address).", "type": "string", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "permission": {"title": "The permissions of the user on this Creative Tonie.\n\"implicit\": the user is a full user or owner and thus has unrestricted access (checkbox checked & readonly).\n \"explicit\": This user is limited and has been granted access to this Creative Tonie (checkbox checked).\n \"none\": The user is limited and can not access the Creative Tonie (checkbox clear).", "type": "string", "enum": ["implicit", "explicit", "none"]}}}}}, "403": {"description": "The current user has only limited permissions and tried to view or change a Creative Tonie's permissions. Only full users and owners can do that."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Creative Tonie does not exist, or the current user is not allowed to access the Creative Tonie."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "creativetonie_pk", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/creativetonies/{creativetonie_pk}/permissions/{id}": {"get": {"operationId": "households_creativetonies_permissions_read", "description": "Get the permissions of a specific household member on this Creative Tonie.", "parameters": [], "responses": {"200": {"description": "The permission of the specified membership.", "schema": {"type": "object", "properties": {"membershipId": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address).", "type": "string", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "permission": {"title": "The permissions of the user on this Creative Tonie.\n\"implicit\": the user is a full user or owner and thus has unrestricted access (checkbox checked & readonly).\n \"explicit\": This user is limited and has been granted access to this Creative Tonie (checkbox checked).\n \"none\": The user is limited and can not access the Creative Tonie (checkbox clear).", "type": "string", "enum": ["implicit", "explicit", "none"]}}}}, "403": {"description": "The current user has only limited permissions and tried to view or change a Creative Tonie's permissions. Only full users and owners can do that."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Creative Tonie does not exist, or the current user is not allowed to access the Creative Tonie."}}, "tags": ["households"]}, "put": {"operationId": "households_creativetonies_permissions_update", "description": "Change the permissions of a specific household member on this Creative Tonie.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"required": ["permission"], "type": "object", "properties": {"permission": {"title": "The desired permission: explicit=checked, none=unchecked", "type": "string", "enum": ["explicit", "none"]}}}}], "responses": {"200": {"description": "The new permission of the specified membership.", "schema": {"type": "object", "properties": {"membershipId": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address).", "type": "string", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "permission": {"title": "The permissions of the user on this Creative Tonie.\n\"implicit\": the user is a full user or owner and thus has unrestricted access (checkbox checked & readonly).\n \"explicit\": This user is limited and has been granted access to this Creative Tonie (checkbox checked).\n \"none\": The user is limited and can not access the Creative Tonie (checkbox clear).", "type": "string", "enum": ["implicit", "explicit", "none"]}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "The current user has only limited permissions and tried to view or change a Creative Tonie's permissions. Only full users and owners can do that."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Creative Tonie does not exist, or the current user is not allowed to access the Creative Tonie."}, "409": {"description": "Invalid update: The user whose permissions should be updated is a full user or owner. Downgrade the user to limited if you want to edit the permissions in detail."}}, "tags": ["households"]}, "patch": {"operationId": "households_creativetonies_permissions_partial_update", "description": "Change the permissions of a specific household member on this Creative Tonie.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"permission": {"title": "The desired permission: explicit=checked, none=unchecked", "type": "string", "enum": ["explicit", "none"]}}}}], "responses": {"200": {"description": "The new permission of the specified membership.", "schema": {"type": "object", "properties": {"membershipId": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address).", "type": "string", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "permission": {"title": "The permissions of the user on this Creative Tonie.\n\"implicit\": the user is a full user or owner and thus has unrestricted access (checkbox checked & readonly).\n \"explicit\": This user is limited and has been granted access to this Creative Tonie (checkbox checked).\n \"none\": The user is limited and can not access the Creative Tonie (checkbox clear).", "type": "string", "enum": ["implicit", "explicit", "none"]}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "The current user has only limited permissions and tried to view or change a Creative Tonie's permissions. Only full users and owners can do that."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Creative Tonie does not exist, or the current user is not allowed to access the Creative Tonie."}, "409": {"description": "Invalid update: The user whose permissions should be updated is a full user or owner. Downgrade the user to limited if you want to edit the permissions in detail."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "creativetonie_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/creativetonies/{creativetonie_pk}/redeem-token": {"post": {"operationId": "households_creativetonies_redeem-token_create", "description": "Add pre-defined content to a Creative Tonie", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"token": {"description": "The token for the content to add. Tokens are not handed out via this API; they are configured via the admin interface.", "type": "string", "example": "toniesong", "minLength": 1}}}}], "responses": {"200": {"description": "Successfully added content to the Creative Tonie. The Tonie will be transcoded immediately. Poll it and wait for its \"transcoding\" property to toggle to false.", "schema": {"type": "object", "properties": {}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `tooMany` - The new chapters will not fit onto the Tonie, because there can only be 99 chapters per Tonie\n\n- `tooLong` - The new chapters will not fit onto the Tonie, because there can only be 5400 seconds on a Tonie\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["tooMany", "tooLong", "required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "The specified token cannot be used on this Tonie by the current user.", "schema": {"type": "object", "properties": {"reason": {"title": "\"edu\": This content is only available to education users. \"onlyAssociated\": This content is only available on associated Creative Tonies.\"expired\": This Content Token is expired. \"geoip\": This Content Token is not licensed in the user's  GeoIP location.", "type": "string", "enum": ["edu", "onlyAssociated", "geoip", "expired"]}}}}, "404": {"description": "Cannot access household, Creative Tonie, or token.", "schema": {"type": "object", "properties": {"reason": {"title": "Which object could not be found:\n\"household\" if the household is not present (or the current user is not a member), \"tonie\" if the user cannot access the specified Creative Tonie (check: is it in this household? If the user is a limited user, can they access it?), \"token\" if the token is invalid.", "type": "string", "enum": ["household", "tonie", "token"]}}}}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "creativetonie_pk", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/creativetonies/{id}": {"get": {"operationId": "households_creativetonies_read", "description": "Get information about a specific Creative Tonie.", "parameters": [], "responses": {"200": {"description": "The requested Creative Tonie.", "schema": {"$ref": "#/definitions/CreativeTonie"}}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Creative Tonie does not exist, or the current user is not allowed to access the Creative Tonie."}}, "tags": ["households"]}, "put": {"operationId": "households_creativetonies_update", "description": "Change properties of a Creative Tonie. Including the key \"chapters\" will trigger a new transcoding if the content is changed. Title changes do not trigger a transcoding, and reoderings only trigger a transcoding of the whole Tonie. Set \"chapters\" to [] (empty array) to clear the Creative Tonie.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"name": {"title": "The human-readable name of the Creative Tonie.", "type": "string", "example": "John's favorite red Tonie", "maxLength": 100}, "live": {"title": "Whether live mode is active. When live mode is active, new content gets inserted at the beginning instead of the end.", "type": "boolean", "default": false}, "private": {"title": "Private mode.\nIf enabled, then only Tonieboxes registered in this household can play this Tonie. Tonieboxes without a household or in other households will get an error message.\nIf private=false, then every Toniebox can play this Tonie.", "type": "boolean", "default": false}, "transcodingErrors": {"title": "A list of transcoding errors that happened since the last transcoding (i.e. a PUT or PATCH with different chapters).", "type": "array", "items": {"type": "object", "properties": {"reason": {"title": "Error type of why the transcoding failed. \"wrongFormat\" if a file was in an unsupported format, \"tooLong\" if all files exceeded 90 minutes in total, \"unknownError\" for internal errors.", "type": "string", "enum": ["wrongFormat", "tooLong", "unknownError"]}, "deletedChapters": {"title": "The chapters that were removed because of the error, if any.", "type": "array", "items": {"type": "object", "properties": {"title": {"title": "Human-readable name for this chapter", "type": "string", "example": "My recording on 2018-08-16", "maxLength": 128}, "seconds": {"title": "Length of this chapter in seconds. Available only if reason is \"tooLong\".", "type": "number"}}}}}}}, "chapters": {"title": "All chapters on this Creative Tonie", "type": "array", "items": {"title": "Chapter", "required": ["title", "file"], "type": "object", "properties": {"id": {"title": "ID of this chapter (for existing chapters)", "type": "string", "format": "uuid"}, "title": {"title": "Human-readable name for this chapter", "type": "string", "example": "My recording on 2018-08-16", "maxLength": 128}, "file": {"title": "File identifier. For new chapters: a UUID (see POST /file on how to generate it). For existing chapters: an opaque blob(only used in case of concurrent editing by another device). Starts with \"ContentToken:\" if this chapter is from a Content Token, followed by the content token followed by \":\", followed by the 0-indexed chapter of the Content Token.", "type": "string", "example": "ContentToken:toniesong:0"}, "additionalData": {"title": "Additional generic/schema-less information about a chapter.", "type": "object", "properties": {}, "example": "{\"read-along-story-id\":\"foobar\"}"}}}}, "type": {"title": "The type of the chapter. Possible values are: [\"recording\", \"file\", \"content-token\", \"tunes-item\", \"native-content\", \"cloud-recording\"]", "type": "string", "example": "recording"}}}}], "responses": {"200": {"description": "The changed Creative Tonie.", "schema": {"$ref": "#/definitions/CreativeTonie"}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `invalidChapters` - The chapters definition is invalid.  Since this is a nested field and errors can be particularily complex, there will be a developer-readable message in the \"message\" key. Note as many of the checks depend on each other and to make sure we don't mix up checks and usage, only the first error will be reported.\n\n- `tooLong` - The total length exceeds the limit of 5400 seconds. Note: In most cases of overlong content, the request will succeed, and the length will be determined during the transcoding process. tooLong will only be returned if the lengths of all chapters is already known, for example because only Content Tokens were added.\n\n- `chapterFileTooLong` - The \"file\" value is longer than 1024 characters.\n\n- `chapterFileTooShort` - The \"file\" value is shorter than 16 characters.\n\n- `chapterTitleTooLong` - The \"title\" field of a record or file upload chapter is longer than 128 characters.\n\n- `chapterTypeInvalid` - The \"type\" field of a chapter is invalid. Allowed type values are: recording, file, content-token, tunes-item, native-content, cloud-recording.\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["invalidChapters", "tooLong", "chapterFileTooLong", "chapterFileTooShort", "chapterTitleTooLong", "chapterTypeInvalid", "required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}, "errorCode": {"description": "Machine-readable sub error codes:\n\n- `tooManyChapters` - The number of chapters exceeds the limit of 99.\n\n- `chapterFileInvalid` - The \"file\" value contains illegal characters.\n\n- `chapterFileNotStr` - The \"file\" field of a chapter must be a string.\n\n- `chaptersNotList` - The \"chapters\" field must be a list.\n\n- `chapterNotObject` - Each entry in \"chapters\" must be an object.\n\n- `chapterFileMissing` - The \"file\" field in a chapter object is missing.\n\n- `chapterIdNotStr` - The \"id\" field of a chapter must be a UUID string.\n\n- `chapterIdNotUUID` - The \"id\" field of a chapter is not a valid UUID string.\n\n- `invalidTunesItemFileScheme` - The TunesItem \"file\" field scheme is not valid.\n\n- `tunesItemNotFound` - TunesItem not found.\n\n- `tunesItemNotAllowed` - Assignment of TunesItem to this Tonie is not allowed.\n\n- `tunesItemNotOwned` - Used has not owned this TunesItem.\n\n- `tunesItemAssignmentInvalid` - Assignment of TunesItem is invalid.\n\n- `invalidContentToken` - The token value contains illegal characters.\n\n- `contentTokenNotFound` - ContentToken can not be found.\n\n- `contentTokenNotAllowed` - ContentToken is only available on associated Creative Tonie items.\n\n- `contentTokenChapterNotFound` - ContentToken does not have a chapter with this position.\n\n- `chapterTitleMissing` - The record or file upload chapter contains no \"title\" field.\n\n- `chapterTitleNotStr` - The \"title\" field of a record or file upload chapter is not a String.\n\n- `tooLong` - The total length exceeds the limit of 5400 seconds. Note: In most cases of overlong content, the request will succeed, and the length will be determined during the transcoding process. tooLong will only be returned if the lengths of all chapters is already known, for example because only Content Tokens were added.\n\n- `chapterFileTooLong` - The \"file\" value is longer than 1024 characters.\n\n- `chapterFileTooShort` - The \"file\" value is shorter than 16 characters.\n\n- `chapterTitleTooLong` - The \"title\" field of a record or file upload chapter is longer than 128 characters.\n\n- `chapterTypeInvalid` - The \"type\" field of a chapter is invalid. Allowed type values are: recording, file, content-token, tunes-item, native-content, cloud-recording.\n", "type": "string", "enum": ["tooManyChapters", "chapterFileInvalid", "chapterFileNotStr", "chaptersNotList", "chapterNotObject", "chapterFileMissing", "chapterIdNotStr", "chapterIdNotUUID", "invalidTunesItemFileScheme", "tunesItemNotFound", "tunesItemNotAllowed", "tunesItemNotOwned", "tunesItemAssignmentInvalid", "invalidContentToken", "contentTokenNotFound", "contentTokenNotAllowed", "contentTokenChapterNotFound", "chapterTitleMissing", "chapterTitleNotStr", "tooLong", "chapterFileTooLong", "chapterFileTooShort", "chapterTitleTooLong", "chapterTypeInvalid"]}}}}}}}, "403": {"description": "The current user has a limited membership and tried to update name or private mode."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Creative Tonie does not exist, or the current user is not allowed to access the Creative Tonie."}}, "tags": ["households"]}, "patch": {"operationId": "households_creativetonies_partial_update", "description": "Change some properties of a Creative Tonie. Including the key \"chapters\" will trigger a new transcoding if the content is changed. Title changes do not trigger a transcoding, and reoderings only trigger a transcoding of the whole Tonie. Set \"chapters\" to [] (empty array) to clear the Creative Tonie.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"name": {"title": "The human-readable name of the Creative Tonie.", "type": "string", "example": "John's favorite red Tonie", "maxLength": 100}, "live": {"title": "Whether live mode is active. When live mode is active, new content gets inserted at the beginning instead of the end.", "type": "boolean", "default": false}, "private": {"title": "Private mode.\nIf enabled, then only Tonieboxes registered in this household can play this Tonie. Tonieboxes without a household or in other households will get an error message.\nIf private=false, then every Toniebox can play this Tonie.", "type": "boolean", "default": false}, "transcodingErrors": {"title": "A list of transcoding errors that happened since the last transcoding (i.e. a PUT or PATCH with different chapters).", "type": "array", "items": {"type": "object", "properties": {"reason": {"title": "Error type of why the transcoding failed. \"wrongFormat\" if a file was in an unsupported format, \"tooLong\" if all files exceeded 90 minutes in total, \"unknownError\" for internal errors.", "type": "string", "enum": ["wrongFormat", "tooLong", "unknownError"]}, "deletedChapters": {"title": "The chapters that were removed because of the error, if any.", "type": "array", "items": {"type": "object", "properties": {"title": {"title": "Human-readable name for this chapter", "type": "string", "example": "My recording on 2018-08-16", "maxLength": 128}, "seconds": {"title": "Length of this chapter in seconds. Available only if reason is \"tooLong\".", "type": "number"}}}}}}}, "chapters": {"title": "All chapters on this Creative Tonie", "type": "array", "items": {"title": "Chapter", "required": ["title", "file"], "type": "object", "properties": {"id": {"title": "ID of this chapter (for existing chapters)", "type": "string", "format": "uuid"}, "title": {"title": "Human-readable name for this chapter", "type": "string", "example": "My recording on 2018-08-16", "maxLength": 128}, "file": {"title": "File identifier. For new chapters: a UUID (see POST /file on how to generate it). For existing chapters: an opaque blob(only used in case of concurrent editing by another device). Starts with \"ContentToken:\" if this chapter is from a Content Token, followed by the content token followed by \":\", followed by the 0-indexed chapter of the Content Token.", "type": "string", "example": "ContentToken:toniesong:0"}, "additionalData": {"title": "Additional generic/schema-less information about a chapter.", "type": "object", "properties": {}, "example": "{\"read-along-story-id\":\"foobar\"}"}}}}, "type": {"title": "The type of the chapter. Possible values are: [\"recording\", \"file\", \"content-token\", \"tunes-item\", \"native-content\", \"cloud-recording\"]", "type": "string", "example": "recording"}}}}], "responses": {"200": {"description": "The changed Creative Tonie.", "schema": {"$ref": "#/definitions/CreativeTonie"}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `invalidChapters` - The chapters definition is invalid.  Since this is a nested field and errors can be particularily complex, there will be a developer-readable message in the \"message\" key. Note as many of the checks depend on each other and to make sure we don't mix up checks and usage, only the first error will be reported.\n\n- `tooLong` - The total length exceeds the limit of 5400 seconds. Note: In most cases of overlong content, the request will succeed, and the length will be determined during the transcoding process. tooLong will only be returned if the lengths of all chapters is already known, for example because only Content Tokens were added.\n\n- `chapterFileTooLong` - The \"file\" value is longer than 1024 characters.\n\n- `chapterFileTooShort` - The \"file\" value is shorter than 16 characters.\n\n- `chapterTitleTooLong` - The \"title\" field of a record or file upload chapter is longer than 128 characters.\n\n- `chapterTypeInvalid` - The \"type\" field of a chapter is invalid. Allowed type values are: recording, file, content-token, tunes-item, native-content, cloud-recording.\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["invalidChapters", "tooLong", "chapterFileTooLong", "chapterFileTooShort", "chapterTitleTooLong", "chapterTypeInvalid", "required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}, "errorCode": {"description": "Machine-readable sub error codes:\n\n- `tooManyChapters` - The number of chapters exceeds the limit of 99.\n\n- `chapterFileInvalid` - The \"file\" value contains illegal characters.\n\n- `chapterFileNotStr` - The \"file\" field of a chapter must be a string.\n\n- `chaptersNotList` - The \"chapters\" field must be a list.\n\n- `chapterNotObject` - Each entry in \"chapters\" must be an object.\n\n- `chapterFileMissing` - The \"file\" field in a chapter object is missing.\n\n- `chapterIdNotStr` - The \"id\" field of a chapter must be a UUID string.\n\n- `chapterIdNotUUID` - The \"id\" field of a chapter is not a valid UUID string.\n\n- `invalidTunesItemFileScheme` - The TunesItem \"file\" field scheme is not valid.\n\n- `tunesItemNotFound` - TunesItem not found.\n\n- `tunesItemNotAllowed` - Assignment of TunesItem to this Tonie is not allowed.\n\n- `tunesItemNotOwned` - Used has not owned this TunesItem.\n\n- `tunesItemAssignmentInvalid` - Assignment of TunesItem is invalid.\n\n- `invalidContentToken` - The token value contains illegal characters.\n\n- `contentTokenNotFound` - ContentToken can not be found.\n\n- `contentTokenNotAllowed` - ContentToken is only available on associated Creative Tonie items.\n\n- `contentTokenChapterNotFound` - ContentToken does not have a chapter with this position.\n\n- `chapterTitleMissing` - The record or file upload chapter contains no \"title\" field.\n\n- `chapterTitleNotStr` - The \"title\" field of a record or file upload chapter is not a String.\n\n- `tooLong` - The total length exceeds the limit of 5400 seconds. Note: In most cases of overlong content, the request will succeed, and the length will be determined during the transcoding process. tooLong will only be returned if the lengths of all chapters is already known, for example because only Content Tokens were added.\n\n- `chapterFileTooLong` - The \"file\" value is longer than 1024 characters.\n\n- `chapterFileTooShort` - The \"file\" value is shorter than 16 characters.\n\n- `chapterTitleTooLong` - The \"title\" field of a record or file upload chapter is longer than 128 characters.\n\n- `chapterTypeInvalid` - The \"type\" field of a chapter is invalid. Allowed type values are: recording, file, content-token, tunes-item, native-content, cloud-recording.\n", "type": "string", "enum": ["tooManyChapters", "chapterFileInvalid", "chapterFileNotStr", "chaptersNotList", "chapterNotObject", "chapterFileMissing", "chapterIdNotStr", "chapterIdNotUUID", "invalidTunesItemFileScheme", "tunesItemNotFound", "tunesItemNotAllowed", "tunesItemNotOwned", "tunesItemAssignmentInvalid", "invalidContentToken", "contentTokenNotFound", "contentTokenNotAllowed", "contentTokenChapterNotFound", "chapterTitleMissing", "chapterTitleNotStr", "tooLong", "chapterFileTooLong", "chapterFileTooShort", "chapterTitleTooLong", "chapterTypeInvalid"]}}}}}}}, "403": {"description": "The current user has a limited membership and tried to update name or private mode."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Creative Tonie does not exist, or the current user is not allowed to access the Creative Tonie."}, "429": {"description": "Transcoding rate limit reached. This is unlikely to happen in normal usage; check for transcoding requests in any loop.", "schema": {"type": "object", "properties": {"retryInSeconds": {"title": "Duration the user should hold off any further transcoding(all requests will return 429)", "type": "integer"}}}}}, "tags": ["households"]}, "delete": {"operationId": "households_creativetonies_delete", "description": "Remove this Creative Tonie from the household.\nThis also deletes all creative content, tunes and permissions on the Creative Tonie;\nit should require the user's confirmation!\nPut the Creative Tonie on another box to see add it again.", "parameters": [], "responses": {"204": {"description": "The Creative Tonie has been emptied and removed from this household. Put it onto a Toniebox to use it again."}, "403": {"description": "The current user is not allowed to delete the Creative Tonie, because the membership is limited."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Creative Tonie does not exist, or the current user is not allowed to access the Creative Tonie."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/discs/{disc_pk}/permissions/{id}": {"put": {"operationId": "households_discs_permissions_update", "description": "Change the permissions of a specific household member on this Tonieplay Disc.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"required": ["permission"], "type": "object", "properties": {"permission": {"title": "The desired permission: explicit=checked, none=unchecked", "type": "string", "enum": ["explicit", "none"]}}}}], "responses": {"200": {"description": "The new permission of the specified membership.", "schema": {"type": "object", "properties": {"membershipId": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address).", "type": "string", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "permission": {"title": "The permissions of the user on this Tonieplay Disc.\n\"implicit\": the user is a full user or owner and thus has unrestricted access (checkbox checked & readonly).\n \"explicit\": This user is limited and has been granted access to this Tonieplay Disc (checkbox checked).\n \"none\": The user is limited and can not access the Tonieplay Disc (checkbox clear).", "type": "string", "enum": ["implicit", "explicit", "none"]}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "The current user has only limited permissions and tried to view or change a Tonieplay Disc's permissions. Only full users and owners can do that."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Tonieplay Disc does not exist, or the current user is not allowed to access the Tonieplay Disc."}, "409": {"description": "Invalid update: The user whose permissions should be updated is a full user or owner. Downgrade the user to limited if you want to edit the permissions in detail."}}, "tags": ["households"]}, "patch": {"operationId": "households_discs_permissions_partial_update", "description": "Change the permissions of a specific household member on this Tonieplay Disc.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"permission": {"title": "The desired permission: explicit=checked, none=unchecked", "type": "string", "enum": ["explicit", "none"]}}}}], "responses": {"200": {"description": "The new permission of the specified membership.", "schema": {"type": "object", "properties": {"membershipId": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address).", "type": "string", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "permission": {"title": "The permissions of the user on this Tonieplay Disc.\n\"implicit\": the user is a full user or owner and thus has unrestricted access (checkbox checked & readonly).\n \"explicit\": This user is limited and has been granted access to this Tonieplay Disc (checkbox checked).\n \"none\": The user is limited and can not access the Tonieplay Disc (checkbox clear).", "type": "string", "enum": ["implicit", "explicit", "none"]}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "The current user has only limited permissions and tried to view or change a Tonieplay Disc's permissions. Only full users and owners can do that."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Tonieplay Disc does not exist, or the current user is not allowed to access the Tonieplay Disc."}, "409": {"description": "Invalid update: The user whose permissions should be updated is a full user or owner. Downgrade the user to limited if you want to edit the permissions in detail."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "disc_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/discs/{id}": {"patch": {"operationId": "households_discs_partial_update", "description": "Change properties of a Tonieplay disc.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"$ref": "#/definitions/DiscPatchRequest"}}], "responses": {"200": {"description": "Updated successfully. (returns a representation of this disc)"}, "204": {"description": "No changes were made."}}, "tags": ["households"]}, "delete": {"operationId": "households_discs_delete", "description": "Remove this Tonieplay Disc from the household.", "parameters": [], "responses": {"204": {"description": "The Tonieplay disc was removed from this household."}, "403": {"description": "The current user is not allowed to remove the Tonieplay disc from this household, because they are not a superuser in the household."}, "404": {"description": "The household does not exist, or the Tonieplay Disc with the specified ID does not exist or the Tonieplay Disc is not in this household"}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/eligible-owners": {"get": {"operationId": "households_eligible-owners_list", "description": "List household members who are eligible to receive a household, i.e.\nthe client can set mtype=owner via PUT on the membership.\nThe rules for eligibility are simple: Only users without a household are eligible.", "parameters": [], "responses": {"200": {"description": "All members which are eligible to receive a household transfer.", "schema": {"type": "array", "items": {"required": ["displayName", "mtype", "canEdit", "canDelete", "isSelf"], "type": "object", "properties": {"id": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address). In contrast to email, firstName, and lastName, this field is always present, no matter the current user's permissions.", "type": "string", "readOnly": true}, "firstName": {"title": "The user's given name", "type": "string", "readOnly": true}, "lastName": {"title": "The user's family name", "type": "string", "readOnly": true}, "email": {"title": "The user's email address", "type": "string", "format": "email", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "mtype": {"title": "The type of this membership", "type": "string", "enum": ["owner", "full", "limited"]}, "isSelf": {"title": "Is this a membership of the current user (the one sending the request)?", "type": "boolean", "readOnly": true}, "canEdit": {"title": "Can the current user edit the membership?", "type": "boolean", "readOnly": true}, "canDelete": {"title": "Can the current user delete the membership?", "type": "boolean", "readOnly": true}}}}}, "403": {"description": "Somebody but the owner sent this request. This route is for the household owner only."}, "404": {"description": "The specified household does not exist, or the current user is not a member in it."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/invitations": {"get": {"operationId": "households_invitations_list", "description": "List all invitations in a household", "parameters": [], "responses": {"200": {"description": "All pending invitations to this household.", "schema": {"type": "array", "items": {"$ref": "#/definitions/Invitation"}}}, "403": {"description": "Insufficient permissions to see invitations in this household. Only owners and full users can see invitations."}, "404": {"description": "The household can not be found, or the current user does not have any permission to see it."}}, "tags": ["households"]}, "post": {"operationId": "households_invitations_create", "description": "Invite somebody to a household, by email address.\nAny frontend that any user can use should include a checkbox for the user to confirm\nthat they are inviting somebody, i.e. not sending spam.\nThe invitee will get an email asking them to join the TonieCloud (if not already)\nand join the household by accepting the invitation.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"required": ["id", "email", "itype"], "type": "object", "properties": {"email": {"title": "The email address of the user to invite.", "type": "string", "format": "email", "maxLength": 254, "minLength": 1}, "itype": {"title": "The type of access rights the user will get after accepting this invitation", "type": "string", "enum": ["full", "limited"]}}}}], "responses": {"201": {"description": "Invitation created.", "schema": {"$ref": "#/definitions/Invitation"}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "Insufficient permissions to invite somebody in this household. Only owners and full users who are not education users can invitesomebody to a household, and education users can not be invited.", "schema": {"type": "object", "properties": {"reason": {"description": "The reason why the user cannot invite", "type": "string", "enum": ["limited", "isEduUser", "inviteeIsEduUser"]}}}}, "404": {"description": "The household does not exist"}, "409": {"description": "The user can not be invited to the household, either because they are already a member or an invitation is pending. In the case (alreadyAMember), send PUT/PATCH/DELETE requests to /v2/households/{householdId}/members/{membershipId} to reconfigure the membership. In the latter case, send PUT/PATCH/DELETE requests to /v2/households/{householdId}/invitations/{currentInvitationId} to update or delete it.", "schema": {"type": "object", "properties": {"conflictType": {"description": "The type of the conflict", "type": "string", "enum": ["member", "invitation"]}, "currentMembershipId": {"description": "(If conflictType is \"member\") The id of the existing membership", "type": "string", "format": "uuid"}}}}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/invitations/{id}": {"get": {"operationId": "households_invitations_read", "description": "Get information about an invitation", "parameters": [], "responses": {"200": {"description": "The invitation in this household", "schema": {"type": "array", "items": {"$ref": "#/definitions/Invitation"}}}, "403": {"description": "Insufficient permissions to see invitations in this household. Only owners and full users can see invitations."}, "404": {"description": "The household or invitation can not be found. Likely the invitation has been accepted already. Another reason could be that the user does not have access to the household at all."}}, "tags": ["households"]}, "put": {"operationId": "households_invitations_update", "description": "Change the type of an invitation.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"$ref": "#/definitions/InvitationUpdate"}}], "responses": {"200": {"description": "The invitation has been updated.", "schema": {"$ref": "#/definitions/Invitation"}}, "403": {"description": "Insufficient permissions to modify invitations in this household. Only owners and full users can modify invitations."}, "404": {"description": "The household or invitation can not be found. Likely the invitation has been accepted already. Another reason could be that the user does not have access to the household at all."}}, "tags": ["households"]}, "patch": {"operationId": "households_invitations_partial_update", "description": "Change the type of an invitation.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"$ref": "#/definitions/InvitationUpdate"}}], "responses": {"200": {"description": "The invitation has been updated.", "schema": {"$ref": "#/definitions/Invitation"}}, "403": {"description": "Insufficient permissions to modify invitations in this household. Only owners and full users can modify invitations."}, "404": {"description": "The household or invitation can not be found. Likely the invitation has been accepted already. Another reason could be that the user does not have access to the household at all."}}, "tags": ["households"]}, "delete": {"operationId": "households_invitations_delete", "description": "Revoke an invitation.", "parameters": [], "responses": {"204": {"description": "The invitation has been revoked, and can no longer be accepted."}, "403": {"description": "Insufficient permissions to delete invitations in this household. Only owners and full users can delete invitations."}, "404": {"description": "The household or invitation can not be found. Likely the invitation has been accepted already. Another reason could be that the user does not have access to the household at all."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/invitations/{id}/resend": {"post": {"operationId": "households_invitations_resend", "description": "Resend an invitation email.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"$ref": "#/definitions/Invitation"}}], "responses": {"200": {"description": "The invitation email has been sent again. The invitation is returned to the caller.", "schema": {"$ref": "#/definitions/Invitation"}}, "403": {"description": "Insufficient permissions to send invitations in this household. Only owners and full users can send invitations."}, "404": {"description": "The household or invitation can not be found. Likely the invitation has been accepted already. Another reason could be that the user does not have access to the household at all."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/memberships": {"get": {"operationId": "households_memberships_list", "description": "List all visible members in a household.", "parameters": [], "responses": {"200": {"description": "All visible members in this household.", "schema": {"type": "array", "items": {"required": ["displayName", "mtype", "canEdit", "canDelete", "isSelf"], "type": "object", "properties": {"id": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address). In contrast to email, firstName, and lastName, this field is always present, no matter the current user's permissions.", "type": "string", "readOnly": true}, "firstName": {"title": "The user's given name", "type": "string", "readOnly": true}, "lastName": {"title": "The user's family name", "type": "string", "readOnly": true}, "email": {"title": "The user's email address", "type": "string", "format": "email", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "mtype": {"title": "The type of this membership", "type": "string", "enum": ["owner", "full", "limited"]}, "isSelf": {"title": "Is this a membership of the current user (the one sending the request)?", "type": "boolean", "readOnly": true}, "canEdit": {"title": "Can the current user edit the membership?", "type": "boolean", "readOnly": true}, "canDelete": {"title": "Can the current user delete the membership?", "type": "boolean", "readOnly": true}}}}}, "404": {"description": "The specified household does not exist, or the current user is not a member in it."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/memberships/{id}": {"get": {"operationId": "households_memberships_read", "description": "Get information about a membership.", "parameters": [], "responses": {"200": {"description": "Information about this membership.", "schema": {"required": ["displayName", "mtype", "canEdit", "canDelete", "isSelf"], "type": "object", "properties": {"id": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address). In contrast to email, firstName, and lastName, this field is always present, no matter the current user's permissions.", "type": "string", "readOnly": true}, "firstName": {"title": "The user's given name", "type": "string", "readOnly": true}, "lastName": {"title": "The user's family name", "type": "string", "readOnly": true}, "email": {"title": "The user's email address", "type": "string", "format": "email", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "mtype": {"title": "The type of this membership", "type": "string", "enum": ["owner", "full", "limited"]}, "isSelf": {"title": "Is this a membership of the current user (the one sending the request)?", "type": "boolean", "readOnly": true}, "canEdit": {"title": "Can the current user edit the membership?", "type": "boolean", "readOnly": true}, "canDelete": {"title": "Can the current user delete the membership?", "type": "boolean", "readOnly": true}}}}, "404": {"description": "The specified household does not exist, or the current user is not a member in it, or the current user cannot access the membership, or the membership does not exist."}}, "tags": ["households"]}, "put": {"operationId": "households_memberships_update", "description": "Change the type of a membership.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"required": ["mtype"], "type": "object", "properties": {"mtype": {"title": "The new type of this membership (can be used to switch members between full and limited). Setting this to \"owner\" transfers the ownership to the specified user.", "type": "string", "enum": ["owner", "full", "limited"]}}}}], "responses": {"200": {"description": "The changed membership.", "schema": {"required": ["displayName", "mtype", "canEdit", "canDelete", "isSelf"], "type": "object", "properties": {"id": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address). In contrast to email, firstName, and lastName, this field is always present, no matter the current user's permissions.", "type": "string", "readOnly": true}, "firstName": {"title": "The user's given name", "type": "string", "readOnly": true}, "lastName": {"title": "The user's family name", "type": "string", "readOnly": true}, "email": {"title": "The user's email address", "type": "string", "format": "email", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "mtype": {"title": "The type of this membership", "type": "string", "enum": ["owner", "full", "limited"]}, "isSelf": {"title": "Is this a membership of the current user (the one sending the request)?", "type": "boolean", "readOnly": true}, "canEdit": {"title": "Can the current user edit the membership?", "type": "boolean", "readOnly": true}, "canDelete": {"title": "Can the current user delete the membership?", "type": "boolean", "readOnly": true}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "You are not allowed to change this membership."}, "404": {"description": "The specified household does not exist, or the current user is not a member in it,  or the current user cannot access the membership, or the membership does not exist."}, "409": {"description": "Cannot transfer ownership; the new owner already has a household."}}, "tags": ["households"]}, "patch": {"operationId": "households_memberships_partial_update", "description": "Change the type of a membership.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"mtype": {"title": "The new type of this membership (can be used to switch members between full and limited). Setting this to \"owner\" transfers the ownership to the specified user.", "type": "string", "enum": ["owner", "full", "limited"]}}}}], "responses": {"200": {"description": "The changed membership.", "schema": {"required": ["displayName", "mtype", "canEdit", "canDelete", "isSelf"], "type": "object", "properties": {"id": {"title": "Unique ID of the membership", "type": "string", "format": "uuid", "readOnly": true}, "displayName": {"title": "The user's name (first name or email address). In contrast to email, firstName, and lastName, this field is always present, no matter the current user's permissions.", "type": "string", "readOnly": true}, "firstName": {"title": "The user's given name", "type": "string", "readOnly": true}, "lastName": {"title": "The user's family name", "type": "string", "readOnly": true}, "email": {"title": "The user's email address", "type": "string", "format": "email", "readOnly": true}, "profileImage": {"title": "The user's profile image", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"], "readOnly": true}, "mtype": {"title": "The type of this membership", "type": "string", "enum": ["owner", "full", "limited"]}, "isSelf": {"title": "Is this a membership of the current user (the one sending the request)?", "type": "boolean", "readOnly": true}, "canEdit": {"title": "Can the current user edit the membership?", "type": "boolean", "readOnly": true}, "canDelete": {"title": "Can the current user delete the membership?", "type": "boolean", "readOnly": true}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "You are not allowed to change this membership."}, "404": {"description": "The specified household does not exist, or the current user is not a member in it,  or the current user cannot access the membership, or the membership does not exist."}, "409": {"description": "Cannot transfer ownership; the new owner already has a household."}}, "tags": ["households"]}, "delete": {"operationId": "households_memberships_delete", "description": "Remove a member from the household.\nThis also deletes all tunes on tonies in this household from the leaving member,\nit should require the user's confirmation!", "parameters": [], "responses": {"204": {"description": "The user has been removed from the household."}, "403": {"description": "You are not allowed to change this membership."}, "404": {"description": "The specified household does not exist, or the current user is not a member in it, or the current user cannot access the membership, or the membership does not exist."}, "409": {"description": "The owner tried to leave the household. The owner must either transfer the household to somebody else or delete it."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/memberships/{membership_pk}/permissions": {"get": {"operationId": "households_memberships_permissions_list", "description": "List the Creative Tonies one member can access.", "parameters": [], "responses": {"200": {"description": "All Creative Tonies in this household and whether the specified user can access them. Use /v2/households/{householdId}/creativetonies/{creativetonieId}/permissions/{membershipId} to change individual permissions", "schema": {"type": "array", "items": {"type": "object", "properties": {"creativetonie": {"type": "object", "properties": {"id": {"title": "The ID of the Creative Tonie. At the moment, this is the actual ID.", "type": "string", "example": "1234ABCDE00304E0", "readOnly": true}, "householdId": {"title": "The ID of the household this Creative Tonie is in", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "The human-readable name of the Creative Tonie.", "type": "string", "example": "John's favorite red Tonie", "maxLength": 100}, "live": {"title": "Whether live mode is active. When live mode is active, new content gets inserted at the beginning instead of the end.", "type": "boolean", "default": false}, "private": {"title": "Private mode.\nIf enabled, then only Tonieboxes registered in this household can play this Tonie. Tonieboxes without a household or in other households will get an error message.\nIf private=false, then every Toniebox can play this Tonie.", "type": "boolean", "default": false}, "imageUrl": {"title": "The URL to the image to represent this Creative Tonie (e.g. https://cdn.tonies.de/thumbnails/98-0412.png ).", "type": "string", "format": "url", "readOnly": true}, "transcodingErrors": {"title": "A list of transcoding errors that happened since the last transcoding (i.e. a PUT or PATCH with different chapters).", "type": "array", "items": {"type": "object", "properties": {"reason": {"title": "Error type of why the transcoding failed. \"wrongFormat\" if a file was in an unsupported format, \"tooLong\" if all files exceeded 90 minutes in total, \"unknownError\" for internal errors.", "type": "string", "enum": ["wrongFormat", "tooLong", "unknownError"]}, "deletedChapters": {"title": "The chapters that were removed because of the error, if any.", "type": "array", "items": {"type": "object", "properties": {"title": {"title": "Human-readable name for this chapter", "type": "string", "example": "My recording on 2018-08-16", "maxLength": 128}, "seconds": {"title": "Length of this chapter in seconds. Available only if reason is \"tooLong\".", "type": "number"}}}}}}}}}, "permission": {"title": "The permissions of the user on this Creative Tonie.\n\"implicit\": the user is a full user or owner and thus has unrestricted access (checkbox checked & readonly).\n \"explicit\": This user is limited and has been granted access to this Creative Tonie (checkbox checked).\n \"none\": The user is limited and can not access the Creative Tonie (checkbox clear).", "type": "string", "enum": ["implicit", "explicit", "none"]}}}}}, "403": {"description": "The current user has only limited permissions and tried to access the permissions page. Only full users and owners can do that."}, "404": {"description": "The household does not exist, or the membership does not exist."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "membership_pk", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/tonie/{id}/tune": {"delete": {"operationId": "households_tonie_tune", "description": "Remove a assigned Tune from a Tonie.", "parameters": [], "responses": {"200": {"description": "Tune was successfully removed from Tonie."}, "404": {"description": "Tonie does not exist or Household membership does not fit or the Tune belongs to someone else or a Tune is not assigned to this Tonie."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/tonie/{tonie_pk}/tune/{id}": {"put": {"operationId": "households_tonie_tune_update", "description": "Assign a bought Tune to a Tonie.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {}}}], "responses": {"200": {"description": "Tune was successfully assigned onto the Tonie.\nIt will be removed automatically from other Tonie(s) if the assign limit has been reached."}, "400": {"description": "This Tune can not be assigned to this Tonie for licensing reasons.", "schema": {"type": "object", "properties": {"reason": {"title": "There exists the following reasons:\n\"notAllowed\" if tonie is not allowed for this tune.", "type": "string", "enum": ["notAllowed"]}}}}, "404": {"description": "Tonie or Tune does not exists or Household membership does not fit or the Tune belongs to someone else."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "tonie_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/tonieboxes": {"get": {"operationId": "households_tonieboxes_list", "description": "List all Tonieboxes in this household", "parameters": [], "responses": {"200": {"description": "All Tonieboxes in this household.", "schema": {"type": "array", "items": {"$ref": "#/definitions/Toniebox"}}}, "403": {"description": "The current user is only a limited user, and thus not allowed to see the Tonieboxes in this household (limited users can only edit [some] Tonies)."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Toniebox does not exist."}}, "tags": ["households"]}, "post": {"operationId": "households_tonieboxes_create", "description": "Add a Toniebox which has been connected to the Internet previously to a household.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"id": {"title": "Toniebox ID. May include dashes.", "type": "string", "minLength": 8}, "name": {"title": "Optional name for this new Toniebox (mandatory if this is a registration)", "type": "string", "maxLength": 50, "minLength": 1}}}}], "responses": {"200": {"description": "The Toniebox has been added to the household. Its data (including its ID) is returned"}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `requiresSetup` - The Toniebox cannot be added and needs to be set up instead.\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["requiresSetup", "required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "The current user is a limited user in this household. Only owners and full users can add Tonieboxes."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Toniebox does not exist."}, "409": {"description": "This Toniebox is in another household. Remove it from that household before adding it to this one."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}]}, "/households/{household_pk}/tonieboxes/{id}": {"get": {"operationId": "households_tonieboxes_read", "description": "Get information about a specific Toniebox (in a household).", "parameters": [], "responses": {"200": {"description": "The requested Toniebox.", "schema": {"$ref": "#/definitions/Toniebox"}}, "403": {"description": "The current user is only a limited user, and thus not allowed to see the Tonieboxes in this household (limited users can only edit [some] Tonies)."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Toniebox does not exist."}}, "tags": ["households"]}, "put": {"operationId": "households_tonieboxes_update", "description": "Change properties of a Toniebox.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"name": {"title": "The human-readable name of the Toniebox.", "type": "string", "example": "Alice's red Toniebox", "maxLength": 50, "minLength": 1}, "ageMode": {"title": "Configuration of the Toniebox determining for which age it is suitable.\nOnly meaningful if the Toniebox has the feature \"ageMode\".\n\"1+\": Suitable for children 12 months or older.\n\"3+\": Suitable for children 3 years or older.\nWill not be present on Tonieboxes which do not have this feature.", "type": "string"}, "lightringBrightness": {"title": "Normal brightness of the lightring, between 0 (off) and 100(full)", "type": "integer", "maxValue": 100, "minValue": 0}, "bedtimeLightringBrightness": {"title": "Brightness of the lightring when a bedtime mode is active. Between 0 (off) and 100(full)", "type": "integer", "maxValue": 100, "minValue": 0}, "bedtimeLightringColor": {"title": "Color of the lightring when a bedtime mode is active. Lower-case RGB, like #ab5f12", "type": "string"}, "bedtimeMaxVolume": {"title": "Maximum volume of the Toniebox speakers when a bedtime mode is active. Between 1 (very quiet) and 100(loudest)", "type": "integer", "maxValue": 100, "minValue": 1}, "bedtimeMaxHeadphoneVolume": {"title": "Maximum headphone volume when a bedtime mode is active. Between 1 (very quiet) and 100(loudest)", "type": "integer", "maxValue": 100, "minValue": 1}, "skippingEnabled": {"title": "Whether the child can tap the Toniebox to jump to the next or previous chapter.\nSet to null to restore default.\nEnabled by default.\n", "type": "boolean"}, "skippingDirection": {"title": "\"right\" (default): Tap right to skip to next track. Tap left to skip to previous track.\n\"left\": Tap left to skip to next track. Tap right to skip to previous track.\nSet to null to restore default.\nNote that this is the opposite default of the similar tapDirection setting for Tonieboxes without the \"tngSettings\" feature.", "type": "string"}, "scrubbingEnabled": {"title": "Whether the child can tilt the Toniebox to fast-forward and rewind.\n Set to null to restore default.\n Off by default for ageMode \"1+\", otherwise on; but parents can override it either way.", "type": "boolean"}, "language": {"title": "The Toniebox language. Will only be available&changeable if the feature \"language\" is set on the Toniebox.\nTonieboxes without this feature still have a language, but it is set directly with a request to the Toniebox in LAN rather than via the Toniecloud.\nnull if no language is set.\nAvailable languages:\n- null: unspecified\n- \"de\": Deutsch\n- \"en\": English\n- \"en-us\": English (US)\n- \"fr\": Français", "type": "string"}, "accelerometerEnabled": {"title": "Tilting & Tapping enabled (older Tonieboxes without the \"tngSettings\" feature only)", "type": "boolean"}, "tapDirection": {"title": "(older Tonieboxes without the \"tngSettings\" feature only)\nWhat happens when the Toniebox is hit: \"left\" = hitting from the left goes to the next chapter, hitting from the right goes to previous chapter. \"right\" = hitting from the left goes to the previous chapter, hitting from the right goes to next chapter.", "type": "string", "enum": ["left", "right"]}, "maxVolume": {"title": "Maximum sound volume that the Toniebox uses with speakers, in percent", "type": "integer", "enum": [100, 75, 50, 25]}, "maxHeadphoneVolume": {"title": "Maximum sound volume that the Toniebox uses with headphones, in percent", "type": "integer", "enum": [100, 75, 50, 25]}, "ledLevel": {"description": "(older Tonieboxes without the \"tngSettings\" feature only)\nThe intensity of the Toniebox LED (the square around the Tonie). One of \"on\" (default), \"off\" (LED disabled) and \"dimmed\" (reduced brightness).", "type": "string", "enum": ["on", "off", "dimmed"]}, "timezone": {"description": "The tzdata timezone the Toniebox is using. See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for possible values.", "type": "string", "example": "Europe/Berlin"}, "reset": {"description": "Set to true to reset all Toniebox settings (except name & language) to factory defaults, but keep the Toniebox in this household. (Use DELETE /v2/households/{householdId}/tonieboxes/{tonieboxId} to reset and remove from the household.)", "type": "boolean", "writeOnly": true}}}}], "responses": {"200": {"description": "The changed Toniebox.", "schema": {"$ref": "#/definitions/Toniebox"}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "The current user is only a limited user, and thus not allowed to see the Tonieboxes in this household (limited users can only edit [some] Tonies)."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Toniebox does not exist."}}, "tags": ["households"]}, "patch": {"operationId": "households_tonieboxes_partial_update", "description": "Change some properties of a Toniebox.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"name": {"title": "The human-readable name of the Toniebox.", "type": "string", "example": "Alice's red Toniebox", "maxLength": 50, "minLength": 1}, "ageMode": {"title": "Configuration of the Toniebox determining for which age it is suitable.\nOnly meaningful if the Toniebox has the feature \"ageMode\".\n\"1+\": Suitable for children 12 months or older.\n\"3+\": Suitable for children 3 years or older.\nWill not be present on Tonieboxes which do not have this feature.", "type": "string"}, "lightringBrightness": {"title": "Normal brightness of the lightring, between 0 (off) and 100(full)", "type": "integer", "maxValue": 100, "minValue": 0}, "bedtimeLightringBrightness": {"title": "Brightness of the lightring when a bedtime mode is active. Between 0 (off) and 100(full)", "type": "integer", "maxValue": 100, "minValue": 0}, "bedtimeLightringColor": {"title": "Color of the lightring when a bedtime mode is active. Lower-case RGB, like #ab5f12", "type": "string"}, "bedtimeMaxVolume": {"title": "Maximum volume of the Toniebox speakers when a bedtime mode is active. Between 1 (very quiet) and 100(loudest)", "type": "integer", "maxValue": 100, "minValue": 1}, "bedtimeMaxHeadphoneVolume": {"title": "Maximum headphone volume when a bedtime mode is active. Between 1 (very quiet) and 100(loudest)", "type": "integer", "maxValue": 100, "minValue": 1}, "skippingEnabled": {"title": "Whether the child can tap the Toniebox to jump to the next or previous chapter.\nSet to null to restore default.\nEnabled by default.\n", "type": "boolean"}, "skippingDirection": {"title": "\"right\" (default): Tap right to skip to next track. Tap left to skip to previous track.\n\"left\": Tap left to skip to next track. Tap right to skip to previous track.\nSet to null to restore default.\nNote that this is the opposite default of the similar tapDirection setting for Tonieboxes without the \"tngSettings\" feature.", "type": "string"}, "scrubbingEnabled": {"title": "Whether the child can tilt the Toniebox to fast-forward and rewind.\n Set to null to restore default.\n Off by default for ageMode \"1+\", otherwise on; but parents can override it either way.", "type": "boolean"}, "language": {"title": "The Toniebox language. Will only be available&changeable if the feature \"language\" is set on the Toniebox.\nTonieboxes without this feature still have a language, but it is set directly with a request to the Toniebox in LAN rather than via the Toniecloud.\nnull if no language is set.\nAvailable languages:\n- null: unspecified\n- \"de\": Deutsch\n- \"en\": English\n- \"en-us\": English (US)\n- \"fr\": Français", "type": "string"}, "accelerometerEnabled": {"title": "Tilting & Tapping enabled (older Tonieboxes without the \"tngSettings\" feature only)", "type": "boolean"}, "tapDirection": {"title": "(older Tonieboxes without the \"tngSettings\" feature only)\nWhat happens when the Toniebox is hit: \"left\" = hitting from the left goes to the next chapter, hitting from the right goes to previous chapter. \"right\" = hitting from the left goes to the previous chapter, hitting from the right goes to next chapter.", "type": "string", "enum": ["left", "right"]}, "maxVolume": {"title": "Maximum sound volume that the Toniebox uses with speakers, in percent", "type": "integer", "enum": [100, 75, 50, 25]}, "maxHeadphoneVolume": {"title": "Maximum sound volume that the Toniebox uses with headphones, in percent", "type": "integer", "enum": [100, 75, 50, 25]}, "ledLevel": {"description": "(older Tonieboxes without the \"tngSettings\" feature only)\nThe intensity of the Toniebox LED (the square around the Tonie). One of \"on\" (default), \"off\" (LED disabled) and \"dimmed\" (reduced brightness).", "type": "string", "enum": ["on", "off", "dimmed"]}, "timezone": {"description": "The tzdata timezone the Toniebox is using. See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for possible values.", "type": "string", "example": "Europe/Berlin"}, "reset": {"description": "Set to true to reset all Toniebox settings (except name & language) to factory defaults, but keep the Toniebox in this household. (Use DELETE /v2/households/{householdId}/tonieboxes/{tonieboxId} to reset and remove from the household.)", "type": "boolean", "writeOnly": true}}}}], "responses": {"200": {"description": "The changed Toniebox.", "schema": {"$ref": "#/definitions/Toniebox"}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "403": {"description": "The current user is only a limited user, and thus not allowed to see the Tonieboxes in this household (limited users can only edit [some] Tonies)."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Toniebox does not exist."}}, "tags": ["households"]}, "delete": {"operationId": "households_tonieboxes_delete", "description": "Remove this Toniebox from a household.\nTo effectively function, it needs be added to this or another household afterwards.", "parameters": [], "responses": {"204": {"description": "The Toniebox has been removed from this household."}, "403": {"description": "The current user is only a limited user, and thus not allowed to see the Tonieboxes in this household (limited users can only edit [some] Tonies)."}, "404": {"description": "The household does not exist, or the current user is not allowed to access the household, or the Toniebox does not exist."}}, "tags": ["households"]}, "parameters": [{"name": "household_pk", "in": "path", "required": true, "type": "string"}, {"name": "id", "in": "path", "required": true, "type": "string"}]}, "/households/{id}": {"get": {"operationId": "households_read", "description": "Get information about a household", "parameters": [], "responses": {"200": {"description": "The household data", "schema": {"type": "object", "properties": {"id": {"title": "The ID of the household", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "The human-readable name of the household", "type": "string", "maxLength": 30, "minLength": 1}, "ownerName": {"title": "First name of the owner, if available", "type": "string", "readOnly": true}, "image": {"title": "name of the household's image", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}, "foreignCreativeTonieContent": {"title": "Can Creative Tonies from other households be played on Tonieboxes in this one?", "type": "boolean", "default": true}, "access": {"title": "The type of access rights the current user has", "type": "string", "enum": ["owner", "full", "limited"], "readOnly": true}, "canLeave": {"title": "Whether the current user can leave the household. Limited and full users can always leave. Owners can only leave if there is somebody they can transfer the household to.", "type": "boolean", "readOnly": true}}}}, "404": {"description": "Household not found, either because there is not household with the ID (or it has been deleted), or the current user has no right to access the household."}}, "tags": ["households"]}, "put": {"operationId": "households_update", "description": "Update household name and settings (name required)", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"name": {"title": "The human-readable name of the household", "type": "string", "maxLength": 30, "minLength": 1}, "image": {"title": "name of the household's image", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}, "foreignCreativeTonieContent": {"title": "Can Creative Tonies from other households be played on Tonieboxes in this one?", "type": "boolean", "default": true}}}}], "responses": {"200": {"description": "Update successful. The new household data is returned.", "schema": {"type": "object", "properties": {"id": {"title": "The ID of the household", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "The human-readable name of the household", "type": "string", "maxLength": 30, "minLength": 1}, "ownerName": {"title": "First name of the owner, if available", "type": "string", "readOnly": true}, "image": {"title": "name of the household's image", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}, "foreignCreativeTonieContent": {"title": "Can Creative Tonies from other households be played on Tonieboxes in this one?", "type": "boolean", "default": true}, "access": {"title": "The type of access rights the current user has", "type": "string", "enum": ["owner", "full", "limited"], "readOnly": true}, "canLeave": {"title": "Whether the current user can leave the household. Limited and full users can always leave. Owners can only leave if there is somebody they can transfer the household to.", "type": "boolean", "readOnly": true}}}}, "403": {"description": "Insufficient permissions to update this household. Only household superusers and owners can update a household."}, "404": {"description": "Household not found. Maybe it has been deleted, or the current user does not have access to it anymore."}}, "tags": ["households"]}, "patch": {"operationId": "households_partial_update", "description": "Update household name and settings", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"name": {"title": "The human-readable name of the household", "type": "string", "maxLength": 30, "minLength": 1}, "image": {"title": "name of the household's image", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}, "foreignCreativeTonieContent": {"title": "Can Creative Tonies from other households be played on Tonieboxes in this one?", "type": "boolean", "default": true}}}}], "responses": {"200": {"description": "Update successful. The new household data is returned.", "schema": {"type": "object", "properties": {"id": {"title": "The ID of the household", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "The human-readable name of the household", "type": "string", "maxLength": 30, "minLength": 1}, "ownerName": {"title": "First name of the owner, if available", "type": "string", "readOnly": true}, "image": {"title": "name of the household's image", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}, "foreignCreativeTonieContent": {"title": "Can Creative Tonies from other households be played on Tonieboxes in this one?", "type": "boolean", "default": true}, "access": {"title": "The type of access rights the current user has", "type": "string", "enum": ["owner", "full", "limited"], "readOnly": true}, "canLeave": {"title": "Whether the current user can leave the household. Limited and full users can always leave. Owners can only leave if there is somebody they can transfer the household to.", "type": "boolean", "readOnly": true}}}}, "403": {"description": "Insufficient permissions to update this household. Only household superusers and owners can update a household."}, "404": {"description": "Household not found. Maybe it has been deleted, or the current user does not have access to it anymore."}}, "tags": ["households"]}, "delete": {"operationId": "households_delete", "description": "Delete the household and all its associated content.\nThis includes Creative Tonies and Tonieboxes!", "parameters": [], "responses": {"204": {"description": "The household and all its associated content has been deleted."}, "403": {"description": "Insufficient permissions to delete this household. Only the household owner can delete a household."}, "404": {"description": "Household not found. Maybe it has been deleted already, or the current user does not have access to it anymore."}}, "tags": ["households"]}, "parameters": [{"name": "id", "in": "path", "required": true, "type": "string"}]}, "/invitations": {"get": {"operationId": "invitations_list", "description": "List all invitations to the current user", "parameters": [], "responses": {"200": {"description": "All pending invitations to this user.", "schema": {"type": "array", "items": {"type": "object", "properties": {"token": {"title": "The invitation token, used to identify the invitation from the perspective of the invited user.", "type": "string", "format": "uuid", "readOnly": true}, "itype": {"title": "The type of access rights the user will get after accepting this invitation", "type": "string", "enum": ["full", "limited"]}, "householdName": {"title": "The human-readable name of the household associated with this invitation", "type": "string", "maxLength": 30, "minLength": 1}, "householdImage": {"title": "name of the household associated with this invitation", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}}}}}}, "tags": ["invitations"]}, "parameters": []}, "/invitations/{id}": {"get": {"operationId": "invitations_read", "description": "Get information about a specific invitation to the current user", "parameters": [], "responses": {"200": {"description": "The specific invitations to this user.", "schema": {"type": "object", "properties": {"token": {"title": "The invitation token, used to identify the invitation from the perspective of the invited user.", "type": "string", "format": "uuid", "readOnly": true}, "itype": {"title": "The type of access rights the user will get after accepting this invitation", "type": "string", "enum": ["full", "limited"]}, "householdName": {"title": "The human-readable name of the household associated with this invitation", "type": "string", "maxLength": 30, "minLength": 1}, "householdImage": {"title": "name of the household associated with this invitation", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}}}}, "404": {"description": "The invitation could not be found. Maybe it has been accepted already?"}}, "tags": ["invitations"]}, "delete": {"operationId": "invitations_delete", "description": "Decline an invitation by token ID", "parameters": [], "responses": {"204": {"description": "The invitation has been declined."}, "404": {"description": "The invitation could not be found. Maybe it has been accepted already?"}}, "tags": ["invitations"]}, "parameters": [{"name": "id", "in": "path", "required": true, "type": "string"}]}, "/invitations/{invitation_pk}/accept": {"post": {"operationId": "invitations_accept_create", "description": "Accept an invitation", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "parameters": {}}}], "responses": {"200": {"description": "The invitation has been accepted. The household information is returned.", "schema": {"type": "object", "properties": {"id": {"title": "The ID of the household", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "The human-readable name of the household", "type": "string", "maxLength": 30, "minLength": 1}, "ownerName": {"title": "First name of the owner, if available", "type": "string", "readOnly": true}, "image": {"title": "name of the household's image", "type": "string", "enum": ["baum.svg", "boot.svg", "haus.svg", "iglo.svg", "wigwam.svg", "wohnwagen.svg", "zelt.svg"], "default": "haus.svg"}, "foreignCreativeTonieContent": {"title": "Can Creative Tonies from other households be played on Tonieboxes in this one?", "type": "boolean", "default": true}, "access": {"title": "The type of access rights the current user has", "type": "string", "enum": ["owner", "full", "limited"], "readOnly": true}, "canLeave": {"title": "Whether the current user can leave the household. Limited and full users can always leave. Owners can only leave if there is somebody they can transfer the household to.", "type": "boolean", "readOnly": true}}}}, "401": {"description": "The authentication token was missing, expired, or invalid", "schema": {"type": "object", "properties": {"reason": {"description": "Reason why the invitation could not be accepted. needLogin means that the invitee already has an account and just has to log in. needRegistration means that the invitee email is not yet connected to an account; the invitee has to create one.", "type": "string", "enum": ["needRegistration", "needLogin"]}}}}, "403": {"description": "The invitation belongs to a different user", "schema": {"type": "object", "properties": {"reason": {"description": "Reason why the invitation could not be accepted. needLogin means that the invitee already has an account and just has to log in. needRegistration means that the invitee email is not yet connected to an account; the invitee has to create one.", "type": "string", "enum": ["needRegistration", "needLogin"]}}}}, "404": {"description": "The invitation could not be found. Maybe it has been accepted already?"}}, "tags": ["invitations"]}, "parameters": [{"name": "invitation_pk", "in": "path", "required": true, "type": "string"}]}, "/me": {"get": {"operationId": "me_read", "description": "Get the profile data of the currently logged-in user", "parameters": [], "responses": {"200": {"description": "The user is logged in; this is their profile data.", "schema": {"$ref": "#/definitions/User"}}, "401": {"description": "The user is not logged in (or there is a problem with the authentication). Log in to see the user's profile."}}, "tags": ["me"]}, "patch": {"operationId": "me_partial_update", "description": "Change some properties of the user's profile.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"locale": {"title": "Language of the user in POSIX format, either in the form xx or xx_YY.", "type": "string", "enum": ["de", "en", "en_US", "fr"], "maxLength": 5, "minLength": 2}, "unicodeLocale": {"title": "Language of the user in Unicode format, either in the form xx or xx-YY.", "type": "string", "enum": ["de", "en", "en-US", "fr"], "maxLength": 5, "minLength": 2}, "country": {"title": "Home country of the user as ISO 3166 alpha 2. If the user is travelling/vacationing etc., this will be different than the GeoIP-determined country. Changed in SSO, will be synchronized automatically.", "type": "string", "maxLength": 2, "minLength": 2}, "firstName": {"title": "The user's first name (used when addressing the user)", "type": "string", "maxLength": 255}, "lastName": {"title": "Last name (used when interacting with other users via a household)", "type": "string", "maxLength": 255}, "sex": {"title": "Deprecated. Do not use.", "type": "string", "enum": ["m", "f"]}, "acceptedTermsOfUse": {"title": "Deprecated: This always returns True.", "type": "boolean"}, "tracking": {"title": "Whether the user has opted out or not of tracking. We don't use this field, but maybe marketing does.", "type": "boolean", "default": true}, "authCode": {"title": "4 or 5 character authentication code, used by our support to identify and authenticate users", "type": "string", "maxLength": 5, "minLength": 4, "readonly": true}, "profileImage": {"title": "Profile image file name", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"]}, "notificationPreferences": {"title": "Which mobile notifications the user opted in to.", "type": "object", "properties": {"household": {"description": "Toniecloud notifications like \"Creative Tonie too long\" or \"Toniebox battery running low\".", "type": "boolean"}, "offerSales": {"description": "Advertisements, like \"Get 10% off if you buy within the next 24 hours\".", "type": "boolean"}, "appUpdates": {"description": "Information about new app features.", "type": "boolean"}, "yourOrders": {"description": "Your orders in the Tonie shop, like \"Your order has been shipped.", "type": "boolean"}, "isDefault": {"description": "Whether the current setting is the default, i.e. the user did not make a choice yet", "type": "boolean"}}}, "personalization": {"title": "Whether the user has finished the personalization process (e.g. setting up children etc.).\n \"unseen\": The user has never seen the process (default).\n \"done\": The user has completed the process.\n \"ignored\": The user has left the process.", "type": "string", "choices": ["unseen", "done", "ignored"]}}}}], "responses": {"200": {"description": "The new profile data of the user.", "schema": {"$ref": "#/definitions/User"}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `use-sso-instead` - Tried to change email address. Use SSO for that\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["use-sso-instead", "required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}}, "tags": ["me"]}, "parameters": []}, "/notifications": {"get": {"operationId": "notifications_list", "description": "Get all notifications", "parameters": [], "responses": {"200": {"description": "All notifications that the current user got.", "schema": {"type": "array", "items": {"$ref": "#/definitions/Notification"}}}}, "tags": ["notifications"]}, "delete": {"operationId": "notifications_delete", "description": "Delete multiple notifications at once.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"title": "List of notifications IDs to delete", "type": "array", "items": {"type": "string", "format": "uuid"}}}], "responses": {"204": {"description": "All specified notifications have been deleted. If a notification was not found  (i.e. presumably has been deleted in the meantime), it still counts as deleted. The same is true for notifications sent to other users (the current user should not be able to obtain these IDs anyways)."}, "400": {"description": "Incorrectly formatted input", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"type": "object", "properties": {"code": {"title": "Machine-readable code for the reason of the error", "type": "string", "enum": ["notArray", "invalidId"]}}}}}}}}, "tags": ["notifications"]}, "parameters": []}, "/notifications/{id}": {"get": {"operationId": "notifications_read", "description": "Get information about a specific notification.", "parameters": [], "responses": {"200": {"description": "The requested notification.", "schema": {"$ref": "#/definitions/Notification"}}, "404": {"description": "The notification could not be found. Maybe it has been deleted already?"}}, "tags": ["notifications"]}, "put": {"operationId": "notifications_update", "description": "Mark a notification as read or unread.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"read": {"title": "Whether this notification has been read (true=read false=unread).", "type": "boolean"}, "tonieId": {"title": "(Only if ntype is \"tonieError\"): Id of the Creative Tonie that failed to transcode", "type": "string", "format": "uuid"}, "tonieReason": {"title": "(Only if ntype is \"tonieError\"): Reason why the transcoding failed", "type": "string", "enum": ["wrongFormat", "tooLong", "unknownError"]}}}}], "responses": {"200": {"description": "The changed notification.", "schema": {"$ref": "#/definitions/Notification"}}, "404": {"description": "The notification could not be found. Maybe it has been deleted already?"}}, "tags": ["notifications"]}, "patch": {"operationId": "notifications_partial_update", "description": "Mark a notification as read or unread.", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"read": {"title": "Whether this notification has been read (true=read false=unread).", "type": "boolean"}, "tonieId": {"title": "(Only if ntype is \"tonieError\"): Id of the Creative Tonie that failed to transcode", "type": "string", "format": "uuid"}, "tonieReason": {"title": "(Only if ntype is \"tonieError\"): Reason why the transcoding failed", "type": "string", "enum": ["wrongFormat", "tooLong", "unknownError"]}}}}], "responses": {"200": {"description": "The changed notification.", "schema": {"$ref": "#/definitions/Notification"}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "404": {"description": "The notification could not be found. Maybe it has been deleted already?"}}, "tags": ["notifications"]}, "delete": {"operationId": "notifications_delete", "description": "Remove this notification.", "parameters": [], "responses": {"204": {"description": "The notification has been deleted."}, "404": {"description": "The notification could not be found. Maybe it has been deleted already?"}}, "tags": ["notifications"]}, "parameters": [{"name": "id", "in": "path", "required": true, "type": "string"}]}, "/playback-info/{toniebox_id}/{tonie_id}": {"get": {"operationId": "playback-info_read", "description": "", "parameters": [], "responses": {"200": {"description": "Get information about a currently playing Tonie", "schema": {"type": "object", "properties": {"status": {"description": "If \"outdated\", then the contentVersion is not up-to-date, and chapters will be missing.If \"unavailable\", then no chapter information is available for this Tonie.", "type": "string", "enum": ["available", "outdated", "unavailable"]}, "tonieType": {"description": "What kind of Tonie this is", "type": "string", "enum": ["content", "creative", "disc"]}, "tonieHouseholdId": {"description": "The UUID of the Tonie's household, if the current user has access to the Tonie.", "type": "string", "format": "uuid", "nullable": true}, "tonieImageUrl": {"description": "Thumbnail URL for this Tonie. Displays just the Tonie.", "type": "string", "format": "url"}, "coverUrl": {"description": "Cover image for the current content on the Tonie.", "type": "string", "format": "url", "nullable": true}, "title": {"description": "Title of the content on this Tonie, e.g. \"Der Löwe, der nicht schreiben konnte\"", "type": "string"}, "series": {"title": "Public name of this Tonie (e.g.: \"Conni\", \"Bibi Blocksberg\")", "type": "string", "nullable": true}, "chapters": {"description": "The chapters / songs that are currently on this Tonie, if any", "type": "array", "items": {"type": "object", "properties": {"coverUrl": {"description": "Cover image for the content (Tune / Content Token) that this chapter belongs to.", "type": "string", "format": "url", "nullable": true}, "seconds": {"description": "Length of this chapter, in seconds", "type": "number"}, "title": {"description": "Name of this chapter", "type": "string"}, "tuneTitle": {"description": "Name of the Tune (paid content) of this chapter, if any", "type": "string", "nullable": true}}}}}}}}, "tags": ["playback-info"]}, "parameters": [{"name": "toniebox_id", "in": "path", "required": true, "type": "string"}, {"name": "tonie_id", "in": "path", "required": true, "type": "string"}]}, "/system-notifications": {"get": {"operationId": "system-notifications_list", "description": "Get all system notifications, not to be confused with per-user notifications.\nSystem notifications are temporary broadcasts to all users.", "parameters": [], "responses": {"200": {"description": "All notifications.", "schema": {"type": "array", "items": {"$ref": "#/definitions/SystemNotification"}}}}, "tags": ["system-notifications"]}, "parameters": []}, "/system-notifications/{id}": {"get": {"operationId": "system-notifications_read", "description": "Get information about a specific system notification.", "parameters": [], "responses": {"200": {"description": "The requested system notification.", "schema": {"$ref": "#/definitions/SystemNotification"}}, "404": {"description": "The system notification could not be found. Maybe it has been dismissed already?"}}, "tags": ["system-notifications"]}, "delete": {"operationId": "system-notifications_delete", "description": "Dismiss this notification.", "parameters": [], "responses": {"204": {"description": "The system notification has been dismissed and will not be shown to the current user again."}, "404": {"description": "The system notification could not be found. Maybe it has been dismissed already?"}}, "tags": ["system-notifications"]}, "parameters": [{"name": "id", "in": "path", "required": true, "type": "string"}]}, "/timezones": {"get": {"operationId": "timezones_list", "description": "Get information about the backend configuration.\nDoes not require authentication.", "parameters": [], "responses": {"200": {"description": "A list of all all timezones.", "schema": {"type": "object", "properties": {"code": {"description": "The timezone code, for example \"America/Los_Angeles\" or \"Europe/Berlin\"", "type": "string", "example": "US/Hawaii"}, "name": {"description": "The timezone name in the user's language, e.g. \"Mountain Time\" or \"Mitteleuropäische Zeit\"", "type": "string", "example": "Mitteleuropäische Zeit"}, "city": {"description": "An example city representing the timezone, in the user's language, like \"Chicago\"", "type": "string", "example": "New York"}, "countryCode": {"description": "The country of the timezone.\nISO 3166 Alpha 2 country code, lower-case, e.g. \"de\" for Germany.\nnull if the timezone is not associated with a specific country.", "type": "string", "example": "de"}, "countryName": {"description": "The name of the country in the user's locale, e.g. \"Frankreich\" for a German user and a French timezone.\nnull if the timezone is not associated with a specific country.", "type": "string", "example": "Frankreich"}, "offset": {"description": "Description of the current time offset, e.g. \"GMT+02:00\"", "type": "string", "example": "GMT+02:00"}, "offsetSeconds": {"description": "Offset in seconds, e.g. 3600", "type": "integer", "example": 3600}}}}}, "tags": ["timezones"]}, "parameters": []}, "/toniebox-languages": {"get": {"operationId": "toniebox-languages_list", "description": "A list of all languages that can be set for a Toniebox", "parameters": [], "responses": {"200": {"description": "A list of all all available Toniebox languages.", "schema": {"type": "object", "properties": {"code": {"description": "The language code (2 or 5 characters)", "type": "string", "example": "en-us"}, "name": {"description": "The name of the language, in the language itself", "type": "string", "example": "Français"}}}}}, "tags": ["toniebox-languages"]}, "parameters": []}, "/toniebox-setup/{id}": {"get": {"operationId": "toniebox-setup_read", "description": "Get information about the current state of an automatic Toniebox setup.", "parameters": [], "responses": {"200": {"description": "The current setup status", "schema": {"type": "object", "properties": {"tonieboxId": {"title": "Cleaned ID of the Toniebox, all uppercase", "type": "string", "example": "EXAMPLE4"}, "householdSpec": {"title": "Either the UUID of a household the current user has full or owner access to, or the string \"create\" (use the current user's household, and  create a household if it does not exists already)", "type": "string", "example": "create"}, "name": {"title": "Name to assign to the Toniebox", "type": "string", "example": "Ben's Favorite Box", "maxLength": 50, "minLength": 1}, "ageMode": {"title": "Configuration of the Toniebox determining for which age it is suitable.\nOnly meaningful if the Toniebox has the feature \"ageMode\".\n\"1+\": Suitable for children 12 months or older.\n\"3+\": Suitable for children 3 years or older.\n\"default\" (if nothing else specified): Depends on the packaging of the Toniebox.\n", "type": "string", "enum": ["default", "1+", "3+"]}, "language": {"title": "Language of the Toniebox.\nOnly meaningful if the Toniebox has the feature \"language\".\n- null: unspecified\n- \"de\": Deutsch\n- \"en\": English\n- \"en-us\": English (US)\n- \"fr\": Français", "type": "string", "enum": [null, "de", "en", "en-us", "fr"]}, "timezone": {"title": "The timezone to set for the Toniebox", "type": "string"}, "status": {"title": "Current state of the setup.\n\"started\" when the setup has just been posted and we haven't seen any requests from the Toniebox.\n\"connected\" when the Toniebox reports connection to the Toniecloud (via MQTT).\n\"time\" [only for generation classic] when the Toniebox first interacted with the cloud. In particular, this indicates that the Wi-Fi password is correct.\n\"cloudreset\" [only for generation classic & rosered] when the Toniebox has been reset to factory settings. The first thing it then does (after a \"time request, see above) is to send a cloud-reset request to the Toniecloud, which removes it from any households and restores all Toniecloud settings to factory state.\n\"registered\" when the Toniebox is associated with a household in the Toniecloud. This concludes the setup from the Toniecloud side; all further states are the Toniebox itself getting ready.\n\"verified\" when the Toniebox has received confirmation of the registration.\n\"checking\" when the Toniebox checks which OTA packages to download.\n\"ota-not-needed\" if the Toniebox has determined it already has the latest firmware version.\n\"downloading\" when the Toniebox is downloading the ServicePack/PD firmware/AP-Website or firmware package.\n\"installing\" when the Toniebox is rebooting into the End-User(=EU) firmware.\n\"sfx\" [only for generations classic & rosered] when the package with sound files in multiple languages is downloaded.\n\"boot-freshness-check\" after the Freshness Check of the first boot into the EU firmware.\n\"content-download\" (with a percent value) during the download of Audio Feedbacks for the set language.\n\"age1-cable-plugged\" if the Toniebox is in 1+ ageMode and the charging cable is still plugged in. The user needs to unplug it for the Toniebox to start.\n\"done\" when the setup has been completed successfully.\n\"failed\" when setup failed (see the reason key for more info).\n\"expired\" after 2.0 hours, if the setup does not complete within that timeframe.\n", "type": "string", "enum": ["started", "connected", "cloudreset", "registered", "verified", "time", "checking", "ota-not-needed", "downloading", "installing", "sfx", "boot-freshness-check", "content-download", "age1-cable-plugged", "done", "failed", "expired"], "example": "started", "readOnly": true}, "expiresIn": {"title": "Seconds until the setup expires. This field is only present if status is neither \"done\" nor \"expired\" nor \"failed\".", "type": "number", "example": 7200.0, "readOnly": true}, "householdId": {"title": "The UUID of the household the Toniebox ended up in. Different to householdSpec if \"create\" was passed in. This field is only present if status is done.", "type": "string", "format": "uuid", "example": "46d10b24-adea-4ba9-8490-b9f29dc75fac", "readOnly": true}, "setupId": {"title": "The UUID of the setup, to be passed to TNG and newer Tonieboxes to confirm the setup. In hexadecimal format, without dashes. For Tonieboxes with the feature \"iciSetupStatus\", you can subscribe to external/${setupId}/status to get real-time updates about the setup.", "type": "string", "format": "uuid", "example": "46d10b24adea4ba98490b9f29dc75fad", "readOnly": true}, "setupType": {"title": "What kind of setup is running. If \"setup\", then the Toniebox is installed normally. If \"cloudreset\", the user must cloud-reset the Toniebox before connecting it to the Internet. If \"wifi\", there are no Toniecloud changes.", "type": "string", "enum": ["setup", "cloudreset", "wifi"], "example": "setup"}, "reason": {"title": "A code for why the setup failed.\n\"concurrentSuccess\" means that another setup was started after this setup was started, and that other setup succeeded.\"householdFailed\" means the household was deleted (or the current user removed from it/downgraded) during the setup.\n\"userDeleted\" means the current user got deleted during the request (very rare).\n\"notReset\" At the start of the setup, the Toniebox was in another household. The user started a setupType=cloudreset setup, promising that they will do a cloud reset (by turning over the Toniebox with power attached and holding both ears), but they did not do that.\n\nThis field is only present if status is \"failed\".", "type": "string", "enum": ["concurrentSuccess", "householdFailed", "userDeleted", "notReset"], "readOnly": true}}}}, "404": {"description": "There is no Toniebox setup (of the specified Toniebox ID, by the current user)"}}, "tags": ["toniebox-setup"]}, "post": {"operationId": "toniebox-setup_create", "description": "Start an automatic Toniebox setup.\nIt will be completed with the next Freshness Check (updating audio content) by the Toniebox", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"householdSpec": {"title": "Either the UUID of a household the current user has full or owner access to, or the string \"create\" (=use the current user's household, and  create a household if it does not exists already).", "type": "string", "example": "797836f4-9661-11e9-9f12-af7056a9e2a6"}, "name": {"title": "Name to assign to the Toniebox", "type": "string", "example": "Ben's Favorite Box", "maxLength": 50, "minLength": 1}, "ageMode": {"title": "Configuration of the Toniebox determining for which age it is suitable.\nOnly meaningful if the Toniebox has the feature \"ageMode\".\n\"1+\": Suitable for children 12 months or older.\n\"3+\": Suitable for children 3 years or older.\n\"default\" (if nothing else specified): Depends on the packaging of the Toniebox.\n", "type": "string", "enum": ["default", "1+", "3+"]}, "language": {"title": "Language of the Toniebox.\nOnly meaningful if the Toniebox has the feature \"language\".\n- null: unspecified\n- \"de\": Deutsch\n- \"en\": English\n- \"en-us\": English (US)\n- \"fr\": Français", "type": "string", "enum": [null, "de", "en", "en-us", "fr"]}, "timezone": {"title": "The timezone to set for the Toniebox", "type": "string"}, "setupSession": {"title": "UUID of the frontend setup session (used to track the setup across different setup attempts. If user e.g. enter an invalid Toniebox id, they are thrown backand a new setup is created).", "type": "string", "example": "4aba391f-0086-453a-a49d-000000000001"}, "frontendStatus": {"title": "An identifier of the current state the setup is in.", "type": "string", "example": "wifi-screen", "maxLength": 256}, "frontendData": {"title": "Any additional data the frontend wants to store for this setup. Max 4096 Bytes.", "type": "object", "additionalProperties": true, "example": "{\"comingFrom\": \"emailLink\", \"screenResolution\": [4000, 1000]}", "maxLength": 256}, "setupType": {"title": "What kind of setup to run. If \"setup\", then the Toniebox must not be in a household currently. If \"cloudreset\", the user must cloud-reset the Toniebox before connecting it to the Internet.", "type": "string", "enum": ["setup", "cloudreset"], "example": "setup"}}}}], "responses": {"201": {"description": "The status of the newly created setup, with firmwareVersionAfterOTA", "schema": {"type": "object", "properties": {"firmwareVersionAfterOTA": {"title": "The firmware version that will be running after the Toniebox has run the Over-the-Air (OTA) update.\nSomething like \"1.2.3\" or \"1715951512\".", "type": "string", "readOnly": true}, "tonieboxId": {"title": "Cleaned ID of the Toniebox, all uppercase", "type": "string", "example": "EXAMPLE4"}, "householdSpec": {"title": "Either the UUID of a household the current user has full or owner access to, or the string \"create\" (use the current user's household, and  create a household if it does not exists already)", "type": "string", "example": "create"}, "name": {"title": "Name to assign to the Toniebox", "type": "string", "example": "Ben's Favorite Box", "maxLength": 50, "minLength": 1}, "ageMode": {"title": "Configuration of the Toniebox determining for which age it is suitable.\nOnly meaningful if the Toniebox has the feature \"ageMode\".\n\"1+\": Suitable for children 12 months or older.\n\"3+\": Suitable for children 3 years or older.\n\"default\" (if nothing else specified): Depends on the packaging of the Toniebox.\n", "type": "string", "enum": ["default", "1+", "3+"]}, "language": {"title": "Language of the Toniebox.\nOnly meaningful if the Toniebox has the feature \"language\".\n- null: unspecified\n- \"de\": Deutsch\n- \"en\": English\n- \"en-us\": English (US)\n- \"fr\": Français", "type": "string", "enum": [null, "de", "en", "en-us", "fr"]}, "timezone": {"title": "The timezone to set for the Toniebox", "type": "string"}, "status": {"title": "Current state of the setup.\n\"started\" when the setup has just been posted and we haven't seen any requests from the Toniebox.\n\"connected\" when the Toniebox reports connection to the Toniecloud (via MQTT).\n\"time\" [only for generation classic] when the Toniebox first interacted with the cloud. In particular, this indicates that the Wi-Fi password is correct.\n\"cloudreset\" [only for generation classic & rosered] when the Toniebox has been reset to factory settings. The first thing it then does (after a \"time request, see above) is to send a cloud-reset request to the Toniecloud, which removes it from any households and restores all Toniecloud settings to factory state.\n\"registered\" when the Toniebox is associated with a household in the Toniecloud. This concludes the setup from the Toniecloud side; all further states are the Toniebox itself getting ready.\n\"verified\" when the Toniebox has received confirmation of the registration.\n\"checking\" when the Toniebox checks which OTA packages to download.\n\"ota-not-needed\" if the Toniebox has determined it already has the latest firmware version.\n\"downloading\" when the Toniebox is downloading the ServicePack/PD firmware/AP-Website or firmware package.\n\"installing\" when the Toniebox is rebooting into the End-User(=EU) firmware.\n\"sfx\" [only for generations classic & rosered] when the package with sound files in multiple languages is downloaded.\n\"boot-freshness-check\" after the Freshness Check of the first boot into the EU firmware.\n\"content-download\" (with a percent value) during the download of Audio Feedbacks for the set language.\n\"age1-cable-plugged\" if the Toniebox is in 1+ ageMode and the charging cable is still plugged in. The user needs to unplug it for the Toniebox to start.\n\"done\" when the setup has been completed successfully.\n\"failed\" when setup failed (see the reason key for more info).\n\"expired\" after 2.0 hours, if the setup does not complete within that timeframe.\n", "type": "string", "enum": ["started", "connected", "cloudreset", "registered", "verified", "time", "checking", "ota-not-needed", "downloading", "installing", "sfx", "boot-freshness-check", "content-download", "age1-cable-plugged", "done", "failed", "expired"], "example": "started", "readOnly": true}, "expiresIn": {"title": "Seconds until the setup expires. This field is only present if status is neither \"done\" nor \"expired\" nor \"failed\".", "type": "number", "example": 7200.0, "readOnly": true}, "householdId": {"title": "The UUID of the household the Toniebox ended up in. Different to householdSpec if \"create\" was passed in. This field is only present if status is done.", "type": "string", "format": "uuid", "example": "46d10b24-adea-4ba9-8490-b9f29dc75fac", "readOnly": true}, "setupId": {"title": "The UUID of the setup, to be passed to TNG and newer Tonieboxes to confirm the setup. In hexadecimal format, without dashes. For Tonieboxes with the feature \"iciSetupStatus\", you can subscribe to external/${setupId}/status to get real-time updates about the setup.", "type": "string", "format": "uuid", "example": "46d10b24adea4ba98490b9f29dc75fad", "readOnly": true}, "setupType": {"title": "What kind of setup is running. If \"setup\", then the Toniebox is installed normally. If \"cloudreset\", the user must cloud-reset the Toniebox before connecting it to the Internet. If \"wifi\", there are no Toniecloud changes.", "type": "string", "enum": ["setup", "cloudreset", "wifi"], "example": "setup"}, "reason": {"title": "A code for why the setup failed.\n\"concurrentSuccess\" means that another setup was started after this setup was started, and that other setup succeeded.\"householdFailed\" means the household was deleted (or the current user removed from it/downgraded) during the setup.\n\"userDeleted\" means the current user got deleted during the request (very rare).\n\"notReset\" At the start of the setup, the Toniebox was in another household. The user started a setupType=cloudreset setup, promising that they will do a cloud reset (by turning over the Toniebox with power attached and holding both ears), but they did not do that.\n\nThis field is only present if status is \"failed\".", "type": "string", "enum": ["concurrentSuccess", "householdFailed", "userDeleted", "notReset"], "readOnly": true}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `invalidHousehold` - The current user is not a full member in the specified target household, or there is no household with the specified UUID.\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["invalidHousehold", "required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "404": {"description": "Unknown Toniebox ID"}, "409": {"description": "The Toniebox is already associated in a household.\nAlways a JSON object, but may not include householdId.\nThis will never be returned if setupType is \"cloudreset\", only if setupType is \"setup\" or left out.\nTonieboxes with the feature \"iciSetupStatus\" will never receive this error,  but have to transmit the setup ID to the Toniecloud.\n", "schema": {"type": "object", "properties": {"householdId": {"title": "ID of the household the Toniebox is currently associated with, if the current user can access that household.", "type": "string", "format": "uuid"}}}}}, "tags": ["toniebox-setup"]}, "patch": {"operationId": "toniebox-setup_partial_update", "description": "Update the name / age mode / language of the Toniebox, both in all pending setups by this user,\nand the Toniebox itself. (if the user can already access it).", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"name": {"title": "Name to assign to the Toniebox", "type": "string", "example": "Ben's Favorite Box", "maxLength": 50, "minLength": 1}, "ageMode": {"title": "Configuration of the Toniebox determining for which age it is suitable.\nOnly meaningful if the Toniebox has the feature \"ageMode\".\n\"1+\": Suitable for children 12 months or older.\n\"3+\": Suitable for children 3 years or older.", "type": "string", "enum": ["1+", "3+"]}, "language": {"title": "Language of the Toniebox.\nOnly meaningful if the Toniebox has the feature \"language\".\n- \"de\": Deutsch\n- \"en\": English\n- \"en-us\": English (US)\n- \"fr\": Français", "type": "string", "enum": ["de", "en", "en-us", "fr"]}, "timezone": {"title": "The timezone to set for the Toniebox", "type": "string"}}}}], "responses": {"200": {"description": "The name / age mode / language change has been stored.", "schema": {"required": ["tonieboxId"], "type": "object", "properties": {"tonieboxId": {"title": "Cleaned ID of the Toniebox, all uppercase", "type": "string", "example": "EXAMPLE4"}, "householdId": {"title": "ID of the household the Toniebox is in, if the current user can access it", "type": "string", "format": "uuid", "example": "46213658-5f67-4b7a-a7ed-a2bcbc9abb62"}}}}, "404": {"description": "There is no recent Toniebox setup for this ID by the current user, and the user cannot access the Toniebox in any of their households either."}}, "tags": ["toniebox-setup"]}, "parameters": [{"name": "id", "in": "path", "required": true, "type": "string"}]}, "/toniebox-setup/{toniebox_id}/frontend-status": {"patch": {"operationId": "toniebox-setup_frontend-status_partial_update", "description": "Store a status identifier from the frontend's point of view", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"setupSession": {"title": "UUID of the frontend setup session (used to track the setup across different setup attempts. If user e.g. enter an invalid Toniebox id, they are thrown backand a new setup is created).", "type": "string", "example": "4aba391f-0086-453a-a49d-000000000001"}, "frontendStatus": {"title": "An identifier of the current state the setup is in.", "type": "string", "example": "wifi-screen", "maxLength": 256}, "frontendData": {"title": "Any additional data the frontend wants to store for this setup. Max 4096 Bytes.", "type": "object", "additionalProperties": true, "example": "{\"comingFrom\": \"emailLink\", \"screenResolution\": [4000, 1000]}", "maxLength": 256}}}}], "responses": {"200": {"description": "The status has been saved.", "schema": {"type": "object", "properties": {"tonieboxId": {"title": "Cleaned ID of the Toniebox, all uppercase", "type": "string", "example": "EXAMPLE4"}}}}, "404": {"description": "Unknown Toniebox ID"}}, "tags": ["toniebox-setup"]}, "parameters": [{"name": "toniebox_id", "in": "path", "required": true, "type": "string"}]}, "/tonieboxes/{id}": {"get": {"operationId": "tonieboxes_read", "description": "Get pre-setup information about a specific Toniebox.", "parameters": [], "responses": {"200": {"description": "The requested Toniebox.", "schema": {"type": "object", "properties": {"id": {"title": "Toniebox ID, without dashes, uppercase", "type": "string", "example": "ATB12345", "maxLength": 8, "minLength": 8}, "imageUrl": {"title": "URL of a thumbnail picture for the Toniebox", "type": "string", "format": "url", "example": "https://cdn.tonies.de/thumbnails/03-0012-i.jpg"}, "defaultName": {"title": "Default name of the Toniebox", "type": "string", "example": "John's red Toniebox"}, "ssid": {"title": "Name of the Wi-Fi network the Toniebox is creating during setup (hold both ears for some time)", "type": "string", "example": "Toniebox-12AB"}, "generation": {"title": "Toniebox generation. One of \"classic\", \"rosered\", or \"tng\".", "type": "string", "example": "tng"}, "product": {"title": "Toniebox product type. For example \"tbl\" or \"tb2\"", "type": "string", "example": "tng"}, "household": {"title": "The ID of the household the Toniebox is currently in. \"wifi\" if the current user is not logged in an thus can only perform the Wi-Fi, and not the full, Toniebox setup. A UUID if it's one of the households where the user is owner or full member. null if the Toniebox is not in any household. \"other\" if the Toniebox is in a household the user can not access.", "type": "string", "example": "other", "nullable": true}, "wifiPassword": {"title": "Password to connect to the Wi-Fi of this Toniebox, if required.", "type": "string", "nullable": true, "readOnly": true}, "workaroundSetupDisconnect": {"title": "True to indicate that this Toniebox needs a workaround during setup becauses it does not respond with HTTP 200 on POST submission.", "type": "boolean", "readOnly": true}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "404": {"description": "Unknown Toniebox ID"}}, "tags": ["tonieboxes"]}, "parameters": [{"name": "id", "in": "path", "required": true, "type": "string"}]}, "/tunes-vouchers/{code}": {"post": {"operationId": "tunes-vouchers_create", "description": "Redeem a voucher for one or more Tunes.", "parameters": [], "responses": {"200": {"description": "Voucher was successfully redeemed for Tunes.", "schema": {"type": "object", "properties": {"tunes": {"description": "The Tunes objects that this voucher was redeemed for.", "type": "array", "items": {"description": "The Tune, i.e. the instance created by the user's purchase. Has main GraphQL fields.", "type": "object", "properties": {"id": {"title": "ID of the specific Tune", "type": "string", "format": "uuid"}, "assignCountCurrent": {"title": "Number of Tonies this Tune is assigned to (0 after just being bought)", "type": "integer"}, "assignCountRemaining": {"title": "Number of Tonies this Tune can be assigned to", "type": "integer"}, "assignedTonies": {"title": "Tonies that this Tune is assigned to", "type": "array", "items": {"type": "object", "properties": {"id": {"description": "Tonie ID", "type": "string", "example": "0BD624073331F6E4"}, "householdId": {"description": "ID of the household the Tonie is in", "type": "string", "format": "uuid"}, "imageUrl": {"description": "The URL to the image to represent this Tonie", "type": "string", "format": "url"}, "title": {"description": "Name of this Tonie", "type": "string"}, "tonieType": {"description": "Whether this is a Content Tonie or Creative Tonie", "type": "string", "enum": ["content", "creative"]}}}}, "suitableTonies": {"title": "Tonies that this Tune could be assigned to. This does NOT include the Tonie the Tune is currently assigned to, if any. Softly deprecated: In most cases, TunesItem.compatibleTonies is the better  (and faster) option.", "type": "array", "items": {"type": "object", "properties": {"id": {"description": "Tonie ID", "type": "string", "example": "0BD624073331F6E4"}, "householdId": {"description": "ID of the household the Tonie is in", "type": "string", "format": "uuid"}, "imageUrl": {"description": "The URL to the image to represent this Tonie", "type": "string", "format": "url"}, "title": {"description": "Name of this Tonie", "type": "string"}, "tonieType": {"description": "Whether this is a Content Tonie or Creative Tonie", "type": "string", "enum": ["content", "creative"]}}}}, "item": {"description": "A Tunes item (aka article)", "type": "object", "properties": {"allCreativeTonies": {"description": "Whether this TunesItem fits onto all Creative Tonies, no matter the item/series. Note that TunesItems can also fit onto specific Creative Tonie items.", "type": "boolean"}, "authors": {"description": "Authors (writer, singer etc.) of this Tunes item", "type": "array", "items": {"type": "object", "properties": {"name": {"description": "The full name of the author", "type": "string", "example": "Elfie Donnelly"}}}}, "contentInfo": {"description": "Information about the audio content associated with the Tunes item", "type": "object", "properties": {"chapters": {"description": "The chapters / songs that make up this Tune", "type": "array", "items": {"type": "object", "properties": {"seconds": {"description": "Length of this chapter in seconds", "type": "number"}, "title": {"description": "Name of this chapter", "type": "string"}, "id": {"description": "ID of this TunesItem chapter", "type": "string", "format": "uuid"}}}}, "seconds": {"description": "Length of the whole content, in seconds", "type": "number"}}}, "description": {"description": "Plaintext (may include line endings) describing the content of the Tune", "type": "string"}, "genre": {"description": "Category of the Tunes content", "type": "object", "properties": {"id": {"description": "Genre identifier", "type": "string", "format": "uuid"}, "title": {"description": "Genre name (in the user's current language)", "type": "string", "format": "uuid"}}, "example": {"id": "6d053810-4170-4177-a073-07ee542b875f", "title": "Audio Book"}}, "id": {"description": "Identifier of this Tunes item. Not to be confused with the Tune itself; the Tune is associated with a specific user and an item", "type": "string", "format": "uuid"}, "minAge": {"description": "Minimum target age of the content", "type": "integer"}, "retailPrice": {"description": "What purchasing this Tunes item costs for the current user. null if the item is not for sale", "type": "object", "properties": {"amount": {"description": "Decimal of the total price, separated with a dot.", "type": "string", "example": "4.99"}, "centAmount": {"description": "Price in cents, as integer.", "type": "integer", "exmple": 499}, "currency": {"description": "Currency code per ISO 4217, e.g. \"EUR\" or \"USD\"", "type": "string", "example": "EUR"}}, "nullable": true}, "salesId": {"description": "ID of this item as communicated on invoices. null if the item is not for sale", "type": "string", "example": "2000000114", "nullable": true}, "series": {"description": "Grouping of Tunes and Content Tonies, e.g. \"Hui Buh - Neue Welt\"", "type": "object", "properties": {"id": {"description": "ID of this series", "type": "string", "format": "uuid"}, "name": {"description": "Name of this series, e.g. \"HUI BUH - Klassik-Hörspiele\"", "type": "string"}, "group": {"description": "The series group / character / product line across multiple series, e.g. \"Hui Buh\"", "type": "object", "properties": {"id": {"description": "ID of this series group", "type": "string", "format": "uuid"}, "name": {"description": "Name of this series group", "type": "string"}}}, "subSeriesName": {"description": "Name of this series within a group, e.g. \"Klassik-Hörspiele\"", "type": "string"}, "slug": {"description": "URL-safe identifier of this series", "type": "string", "pattern": "^[-_a-z0-9]+$"}}}, "thumbnail": {"description": "URL of an image for the Tune", "type": "string", "format": "url"}, "title": {"description": "The title of the Tunes item", "type": "string", "example": "Benjamin als Koch"}, "tonieShopUrl": {"description": "Shop URL (may depend on the user's country) where the user can buy compatible Tonies for this Tunes item", "type": "string", "example": "https://tonies.de/shop/tonies/benjamin-bluemchen/"}}}}}}}}}, "404": {"description": "There is no voucher with this code."}, "409": {"description": "The user owns some or all of the Tunes items already, and because every user  can own every Tunes item just once, the voucher cannot be redeemed. Contact customer care or redeem the voucher with another user.", "schema": {"type": "object", "properties": {"ownedTunes": {"title": "The Tunes objects that the user owns already.", "type": "array", "items": {"description": "The Tune, i.e. the instance created by the user's purchase. Has main GraphQL fields.", "type": "object", "properties": {"id": {"title": "ID of the specific Tune", "type": "string", "format": "uuid"}, "assignCountCurrent": {"title": "Number of Tonies this Tune is assigned to (0 after just being bought)", "type": "integer"}, "assignCountRemaining": {"title": "Number of Tonies this Tune can be assigned to", "type": "integer"}, "assignedTonies": {"title": "Tonies that this Tune is assigned to", "type": "array", "items": {"type": "object", "properties": {"id": {"description": "Tonie ID", "type": "string", "example": "0BD624073331F6E4"}, "householdId": {"description": "ID of the household the Tonie is in", "type": "string", "format": "uuid"}, "imageUrl": {"description": "The URL to the image to represent this Tonie", "type": "string", "format": "url"}, "title": {"description": "Name of this Tonie", "type": "string"}, "tonieType": {"description": "Whether this is a Content Tonie or Creative Tonie", "type": "string", "enum": ["content", "creative"]}}}}, "suitableTonies": {"title": "Tonies that this Tune could be assigned to. This does NOT include the Tonie the Tune is currently assigned to, if any. Softly deprecated: In most cases, TunesItem.compatibleTonies is the better  (and faster) option.", "type": "array", "items": {"type": "object", "properties": {"id": {"description": "Tonie ID", "type": "string", "example": "0BD624073331F6E4"}, "householdId": {"description": "ID of the household the Tonie is in", "type": "string", "format": "uuid"}, "imageUrl": {"description": "The URL to the image to represent this Tonie", "type": "string", "format": "url"}, "title": {"description": "Name of this Tonie", "type": "string"}, "tonieType": {"description": "Whether this is a Content Tonie or Creative Tonie", "type": "string", "enum": ["content", "creative"]}}}}, "item": {"description": "A Tunes item (aka article)", "type": "object", "properties": {"allCreativeTonies": {"description": "Whether this TunesItem fits onto all Creative Tonies, no matter the item/series. Note that TunesItems can also fit onto specific Creative Tonie items.", "type": "boolean"}, "authors": {"description": "Authors (writer, singer etc.) of this Tunes item", "type": "array", "items": {"type": "object", "properties": {"name": {"description": "The full name of the author", "type": "string", "example": "Elfie Donnelly"}}}}, "contentInfo": {"description": "Information about the audio content associated with the Tunes item", "type": "object", "properties": {"chapters": {"description": "The chapters / songs that make up this Tune", "type": "array", "items": {"type": "object", "properties": {"seconds": {"description": "Length of this chapter in seconds", "type": "number"}, "title": {"description": "Name of this chapter", "type": "string"}, "id": {"description": "ID of this TunesItem chapter", "type": "string", "format": "uuid"}}}}, "seconds": {"description": "Length of the whole content, in seconds", "type": "number"}}}, "description": {"description": "Plaintext (may include line endings) describing the content of the Tune", "type": "string"}, "genre": {"description": "Category of the Tunes content", "type": "object", "properties": {"id": {"description": "Genre identifier", "type": "string", "format": "uuid"}, "title": {"description": "Genre name (in the user's current language)", "type": "string", "format": "uuid"}}, "example": {"id": "6d053810-4170-4177-a073-07ee542b875f", "title": "Audio Book"}}, "id": {"description": "Identifier of this Tunes item. Not to be confused with the Tune itself; the Tune is associated with a specific user and an item", "type": "string", "format": "uuid"}, "minAge": {"description": "Minimum target age of the content", "type": "integer"}, "retailPrice": {"description": "What purchasing this Tunes item costs for the current user. null if the item is not for sale", "type": "object", "properties": {"amount": {"description": "Decimal of the total price, separated with a dot.", "type": "string", "example": "4.99"}, "centAmount": {"description": "Price in cents, as integer.", "type": "integer", "exmple": 499}, "currency": {"description": "Currency code per ISO 4217, e.g. \"EUR\" or \"USD\"", "type": "string", "example": "EUR"}}, "nullable": true}, "salesId": {"description": "ID of this item as communicated on invoices. null if the item is not for sale", "type": "string", "example": "2000000114", "nullable": true}, "series": {"description": "Grouping of Tunes and Content Tonies, e.g. \"Hui Buh - Neue Welt\"", "type": "object", "properties": {"id": {"description": "ID of this series", "type": "string", "format": "uuid"}, "name": {"description": "Name of this series, e.g. \"HUI BUH - Klassik-Hörspiele\"", "type": "string"}, "group": {"description": "The series group / character / product line across multiple series, e.g. \"Hui Buh\"", "type": "object", "properties": {"id": {"description": "ID of this series group", "type": "string", "format": "uuid"}, "name": {"description": "Name of this series group", "type": "string"}}}, "subSeriesName": {"description": "Name of this series within a group, e.g. \"Klassik-Hörspiele\"", "type": "string"}, "slug": {"description": "URL-safe identifier of this series", "type": "string", "pattern": "^[-_a-z0-9]+$"}}}, "thumbnail": {"description": "URL of an image for the Tune", "type": "string", "format": "url"}, "title": {"description": "The title of the Tunes item", "type": "string", "example": "Benjamin als Koch"}, "tonieShopUrl": {"description": "Shop URL (may depend on the user's country) where the user can buy compatible Tonies for this Tunes item", "type": "string", "example": "https://tonies.de/shop/tonies/benjamin-bluemchen/"}}}}}, "nullable": true}}}}, "410": {"description": "This voucher has already been used.", "schema": {"type": "object", "properties": {"tunes": {"title": "The Tunes objects that the voucher was redeemed for. Only present if all of them belong to the current user.", "type": "array", "items": {"description": "The Tune, i.e. the instance created by the user's purchase. Has main GraphQL fields.", "type": "object", "properties": {"id": {"title": "ID of the specific Tune", "type": "string", "format": "uuid"}, "assignCountCurrent": {"title": "Number of Tonies this Tune is assigned to (0 after just being bought)", "type": "integer"}, "assignCountRemaining": {"title": "Number of Tonies this Tune can be assigned to", "type": "integer"}, "assignedTonies": {"title": "Tonies that this Tune is assigned to", "type": "array", "items": {"type": "object", "properties": {"id": {"description": "Tonie ID", "type": "string", "example": "0BD624073331F6E4"}, "householdId": {"description": "ID of the household the Tonie is in", "type": "string", "format": "uuid"}, "imageUrl": {"description": "The URL to the image to represent this Tonie", "type": "string", "format": "url"}, "title": {"description": "Name of this Tonie", "type": "string"}, "tonieType": {"description": "Whether this is a Content Tonie or Creative Tonie", "type": "string", "enum": ["content", "creative"]}}}}, "suitableTonies": {"title": "Tonies that this Tune could be assigned to. This does NOT include the Tonie the Tune is currently assigned to, if any. Softly deprecated: In most cases, TunesItem.compatibleTonies is the better  (and faster) option.", "type": "array", "items": {"type": "object", "properties": {"id": {"description": "Tonie ID", "type": "string", "example": "0BD624073331F6E4"}, "householdId": {"description": "ID of the household the Tonie is in", "type": "string", "format": "uuid"}, "imageUrl": {"description": "The URL to the image to represent this Tonie", "type": "string", "format": "url"}, "title": {"description": "Name of this Tonie", "type": "string"}, "tonieType": {"description": "Whether this is a Content Tonie or Creative Tonie", "type": "string", "enum": ["content", "creative"]}}}}, "item": {"description": "A Tunes item (aka article)", "type": "object", "properties": {"allCreativeTonies": {"description": "Whether this TunesItem fits onto all Creative Tonies, no matter the item/series. Note that TunesItems can also fit onto specific Creative Tonie items.", "type": "boolean"}, "authors": {"description": "Authors (writer, singer etc.) of this Tunes item", "type": "array", "items": {"type": "object", "properties": {"name": {"description": "The full name of the author", "type": "string", "example": "Elfie Donnelly"}}}}, "contentInfo": {"description": "Information about the audio content associated with the Tunes item", "type": "object", "properties": {"chapters": {"description": "The chapters / songs that make up this Tune", "type": "array", "items": {"type": "object", "properties": {"seconds": {"description": "Length of this chapter in seconds", "type": "number"}, "title": {"description": "Name of this chapter", "type": "string"}, "id": {"description": "ID of this TunesItem chapter", "type": "string", "format": "uuid"}}}}, "seconds": {"description": "Length of the whole content, in seconds", "type": "number"}}}, "description": {"description": "Plaintext (may include line endings) describing the content of the Tune", "type": "string"}, "genre": {"description": "Category of the Tunes content", "type": "object", "properties": {"id": {"description": "Genre identifier", "type": "string", "format": "uuid"}, "title": {"description": "Genre name (in the user's current language)", "type": "string", "format": "uuid"}}, "example": {"id": "6d053810-4170-4177-a073-07ee542b875f", "title": "Audio Book"}}, "id": {"description": "Identifier of this Tunes item. Not to be confused with the Tune itself; the Tune is associated with a specific user and an item", "type": "string", "format": "uuid"}, "minAge": {"description": "Minimum target age of the content", "type": "integer"}, "retailPrice": {"description": "What purchasing this Tunes item costs for the current user. null if the item is not for sale", "type": "object", "properties": {"amount": {"description": "Decimal of the total price, separated with a dot.", "type": "string", "example": "4.99"}, "centAmount": {"description": "Price in cents, as integer.", "type": "integer", "exmple": 499}, "currency": {"description": "Currency code per ISO 4217, e.g. \"EUR\" or \"USD\"", "type": "string", "example": "EUR"}}, "nullable": true}, "salesId": {"description": "ID of this item as communicated on invoices. null if the item is not for sale", "type": "string", "example": "2000000114", "nullable": true}, "series": {"description": "Grouping of Tunes and Content Tonies, e.g. \"Hui Buh - Neue Welt\"", "type": "object", "properties": {"id": {"description": "ID of this series", "type": "string", "format": "uuid"}, "name": {"description": "Name of this series, e.g. \"HUI BUH - Klassik-Hörspiele\"", "type": "string"}, "group": {"description": "The series group / character / product line across multiple series, e.g. \"Hui Buh\"", "type": "object", "properties": {"id": {"description": "ID of this series group", "type": "string", "format": "uuid"}, "name": {"description": "Name of this series group", "type": "string"}}}, "subSeriesName": {"description": "Name of this series within a group, e.g. \"Klassik-Hörspiele\"", "type": "string"}, "slug": {"description": "URL-safe identifier of this series", "type": "string", "pattern": "^[-_a-z0-9]+$"}}}, "thumbnail": {"description": "URL of an image for the Tune", "type": "string", "format": "url"}, "title": {"description": "The title of the Tunes item", "type": "string", "example": "Benjamin als Koch"}, "tonieShopUrl": {"description": "Shop URL (may depend on the user's country) where the user can buy compatible Tonies for this Tunes item", "type": "string", "example": "https://tonies.de/shop/tonies/benjamin-bluemchen/"}}}}}, "nullable": true}}}}, "429": {"description": "The user tried many unusuccessful voucher codes in a short time.Voucher access is being rate-limited by the API", "schema": {"type": "object", "properties": {"retryInSeconds": {"title": "Duration the user should hold off inputting (all requests will return 429 and extend the ban)", "type": "integer"}}}}}, "tags": ["tunes-vouchers"]}, "parameters": [{"name": "code", "in": "path", "required": true, "type": "string"}]}, "/tunesitems/{sales_id}/compatible-content-tonie-item-sales-ids": {"get": {"operationId": "tunesitems_compatible_content_tonie_item_sales_ids", "description": "Return which Content Tonie items are compatible to a Tunes-Item (identified by its Sales ID)", "parameters": [], "responses": {"200": {"description": "Returns an array of Content Tonie item sales IDs this Tunes item is compatible with.", "schema": {"type": "array", "items": {"type": "string"}}}}, "tags": ["tunesitems"]}, "parameters": [{"name": "sales_id", "in": "path", "description": "(Ausgefüllt via Octonie)", "required": true, "type": "string"}]}, "/version": {"get": {"operationId": "version_list", "description": "Return the internal cloudservices backend version number.", "parameters": [], "responses": {"200": {"description": "Internal cloudservices backend version number (for debugging) as plain text", "example": "v2026.03.27/2da3a57cf"}}, "tags": ["version"]}, "parameters": []}, "/wifi-setup/{id}": {"get": {"operationId": "wifi-setup_read", "description": "Get information about the current state of an automatic Toniebox setup.", "parameters": [], "responses": {"200": {"description": "The current setup status", "schema": {"type": "object", "properties": {"tonieboxId": {"title": "Cleaned ID of the Toniebox, all uppercase", "type": "string", "example": "EXAMPLE4"}, "householdSpec": {"title": "Either the UUID of a household the current user has full or owner access to, or the string \"create\" (use the current user's household, and  create a household if it does not exists already)", "type": "string", "example": "create"}, "name": {"title": "Name to assign to the Toniebox", "type": "string", "example": "Ben's Favorite Box", "maxLength": 50, "minLength": 1}, "ageMode": {"title": "Configuration of the Toniebox determining for which age it is suitable.\nOnly meaningful if the Toniebox has the feature \"ageMode\".\n\"1+\": Suitable for children 12 months or older.\n\"3+\": Suitable for children 3 years or older.\n\"default\" (if nothing else specified): Depends on the packaging of the Toniebox.\n", "type": "string", "enum": ["default", "1+", "3+"]}, "language": {"title": "Language of the Toniebox.\nOnly meaningful if the Toniebox has the feature \"language\".\n- null: unspecified\n- \"de\": Deutsch\n- \"en\": English\n- \"en-us\": English (US)\n- \"fr\": Français", "type": "string", "enum": [null, "de", "en", "en-us", "fr"]}, "timezone": {"title": "The timezone to set for the Toniebox", "type": "string"}, "status": {"title": "Current state of the setup.\n\"started\" when the setup has just been posted and we haven't seen any requests from the Toniebox.\n\"connected\" when the Toniebox reports connection to the Toniecloud (via MQTT).\n\"time\" [only for generation classic] when the Toniebox first interacted with the cloud. In particular, this indicates that the Wi-Fi password is correct.\n\"cloudreset\" [only for generation classic & rosered] when the Toniebox has been reset to factory settings. The first thing it then does (after a \"time request, see above) is to send a cloud-reset request to the Toniecloud, which removes it from any households and restores all Toniecloud settings to factory state.\n\"registered\" when the Toniebox is associated with a household in the Toniecloud. This concludes the setup from the Toniecloud side; all further states are the Toniebox itself getting ready.\n\"verified\" when the Toniebox has received confirmation of the registration.\n\"checking\" when the Toniebox checks which OTA packages to download.\n\"ota-not-needed\" if the Toniebox has determined it already has the latest firmware version.\n\"downloading\" when the Toniebox is downloading the ServicePack/PD firmware/AP-Website or firmware package.\n\"installing\" when the Toniebox is rebooting into the End-User(=EU) firmware.\n\"sfx\" [only for generations classic & rosered] when the package with sound files in multiple languages is downloaded.\n\"boot-freshness-check\" after the Freshness Check of the first boot into the EU firmware.\n\"content-download\" (with a percent value) during the download of Audio Feedbacks for the set language.\n\"age1-cable-plugged\" if the Toniebox is in 1+ ageMode and the charging cable is still plugged in. The user needs to unplug it for the Toniebox to start.\n\"done\" when the setup has been completed successfully.\n\"failed\" when setup failed (see the reason key for more info).\n\"expired\" after 2.0 hours, if the setup does not complete within that timeframe.\n", "type": "string", "enum": ["started", "connected", "cloudreset", "registered", "verified", "time", "checking", "ota-not-needed", "downloading", "installing", "sfx", "boot-freshness-check", "content-download", "age1-cable-plugged", "done", "failed", "expired"], "example": "started", "readOnly": true}, "expiresIn": {"title": "Seconds until the setup expires. This field is only present if status is neither \"done\" nor \"expired\" nor \"failed\".", "type": "number", "example": 7200.0, "readOnly": true}, "householdId": {"title": "The UUID of the household the Toniebox ended up in. Different to householdSpec if \"create\" was passed in. This field is only present if status is done.", "type": "string", "format": "uuid", "example": "46d10b24-adea-4ba9-8490-b9f29dc75fac", "readOnly": true}, "setupId": {"title": "The UUID of the setup, to be passed to TNG and newer Tonieboxes to confirm the setup. In hexadecimal format, without dashes. For Tonieboxes with the feature \"iciSetupStatus\", you can subscribe to external/${setupId}/status to get real-time updates about the setup.", "type": "string", "format": "uuid", "example": "46d10b24adea4ba98490b9f29dc75fad", "readOnly": true}, "setupType": {"title": "What kind of setup is running. If \"setup\", then the Toniebox is installed normally. If \"cloudreset\", the user must cloud-reset the Toniebox before connecting it to the Internet. If \"wifi\", there are no Toniecloud changes.", "type": "string", "enum": ["setup", "cloudreset", "wifi"], "example": "setup"}, "reason": {"title": "A code for why the setup failed.\n\"concurrentSuccess\" means that another setup was started after this setup was started, and that other setup succeeded.\"householdFailed\" means the household was deleted (or the current user removed from it/downgraded) during the setup.\n\"userDeleted\" means the current user got deleted during the request (very rare).\n\"notReset\" At the start of the setup, the Toniebox was in another household. The user started a setupType=cloudreset setup, promising that they will do a cloud reset (by turning over the Toniebox with power attached and holding both ears), but they did not do that.\n\nThis field is only present if status is \"failed\".", "type": "string", "enum": ["concurrentSuccess", "householdFailed", "userDeleted", "notReset"], "readOnly": true}}}}, "404": {"description": "There is no Toniebox setup (of the specified Toniebox ID, by the current user)"}}, "tags": ["wifi-setup"]}, "post": {"operationId": "wifi-setup_create", "description": "Start an automatic Toniebox setup, but without assigning anything on the server;\njust to associate a new Wi-Fi network.\nIt will be completed with the next freshness check by the Toniebox", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"setupSession": {"title": "UUID of the frontend setup session (used to track the setup across different setup attempts. If user e.g. enter an invalid Toniebox id, they are thrown backand a new setup is created).", "type": "string", "example": "4aba391f-0086-453a-a49d-000000000001"}, "frontendStatus": {"title": "An identifier of the current state the setup is in.", "type": "string", "example": "wifi-screen", "maxLength": 256}, "frontendData": {"title": "Any additional data the frontend wants to store for this setup. Max 4096 Bytes.", "type": "object", "additionalProperties": true, "example": "{\"comingFrom\": \"emailLink\", \"screenResolution\": [4000, 1000]}", "maxLength": 256}}}}], "responses": {"201": {"description": "The status of the newly created setup", "schema": {"type": "object", "properties": {"tonieboxId": {"title": "Cleaned ID of the Toniebox, all uppercase", "type": "string", "example": "EXAMPLE4"}, "householdSpec": {"title": "Either the UUID of a household the current user has full or owner access to, or the string \"create\" (use the current user's household, and  create a household if it does not exists already)", "type": "string", "example": "create"}, "name": {"title": "Name to assign to the Toniebox", "type": "string", "example": "Ben's Favorite Box", "maxLength": 50, "minLength": 1}, "ageMode": {"title": "Configuration of the Toniebox determining for which age it is suitable.\nOnly meaningful if the Toniebox has the feature \"ageMode\".\n\"1+\": Suitable for children 12 months or older.\n\"3+\": Suitable for children 3 years or older.\n\"default\" (if nothing else specified): Depends on the packaging of the Toniebox.\n", "type": "string", "enum": ["default", "1+", "3+"]}, "language": {"title": "Language of the Toniebox.\nOnly meaningful if the Toniebox has the feature \"language\".\n- null: unspecified\n- \"de\": Deutsch\n- \"en\": English\n- \"en-us\": English (US)\n- \"fr\": Français", "type": "string", "enum": [null, "de", "en", "en-us", "fr"]}, "timezone": {"title": "The timezone to set for the Toniebox", "type": "string"}, "status": {"title": "Current state of the setup.\n\"started\" when the setup has just been posted and we haven't seen any requests from the Toniebox.\n\"connected\" when the Toniebox reports connection to the Toniecloud (via MQTT).\n\"time\" [only for generation classic] when the Toniebox first interacted with the cloud. In particular, this indicates that the Wi-Fi password is correct.\n\"cloudreset\" [only for generation classic & rosered] when the Toniebox has been reset to factory settings. The first thing it then does (after a \"time request, see above) is to send a cloud-reset request to the Toniecloud, which removes it from any households and restores all Toniecloud settings to factory state.\n\"registered\" when the Toniebox is associated with a household in the Toniecloud. This concludes the setup from the Toniecloud side; all further states are the Toniebox itself getting ready.\n\"verified\" when the Toniebox has received confirmation of the registration.\n\"checking\" when the Toniebox checks which OTA packages to download.\n\"ota-not-needed\" if the Toniebox has determined it already has the latest firmware version.\n\"downloading\" when the Toniebox is downloading the ServicePack/PD firmware/AP-Website or firmware package.\n\"installing\" when the Toniebox is rebooting into the End-User(=EU) firmware.\n\"sfx\" [only for generations classic & rosered] when the package with sound files in multiple languages is downloaded.\n\"boot-freshness-check\" after the Freshness Check of the first boot into the EU firmware.\n\"content-download\" (with a percent value) during the download of Audio Feedbacks for the set language.\n\"age1-cable-plugged\" if the Toniebox is in 1+ ageMode and the charging cable is still plugged in. The user needs to unplug it for the Toniebox to start.\n\"done\" when the setup has been completed successfully.\n\"failed\" when setup failed (see the reason key for more info).\n\"expired\" after 2.0 hours, if the setup does not complete within that timeframe.\n", "type": "string", "enum": ["started", "connected", "cloudreset", "registered", "verified", "time", "checking", "ota-not-needed", "downloading", "installing", "sfx", "boot-freshness-check", "content-download", "age1-cable-plugged", "done", "failed", "expired"], "example": "started", "readOnly": true}, "expiresIn": {"title": "Seconds until the setup expires. This field is only present if status is neither \"done\" nor \"expired\" nor \"failed\".", "type": "number", "example": 7200.0, "readOnly": true}, "householdId": {"title": "The UUID of the household the Toniebox ended up in. Different to householdSpec if \"create\" was passed in. This field is only present if status is done.", "type": "string", "format": "uuid", "example": "46d10b24-adea-4ba9-8490-b9f29dc75fac", "readOnly": true}, "setupId": {"title": "The UUID of the setup, to be passed to TNG and newer Tonieboxes to confirm the setup. In hexadecimal format, without dashes. For Tonieboxes with the feature \"iciSetupStatus\", you can subscribe to external/${setupId}/status to get real-time updates about the setup.", "type": "string", "format": "uuid", "example": "46d10b24adea4ba98490b9f29dc75fad", "readOnly": true}, "setupType": {"title": "What kind of setup is running. If \"setup\", then the Toniebox is installed normally. If \"cloudreset\", the user must cloud-reset the Toniebox before connecting it to the Internet. If \"wifi\", there are no Toniecloud changes.", "type": "string", "enum": ["setup", "cloudreset", "wifi"], "example": "setup"}, "reason": {"title": "A code for why the setup failed.\n\"concurrentSuccess\" means that another setup was started after this setup was started, and that other setup succeeded.\"householdFailed\" means the household was deleted (or the current user removed from it/downgraded) during the setup.\n\"userDeleted\" means the current user got deleted during the request (very rare).\n\"notReset\" At the start of the setup, the Toniebox was in another household. The user started a setupType=cloudreset setup, promising that they will do a cloud reset (by turning over the Toniebox with power attached and holding both ears), but they did not do that.\n\nThis field is only present if status is \"failed\".", "type": "string", "enum": ["concurrentSuccess", "householdFailed", "userDeleted", "notReset"], "readOnly": true}}}}, "400": {"description": "The request did not contain all expected parameters in the documented format.  This is likely a bug in the client implementation, and should be logged client-side, with an apology to the user.", "schema": {"required": ["errors"], "type": "object", "properties": {"errors": {"type": "array", "items": {"required": ["code"], "type": "object", "properties": {"key": {"description": "The key in the request that was incorrect (if any)", "type": "string"}, "code": {"description": "Machine-readable code for the reason of the error:\n\n- `setupRequired` - A Wi-Fi setup cannot be started because the Toniebox has never been set up. (Only for Tonieboxes without \"iciSetupStatus\" in features).\n\n- `required` - The field was missing in the request and needs to be set.\n\n- `maxLength` - The value is too long, must be shorter\n\n- `minLength` - The value is too short, must be longer\n\n- `blank` - The value must not be empty (same as min_length=1)\n\n- `invalidChoice` - The field is an enum; you must pick one of the declared options.\n\n- `invalid` - Another field validation problem. For instance, an email field may not be a valid email address\n", "type": "string", "enum": ["setupRequired", "required", "maxLength", "minLength", "blank", "invalidChoice", "invalid"]}}}}}}}, "404": {"description": "Unknown Toniebox ID"}}, "tags": ["wifi-setup"]}, "parameters": [{"name": "id", "in": "path", "required": true, "type": "string"}]}, "/wifi-setup/{toniebox_id}/frontend-status": {"patch": {"operationId": "wifi-setup_frontend-status_partial_update", "description": "Store a status identifier from the frontend's point of view", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"setupSession": {"title": "UUID of the frontend setup session (used to track the setup across different setup attempts. If user e.g. enter an invalid Toniebox id, they are thrown backand a new setup is created).", "type": "string", "example": "4aba391f-0086-453a-a49d-000000000001"}, "frontendStatus": {"title": "An identifier of the current state the setup is in.", "type": "string", "example": "wifi-screen", "maxLength": 256}, "frontendData": {"title": "Any additional data the frontend wants to store for this setup. Max 4096 Bytes.", "type": "object", "additionalProperties": true, "example": "{\"comingFrom\": \"emailLink\", \"screenResolution\": [4000, 1000]}", "maxLength": 256}}}}], "responses": {"200": {"description": "The status has been saved.", "schema": {"type": "object", "properties": {"tonieboxId": {"title": "Cleaned ID of the Toniebox, all uppercase", "type": "string", "example": "EXAMPLE4"}}}}, "404": {"description": "Unknown Toniebox ID"}}, "tags": ["wifi-setup"]}, "parameters": [{"name": "toniebox_id", "in": "path", "required": true, "type": "string"}]}}, "definitions": {"Child": {"type": "object", "properties": {"id": {"title": "UUID of this child", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "Name of this child. null for no name given.", "type": "string"}, "birthDate": {"title": "Optional birth date. A full ISO date like \"2020-12-31\", or year and month, like \"2020-12\", or unspecified (null).", "type": "string"}, "gender": {"title": "One of \"male\", \"female\", \"diverse\". null for unspecified.", "type": "string", "choices": [null, "male", "female", "diverse"]}, "situations": {"title": "List of situations that this child uses Tonieboxes in.  For example [\"playMovement\", \"singalong\", \"learning\", \"relaxing\", \"travel\", \"bedtimeRoutine\"]. Can be empty. null for unspecified.", "type": "array", "items": {"type": "string"}}, "flowIdentifier": {"title": "Identifier of in which part of which application the child was last updated. Freetext, something like \"app-android-toniebox-v1\" or so. Optional. Write-only, will not be included in responses.", "type": "string"}, "taxonomiesPreferences": {"title": "List of taxonomies the child prefers, e.g.  [\"subject:animals\",\"subject:space\",\"character_name:moana\",\"character_name:elmo\"]", "type": "array", "items": {"type": "string"}}, "taxonomiesAvoid": {"title": "List of taxonomies to avoid, e.g. [\"content_sensitive:ghosts_monsters\",\"content_sensitive:grossout_pottyhumor\"]", "type": "array", "items": {"type": "string"}}, "tonieboxIds": {"title": "Toniebox IDs of the Tonieboxes this child interacts with in this household.", "type": "array", "items": {"type": "string"}}}}, "Consent": {"required": ["choice"], "type": "object", "properties": {"choice": {"title": "\"accepted\" (user consented) or \"declined\" (user declined the consent) or null (no information)", "type": "string", "choices": [null, "declined", "accepted"]}}}, "ContentToniePatchRequest": {"type": "object", "properties": {"lock": {"title": "Lock", "description": "If enabled: This Tonie will not be claimed into another household.", "type": "boolean"}, "language": {"title": "Language", "description": "Optional language code (preferred in Unicode format) to switch the language of a Content Tonie (Only available for multi-language Content Tonies)", "type": "string", "minLength": 1}, "chapters": {"description": "Optional list of chapters to update the chapters of a Content Tonie. Each chapter is a dictionary with a \"file\" key. (Only available when \"Content Stacking on Content Tonie\" feature is enabled)", "type": "array", "items": {"type": "object", "additionalProperties": {"type": "string", "x-nullable": true}}}}}, "CreativeTonie": {"type": "object", "properties": {"id": {"title": "The ID of the Creative Tonie. At the moment, this is the actual ID.", "type": "string", "example": "1234ABCDE00304E0", "readOnly": true}, "householdId": {"title": "The ID of the household this Creative Tonie is in", "type": "string", "format": "uuid", "readOnly": true}, "name": {"title": "The human-readable name of the Creative Tonie.", "type": "string", "example": "John's favorite red Tonie", "maxLength": 100}, "live": {"title": "Whether live mode is active. When live mode is active, new content gets inserted at the beginning instead of the end.", "type": "boolean", "default": false}, "private": {"title": "Private mode.\nIf enabled, then only Tonieboxes registered in this household can play this Tonie. Tonieboxes without a household or in other households will get an error message.\nIf private=false, then every Toniebox can play this Tonie.", "type": "boolean", "default": false}, "imageUrl": {"title": "The URL to the image to represent this Creative Tonie (e.g. https://cdn.tonies.de/thumbnails/98-0412.png ).", "type": "string", "format": "url", "readOnly": true}, "transcodingErrors": {"title": "A list of transcoding errors that happened since the last transcoding (i.e. a PUT or PATCH with different chapters).", "type": "array", "items": {"type": "object", "properties": {"reason": {"title": "Error type of why the transcoding failed. \"wrongFormat\" if a file was in an unsupported format, \"tooLong\" if all files exceeded 90 minutes in total, \"unknownError\" for internal errors.", "type": "string", "enum": ["wrongFormat", "tooLong", "unknownError"]}, "deletedChapters": {"title": "The chapters that were removed because of the error, if any.", "type": "array", "items": {"type": "object", "properties": {"title": {"title": "Human-readable name for this chapter", "type": "string", "example": "My recording on 2018-08-16", "maxLength": 128}, "seconds": {"title": "Length of this chapter in seconds. Available only if reason is \"tooLong\".", "type": "number"}}}}}}}, "secondsRemaining": {"title": "Number of seconds that can be added to this Creative Tonie", "type": "number", "readOnly": true}, "secondsPresent": {"title": "Current length of all content on the Creative Tonie", "type": "number", "readOnly": true}, "chaptersRemaining": {"title": "Number of chapters that can be added to this Creative Tonie", "type": "integer", "readOnly": true}, "chaptersPresent": {"title": "Current number of chapters on the Creative Tonie", "type": "integer", "readOnly": true}, "transcoding": {"title": "Is this Tonie currently transcoding?", "type": "boolean", "readOnly": true}, "lastUpdate": {"title": "ISO 8601 timestamp (e.g. \"2022-04-05T12:26:01+0100\") of the time when the Creative Tonie content was last updated. This is changed once transcoding finishes. null if the Creative Tonie is completely empty. Applying or removing Tunes does not impact this timestamp.", "type": "string", "readOnly": true}, "chapters": {"title": "All chapters on this Creative Tonie", "type": "array", "items": {"title": "Chapter", "required": ["title", "file"], "type": "object", "properties": {"id": {"title": "ID of this chapter (for existing chapters)", "type": "string", "format": "uuid"}, "title": {"title": "Human-readable name for this chapter", "type": "string", "example": "My recording on 2018-08-16", "maxLength": 128}, "file": {"title": "File identifier. For new chapters: a UUID (see POST /file on how to generate it). For existing chapters: an opaque blob(only used in case of concurrent editing by another device). Starts with \"ContentToken:\" if this chapter is from a Content Token, followed by the content token followed by \":\", followed by the 0-indexed chapter of the Content Token.", "type": "string", "example": "ContentToken:toniesong:0"}, "additionalData": {"title": "Additional generic/schema-less information about a chapter.", "type": "object", "properties": {}, "example": "{\"read-along-story-id\":\"foobar\"}"}, "seconds": {"title": "Length of this chapter in seconds", "type": "number", "readOnly": true}, "transcoding": {"title": "Is this chapter currently transcoding?", "type": "boolean", "readOnly": true}}}}, "type": {"title": "The type of the chapter. Possible values are: [\"recording\", \"file\", \"content-token\", \"tunes-item\", \"native-content\", \"cloud-recording\"]", "type": "string", "example": "recording"}}}, "AddChapter": {"required": ["title", "file"], "type": "object", "properties": {"title": {"title": "Human-readable name for this chapter", "type": "string", "example": "My recording on 2018-08-16", "maxLength": 128}, "file": {"title": "File identifier, a UUID. See POST /file on how to generate it.", "type": "string", "maxLength": 1024, "minLength": 16}, "origin": {"title": "ID describing where the file originated.", "type": "string", "helpText": "DEPRECATED: Use \"type\" instead!"}, "type": {"title": "Type of the chapter", "type": "string", "enum": ["recording", "file", "content-token", "tunes-item", "native-content", "cloud-recording"], "helpText": "This is relevant for differentiating a 'recording' from a 'file' upload for a NEW chapter. For already persisted chapters or 'content-token'/'tunes-item' chapters the type has no effect because the backend is mostly looking at the `file` attribute, but should still be sent along for consistency."}}}, "DiscPatchRequest": {"type": "object", "properties": {"lock": {"title": "Lock", "description": "If enabled: This Tonieplay disc will not be claimed into another household.", "type": "boolean"}, "gameItem": {"title": "Game item", "description": "Optional GameItem ID to switch the Game on this disc (Only available for multi-game Discs)", "type": "string", "format": "uuid"}}}, "Invitation": {"required": ["id", "email", "itype"], "type": "object", "properties": {"id": {"title": "The ID of the invitation", "type": "string", "format": "uuid", "readOnly": true}, "email": {"title": "The email address of the user to invite.", "type": "string", "format": "email", "maxLength": 254, "minLength": 1}, "itype": {"title": "The type of access rights the user will get after accepting this invitation", "type": "string", "enum": ["full", "limited"]}}}, "InvitationUpdate": {"required": ["itype"], "type": "object", "properties": {"itype": {"title": "The type of access rights the user has", "type": "string", "enum": ["full", "limited"]}}}, "Toniebox": {"type": "object", "properties": {"id": {"title": "The ID of the Toniebox, as printed on the bottom. All-uppercase, without dashes.", "type": "string", "example": "SOMTB123", "length": 8, "readOnly": true}, "macAddress": {"title": "The MAC address of the Toniebox, in the same format used in ICI", "type": "string", "example": "ABC123001234", "length": 12, "readOnly": true}, "householdId": {"title": "The ID of the household this Toniebox is in", "type": "string", "format": "uuid", "readOnly": true}, "itemId": {"title": "The Toniecloud ID of the Toniebox item", "type": "string", "example": "98-0078", "readOnly": true}, "name": {"title": "The human-readable name of the Toniebox.", "type": "string", "example": "Alice's red Toniebox", "maxLength": 50, "minLength": 1}, "imageUrl": {"title": "The URL to the image to represent this Toniebox. From a slight angle.", "type": "string", "format": "url", "example": "https://cdn.tonies.de/thumbnails/toniebox_rot.png", "readOnly": true}, "birdseyeImageUrl": {"title": "Image of the Toniebox from top-down. Not available for all Tonieboxes.", "type": "string", "format": "url", "readOnly": true}, "frontImageUrl": {"title": "Image of the Toniebox from the front (straight on). Not available for all Tonieboxes.", "type": "string", "format": "url", "readOnly": true}, "ageMode": {"title": "Configuration of the Toniebox determining for which age it is suitable.\nOnly meaningful if the Toniebox has the feature \"ageMode\".\n\"1+\": Suitable for children 12 months or older.\n\"3+\": Suitable for children 3 years or older.\nWill not be present on Tonieboxes which do not have this feature.", "type": "string"}, "bleColorId": {"title": "Index of the color used for Bluetooth pairing", "type": "integer", "readOnly": true}, "lightringBrightness": {"title": "Normal brightness of the lightring, between 0 (off) and 100(full)", "type": "integer", "maxValue": 100, "minValue": 0}, "bedtimeLightringBrightness": {"title": "Brightness of the lightring when a bedtime mode is active. Between 0 (off) and 100(full)", "type": "integer", "maxValue": 100, "minValue": 0}, "bedtimeLightringColor": {"title": "Color of the lightring when a bedtime mode is active. Lower-case RGB, like #ab5f12", "type": "string"}, "bedtimeMaxVolume": {"title": "Maximum volume of the Toniebox speakers when a bedtime mode is active. Between 1 (very quiet) and 100(loudest)", "type": "integer", "maxValue": 100, "minValue": 1}, "bedtimeMaxHeadphoneVolume": {"title": "Maximum headphone volume when a bedtime mode is active. Between 1 (very quiet) and 100(loudest)", "type": "integer", "maxValue": 100, "minValue": 1}, "skippingEnabled": {"title": "Whether the child can tap the Toniebox to jump to the next or previous chapter.\nSet to null to restore default.\nEnabled by default.\n", "type": "boolean"}, "skippingDirection": {"title": "\"right\" (default): Tap right to skip to next track. Tap left to skip to previous track.\n\"left\": Tap left to skip to next track. Tap right to skip to previous track.\nSet to null to restore default.\nNote that this is the opposite default of the similar tapDirection setting for Tonieboxes without the \"tngSettings\" feature.", "type": "string"}, "scrubbingEnabled": {"title": "Whether the child can tilt the Toniebox to fast-forward and rewind.\n Set to null to restore default.\n Off by default for ageMode \"1+\", otherwise on; but parents can override it either way.", "type": "boolean"}, "language": {"title": "The Toniebox language. Will only be available&changeable if the feature \"language\" is set on the Toniebox.\nTonieboxes without this feature still have a language, but it is set directly with a request to the Toniebox in LAN rather than via the Toniecloud.\nnull if no language is set.\nAvailable languages:\n- null: unspecified\n- \"de\": Deutsch\n- \"en\": English\n- \"en-us\": English (US)\n- \"fr\": Français", "type": "string"}, "accelerometerEnabled": {"title": "Tilting & Tapping enabled (older Tonieboxes without the \"tngSettings\" feature only)", "type": "boolean"}, "tapDirection": {"title": "(older Tonieboxes without the \"tngSettings\" feature only)\nWhat happens when the Toniebox is hit: \"left\" = hitting from the left goes to the next chapter, hitting from the right goes to previous chapter. \"right\" = hitting from the left goes to the previous chapter, hitting from the right goes to next chapter.", "type": "string", "enum": ["left", "right"]}, "maxVolume": {"title": "Maximum sound volume that the Toniebox uses with speakers, in percent", "type": "integer", "enum": [100, 75, 50, 25]}, "maxHeadphoneVolume": {"title": "Maximum sound volume that the Toniebox uses with headphones, in percent", "type": "integer", "enum": [100, 75, 50, 25]}, "ledLevel": {"description": "(older Tonieboxes without the \"tngSettings\" feature only)\nThe intensity of the Toniebox LED (the square around the Tonie). One of \"on\" (default), \"off\" (LED disabled) and \"dimmed\" (reduced brightness).", "type": "string", "enum": ["on", "off", "dimmed"]}, "timezone": {"description": "The tzdata timezone the Toniebox is using. See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for possible values.", "type": "string", "example": "Europe/Berlin"}, "ssid": {"description": "Name of the Wi-Fi network the Toniebox is creating during setup (hold both ears for some time)", "type": "string", "readOnly": true, "example": "Toniebox-ABC1"}, "features": {"description": "List of features that this Toniebox supports.\nSome stable features:\n\"iciSetupStatus\": Setup status is reported via MQTT interactions (that API is private at the moment).\n\"tngSettings\": The Toniebox supports tng-generation settings (e.g. lightringBrightness or bedtimeMaxVolume)\n\"language\": The Toniebox language can be set while the Toniebox is running (rather than only with a new setup).\n\"automaticFreshnessCheck\": The Toniebox gets notified automatically for updates to Creative Tonies, and does not require a user gesture to get notified about the changed content.\n\"bluetoothHeadphones\": The Toniebox can be paired with Bluetooth headphones.\n\"bluetoothHeadphoneSettings\": headphone volume settings are supported for Bluetooth headphones.", "type": "array", "items": {"type": "string"}, "readOnly": true}, "firmwareVersion": {"description": "Latest firmware version of the Toniebox, if any. Might not be available for all Tonieboxes.", "type": "string", "readOnly": true}, "onlineState": {"description": "Whether the Toniebox is currently online.\n\"connected\": Toniebox is online.\n\"offline\": Toniebox is not connected to Toniecloud.\n\"unknown\": Connection tracking temporarily unavailable.\n\"unsupported\": This Toniebox does not support online status tracking.\n The features property will not include \"onlineState\" in this case.", "type": "string", "readOnly": true, "deprecated": true}, "offlineMode": {"description": "Whether the Toniebox is currently in Offline Mode. In Offline Mode, the Toniebox does not contact the Internet.", "type": "boolean", "readOnly": true}, "registeredAt": {"description": "When this Toniebox was last added to the current household / set up. Formatted as ISO 8601. Not available before November 2025, so may be null.", "type": "string", "format": "date-time", "readOnly": true}, "settingsApplied": {"description": "Whether the Toniebox got the latest settings update.", "type": "boolean", "readOnly": true}, "reset": {"description": "Set to true to reset all Toniebox settings (except name & language) to factory defaults, but keep the Toniebox in this household. (Use DELETE /v2/households/{householdId}/tonieboxes/{tonieboxId} to reset and remove from the household.)", "type": "boolean", "writeOnly": true}, "generation": {"description": "Toniebox generation. One of \"classic\", \"rosered\", or \"tng\".", "type": "boolean", "readOnly": true}, "product": {"description": "Toniebox product type. For example \"tbl\" or \"tb2\"", "type": "boolean", "readOnly": true}}}, "NotificationPreferences": {"type": "object", "properties": {"isDefault": {"title": "Is default", "type": "boolean", "readOnly": true}, "household": {"title": "Household", "type": "boolean"}, "offerSales": {"title": "Offer sales", "type": "boolean"}, "appUpdates": {"title": "App updates", "type": "boolean"}, "yourOrders": {"title": "Your orders", "type": "boolean"}}}, "User": {"required": ["email"], "type": "object", "properties": {"uuid": {"title": "Unique ID of the user", "type": "string", "format": "uuid", "readOnly": true}, "email": {"title": "email address and primary key of the user", "type": "string", "format": "email", "maxLength": 254, "readOnly": true}, "locale": {"title": "Language of the user in POSIX format, either in the form xx or xx_YY.", "type": "string", "enum": ["de", "en", "en_US", "fr"], "maxLength": 5, "minLength": 2}, "unicodeLocale": {"title": "Language of the user in Unicode format, either in the form xx or xx-YY.", "type": "string", "enum": ["de", "en", "en-US", "fr"], "maxLength": 5, "minLength": 2}, "country": {"title": "Home country of the user as ISO 3166 alpha 2. If the user is travelling/vacationing etc., this will be different than the GeoIP-determined country. Changed in SSO, will be synchronized automatically.", "type": "string", "maxLength": 2, "minLength": 2}, "region": {"title": "Region of the user's country as per user preferences. Use flags.contentRegion to find out what region to present content in.\n`dach` (Germany, Austria, Switzerland)\n`usa` (USA)\n`can` (Canada)\n`fra` (France & Territories)\n`uki` (UK & Ireland)\n`eur` (Rest of Europe: Poland, Spain, Benelux, Italy etc.)\n`hkg` (Hong Kong & Macao)\n`aus` (Australia)\n`nzl` (New Zealand)\n`chn` (Mainland China)\n`row` (Rest of World. This is usually handled like the `uki` region)", "type": "string", "enum": ["aus", "can", "chn", "dach", "eur", "fra", "hkg", "nzl", "row", "uki", "usa"], "readOnly": true}, "firstName": {"title": "The user's first name (used when addressing the user)", "type": "string", "maxLength": 255}, "lastName": {"title": "Last name (used when interacting with other users via a household)", "type": "string", "maxLength": 255}, "sex": {"title": "Deprecated. Do not use.", "type": "string", "enum": ["m", "f"]}, "acceptedTermsOfUse": {"title": "Deprecated: This always returns True.", "type": "boolean"}, "tracking": {"title": "Whether the user has opted out or not of tracking. We don't use this field, but maybe marketing does.", "type": "boolean", "default": true}, "authCode": {"title": "4 or 5 character authentication code, used by our support to identify and authenticate users", "type": "string", "maxLength": 5, "minLength": 4, "readonly": true}, "profileImage": {"title": "Profile image file name", "type": "string", "enum": ["baer.svg", "elefant.svg", "erdmaennchen.svg", "eule.svg", "hund.svg", "igel.svg", "katze.svg", "maus.svg", "pinguin.svg", "schildkroete.svg"]}, "isVerified": {"title": "Deprecated. Do not use.", "type": "boolean", "readOnly": true}, "daysRemaining": {"title": "Deprecated. Do not use.", "type": "integer", "readOnly": true}, "notificationCount": {"title": "Number of unread notifications.", "type": "integer", "readOnly": true}, "isEduUser": {"title": "Education user, gets special treatment in the interface", "type": "boolean", "readOnly": true}, "isBetaTester": {"title": "User gets early access to special features", "type": "boolean", "readOnly": true}, "requiresVerificationToUpload": {"title": "Deprecated. Do not use.", "type": "boolean", "readOnly": true}, "canBuyTunes": {"title": "Deprecated. Use flags.canBuyTunes", "type": "boolean", "readOnly": true}, "ownsTunes": {"title": "Whether the user has bought any Tunes so far, i.e. whether to show the \"My Collection\" tab of the audio library even if canBuyTunes is false.", "type": "boolean", "readOnly": true}, "anyPublicContentTokens": {"title": "Whether public Content Tokens are available in the given region. Public Content Tokens can be queried via GraphQL, {contentTokens(selection:\"public\") {...}} .", "type": "boolean", "readOnly": true}, "creativeTonieShopUrl": {"title": "URL where this user (depending on their country settings) can buy Creative Tonies.", "type": "string", "readOnly": true}, "notificationPreferences": {"title": "Which mobile notifications the user opted in to.", "type": "object", "properties": {"household": {"description": "Toniecloud notifications like \"Creative Tonie too long\" or \"Toniebox battery running low\".", "type": "boolean"}, "offerSales": {"description": "Advertisements, like \"Get 10% off if you buy within the next 24 hours\".", "type": "boolean"}, "appUpdates": {"description": "Information about new app features.", "type": "boolean"}, "yourOrders": {"description": "Your orders in the Tonie shop, like \"Your order has been shipped.", "type": "boolean"}, "isDefault": {"description": "Whether the current setting is the default, i.e. the user did not make a choice yet", "type": "boolean"}}}, "personalization": {"title": "Whether the user has finished the personalization process (e.g. setting up children etc.).\n \"unseen\": The user has never seen the process (default).\n \"done\": The user has completed the process.\n \"ignored\": The user has left the process.", "type": "string", "choices": ["unseen", "done", "ignored"]}}}, "Notification": {"type": "object", "properties": {"id": {"title": "The ID of the Notification.", "type": "string", "format": "uuid", "readOnly": true}, "text": {"title": "The text of the notification, in the current user's locale if possible. (Legacy notifications were stored as text, and thus may be in a different locale.)", "type": "string", "readOnly": true}, "read": {"title": "Whether this notification has been read (true=read false=unread).", "type": "boolean"}, "timestamp": {"title": "The time when the notification was sent.", "type": "string", "readOnly": true}, "ntype": {"title": "The type of the notification.", "type": "string", "choice": ["text", "invitationCreated", "invitationAccepted", "tonieError"], "readOnly": true}, "invitationToken": {"title": "(Only if ntype is \"invitationCreated\" and the invitation is still valid): Token to accept an invitation, for a button \"accept invitation\"", "type": "string", "format": "uuid", "readOnly": true}, "householdId": {"title": "(Only if ntype is \"invitationAccepted\" and the membership still exists and the user is limited): householdId of the membership (for a button \"Configure permissions\")", "type": "string", "format": "uuid", "readOnly": true}, "membershipId": {"title": "(Only if ntype is \"invitationAccepted\" and the membership still exists and the user is limited): id of the membership (for a button \"Configure permissions\")", "type": "string", "format": "uuid", "readOnly": true}, "tonieId": {"title": "(Only if ntype is \"tonieError\"): Id of the Creative Tonie that failed to transcode", "type": "string", "format": "uuid"}, "tonieReason": {"title": "(Only if ntype is \"tonieError\"): Reason why the transcoding failed", "type": "string", "enum": ["wrongFormat", "tooLong", "unknownError"]}}}, "SystemNotification": {"type": "object", "properties": {"id": {"title": "The ID of the Notification.", "type": "string", "readOnly": true}, "translatedText": {"title": "The notification message, translated into the user's language. May include HTML.", "type": "string", "example": "It's holiday time! You can buy Tonies <a href=\"https://tonies.com/shop/\">in our shop</a>."}}}}}