{
  "openapi": "3.1.0",
  "info": {
    "title": "Mythicshot API",
    "version": "0.1.7",
    "description": "Upload, publish and manage interactive product tours. This is the API Mythicshot itself uses.\n\n## Get connected\n\nEvery request except the health check carries a token, as the header `Authorization: Bearer YOUR_TOKEN`. A token starts with \"dp_\" and is 43 characters long. It acts only inside its own workspace: another workspace's tour answers 404, the same as one that does not exist.\n\nThe first request to try answers with your workspace's name and the server's version:\n\n```\ncurl https://YOUR-SITE/api/v1/me -H \"Authorization: Bearer YOUR_TOKEN\"\n```\n\n## Errors\n\nEvery refusal is JSON with an error code and, mostly, a detail in plain words: `{\"error\":\"bad_title\",\"detail\":\"the title must not be empty\"}`. The codes are stable; the detail text may change.\n\nSome answers can come from any request and are not repeated on each one:\n\n- `401 {\"error\":\"unauthorized\"}`, with no detail: the token is missing, malformed, unknown or revoked.\n- `404 {\"error\":\"not_found\"}`, with no detail: no request has that address.\n- `421` with nothing in it: on a server with two addresses, the request was sent to another host name.\n- `500 {\"error\":\"internal\"}`: the server failed; nothing about the failure is given.\n- `500 {\"error\":\"misconfigured\"}`: on Cloudflare, the two addresses in the settings cannot be used together; every request answers this until they are fixed.\n\n## Requests that work in steps\n\nPublish, unpublish and delete may need several requests for a large tour. Each is safe to send again: send the same request until it answers 200 or 204.\n\n## Limits\n\n- 200 steps in one upload, and 20 notes on a step.\n- The manifest: 262,144 bytes.\n- A step image: 2,000,000 bytes and 4,096 pixels on a side, PNG or JPEG.\n- The logo: 200,000 bytes and 512 pixels on a side, PNG or JPEG.\n- Text, in characters after trimming: title 200, generator 100, note text 500, card title 80, card body 300, next label 24, cover title 80, cover body 200, cover button 24, button label 24, end text 200, link 500.\n- 400 steps in one published tour, and 512,000 bytes for its text (titles, notes, cards and settings together).\n- One publish request copies up to 12 images; one delete request removes up to 250 files.\n- 5 open uploads per workspace, unless the server's settings give another number.\n- An upload that is not finished is removed after 24 hours.\n- A publish that makes no progress for 15 minutes counts as abandoned.\n\nAnything over a limit is refused, never cut short."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "tags": [
    {
      "name": "Tours",
      "description": "List, rename, publish, unpublish and delete tours, and read a draft step's image."
    },
    {
      "name": "Uploads",
      "description": "Send a tour, a new chapter or a chapter's replacement: start, one request per image, finish."
    },
    {
      "name": "Workspace",
      "description": "The workspace a token belongs to."
    },
    {
      "name": "Server",
      "description": "Whether the server is up. Needs no token."
    }
  ],
  "paths": {
    "/api/v1/tours": {
      "get": {
        "tags": [
          "Tours"
        ],
        "summary": "List the workspace's tours",
        "description": "Every tour of the token's workspace, drafts and published, most recently changed first. url is the public link as a path, /t/<slug>, to put after the server address; it and published_at are null for a draft.",
        "operationId": "listTours",
        "security": [
          {
            "token": []
          }
        ],
        "responses": {
          "200": {
            "description": "The tours.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TourList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/tours/{id}": {
      "patch": {
        "tags": [
          "Tours"
        ],
        "summary": "Rename a tour",
        "description": "Changes the title only. The title follows the rule of a tour's title at upload: trimmed, 1 to 200 characters, no control or format characters. The slug and the public link stay the same. A rename shows on the public page of a published tour at once, without publishing again.",
        "operationId": "renameTour",
        "security": [
          {
            "token": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The tour's id, as the tour list and an upload's commit give it.",
            "schema": {
              "type": "string",
              "pattern": "^tour_[0-9a-f]{24}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RenameBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The tour's id, and the title as saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Renamed"
                }
              }
            }
          },
          "400": {
            "description": "bad_request: the body is not a JSON object. bad_title: the title breaks the rule; the detail says how.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "bad_request",
                        "bad_title"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such tour in this workspace: unknown, another workspace's, or already deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "not_found"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "413": {
            "description": "The request body is too long.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_large"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Tours"
        ],
        "summary": "Delete a tour, in steps",
        "description": "Removes the tour, its chapters and steps, its draft images and logo, its published images and any unfinished upload into it. This cannot be undone. A large tour takes several requests, each removing up to 250 files: send the same request until it answers 200. From the first request on, the tour is gone from the list and its public page answers 404; the later requests only remove files. A repeated request after the tour is gone answers 404, so treat 404 as \"gone\". Delete does not stop a publish in progress: let it finish, or unpublish the tour, then delete.",
        "operationId": "deleteTour",
        "security": [
          {
            "token": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The tour's id, as the tour list and an upload's commit give it.",
            "schema": {
              "type": "string",
              "pattern": "^tour_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Nothing of the tour is left.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Deleted"
                }
              }
            }
          },
          "202": {
            "description": "The tour is deleted; files remain to remove. Send the same request again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InProgress"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such tour in this workspace: unknown, another workspace's, or already deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "not_found"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "409": {
            "description": "A publish of this tour is in progress. Wait for it to finish, or unpublish the tour to stop it, then delete again.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "publish_busy"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "The tour is deleted, but some of its files could not be removed yet. Send the same request again.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "cleanup_pending"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tours/{id}/publish": {
      "post": {
        "tags": [
          "Tours"
        ],
        "summary": "Publish a tour, in steps",
        "description": "Copies the tour's draft into a public version at its link. Send it with no body to start, or to join the publish already in progress for the current draft. A small tour answers 200 at once. A large one answers 202 with a publish_id: send the request again with that id, each request copying up to 12 images, until it answers 200. Visitors see the previously published version until the last request, and a publish that did not finish never touches it. A publish works from the draft as it was when it started. A tour of more than 400 steps, or one whose text is over 512,000 bytes, answers 413 on the first request, before anything is copied. A publish with no progress for 15 minutes counts as abandoned, and the next request without a publish_id starts a new one.",
        "operationId": "publishTour",
        "security": [
          {
            "token": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The tour's id, as the tour list and an upload's commit give it.",
            "schema": {
              "type": "string",
              "pattern": "^tour_[0-9a-f]{24}$"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "description": "Empty to start; the previous answer's publish_id to continue.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublishBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The new version is live. The same answer on any repeat.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Published"
                }
              }
            }
          },
          "202": {
            "description": "Images are being copied. Send the request again with this publish_id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublishInProgress"
                }
              }
            }
          },
          "400": {
            "description": "bad_request: the body is neither empty nor a publish_id. empty_tour: a tour with no steps cannot be published.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "bad_request",
                        "empty_tour"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such tour in this workspace: unknown, another workspace's, or already deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "not_found"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "409": {
            "description": "publish_cancelled: that publish was stopped before it finished (the tour was unpublished, the publish failed or was abandoned, or a fresh start replaced it); publish again to start over. publish_busy: another publish of the tour is starting at this moment, or its draft changed while this one was starting; nothing was written, try again.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "publish_cancelled",
                        "publish_busy"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "413": {
            "description": "The tour has too many steps or too much text to publish, or the request body is too long.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_large"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "The tour could not be published. What was published before is unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "publish_failed"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tours/{id}/unpublish": {
      "post": {
        "tags": [
          "Tours"
        ],
        "summary": "Unpublish a tour",
        "description": "Takes the tour's public page and images down at once and makes the tour a draft again. A publish in progress is cancelled. Removing a large tour's public images can take more than one request: send the same request until it answers 204. Unpublishing a draft answers 204 too.",
        "operationId": "unpublishTour",
        "security": [
          {
            "token": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The tour's id, as the tour list and an upload's commit give it.",
            "schema": {
              "type": "string",
              "pattern": "^tour_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "The tour is unpublished; public images remain to remove. Send the same request again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnpublishInProgress"
                }
              }
            }
          },
          "204": {
            "description": "The tour is a draft and all its public images are gone."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such tour in this workspace: unknown, another workspace's, or already deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "not_found"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "500": {
            "description": "The tour is unpublished, but some of its public images could not be removed yet. Send the same request again.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "cleanup_pending"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tours/{id}/steps/{step_id}/image": {
      "get": {
        "tags": [
          "Tours"
        ],
        "summary": "Get a draft step's image",
        "description": "The picture of one step of the draft, as it was uploaded. The type is the one the server read from the file's own bytes at upload. Nothing may cache it but the client that asked.",
        "operationId": "getStepImage",
        "security": [
          {
            "token": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The tour's id, as the tour list and an upload's commit give it.",
            "schema": {
              "type": "string",
              "pattern": "^tour_[0-9a-f]{24}$"
            }
          },
          {
            "name": "step_id",
            "in": "path",
            "required": true,
            "description": "The step's id.",
            "schema": {
              "type": "string",
              "pattern": "^st_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The image.",
            "headers": {
              "content-security-policy": {
                "description": "Always `default-src 'none'; sandbox`, so the picture can do nothing when opened on its own.",
                "schema": {
                  "type": "string",
                  "const": "default-src 'none'; sandbox"
                }
              },
              "cache-control": {
                "description": "Always `private, no-store`.",
                "schema": {
                  "type": "string",
                  "const": "private, no-store"
                }
              }
            },
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such step in this workspace.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "not_found"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/uploads": {
      "post": {
        "tags": [
          "Uploads"
        ],
        "summary": "Start an upload",
        "description": "Starts an upload from the tour's manifest (at most 262,144 bytes) and says where it goes: a new tour, a new chapter of a tour, or the replacement of a chapter. Then send each step's image, the logo if one is due, and finish the upload; nothing changes in any tour until then. A replace changes the draft only: the public page stays as it was until the tour is published again. A workspace may have 5 open uploads at a time (the server's settings can give another number), and an upload that is not finished is removed after 24 hours. A repeated request only makes another upload.",
        "operationId": "createUpload",
        "security": [
          {
            "token": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UploadCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The upload exists. For the target replace the answer also has have and settings.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/UploadCreated"
                    },
                    {
                      "$ref": "#/components/schemas/ReplaceCreated"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "bad_request: the body is not a JSON object, or sha256 is not one 64-character lowercase hex text per step, or comes with another target than replace. bad_manifest: the manifest breaks a rule; the detail names the field. bad_target: the target is missing or its kind is not new, chapter or replace.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "bad_request",
                        "bad_manifest",
                        "bad_target"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The target's tour is not in this workspace (detail: no such tour), or the chapter is not a chapter of that tour (detail: no such chapter).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "not_found"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "413": {
            "description": "The request body is too long.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_large"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "429": {
            "description": "The workspace already has its number of open uploads. Finish or cancel one first.",
            "headers": {
              "retry-after": {
                "description": "Seconds to wait before trying again.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_many_uploads"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/uploads/{id}/steps/{n}": {
      "put": {
        "tags": [
          "Uploads"
        ],
        "summary": "Send one step's image",
        "description": "The body is the image itself, a PNG or a JPEG of at most 2,000,000 bytes and 4,096 pixels on a side. Its type, width, height and length must be exactly what the manifest gives for the step; the server reads them from the file's own bytes, not from the Content-Type. Steps may be sent in any order, each once.",
        "operationId": "putStepImage",
        "security": [
          {
            "token": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The upload's id, from the answer that started it.",
            "schema": {
              "type": "string",
              "pattern": "^up_[0-9a-f]{24}$"
            }
          },
          {
            "name": "n",
            "in": "path",
            "required": true,
            "description": "The step's number in the manifest, counted from 1.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "The image is stored."
          },
          "400": {
            "description": "The body is not the image the manifest describes; the detail says what differs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "bad_image"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such upload in this workspace: unknown, another workspace's, finished or cancelled, or the manifest has no step of that number.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "not_found"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "409": {
            "description": "This step was already sent, or the chapter already has its image (a step listed in have).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "already_sent"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "413": {
            "description": "The image is too long.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_large"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/uploads/{id}/logo": {
      "put": {
        "tags": [
          "Uploads"
        ],
        "summary": "Send the logo",
        "description": "The body is the cover's logo, a PNG or a JPEG (as the manifest's cover names it) of at most 200,000 bytes and 512 pixels on a side. Only an upload that makes a new tour, or replaces a tour's first chapter, takes a logo; a tour keeps its logo otherwise.",
        "operationId": "putLogo",
        "security": [
          {
            "token": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The upload's id, from the answer that started it.",
            "schema": {
              "type": "string",
              "pattern": "^up_[0-9a-f]{24}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "The logo is stored."
          },
          "400": {
            "description": "The body is not a logo of the type the manifest names, or is too large on a side.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "bad_image"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such upload in this workspace: unknown, another workspace's, finished or cancelled, or its manifest names no logo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "not_found"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "409": {
            "description": "logo_not_used: this upload goes into an existing tour, which keeps its logo; do not send one. already_sent: the logo was already sent.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "logo_not_used",
                        "already_sent"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "413": {
            "description": "The logo is too long.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "too_large"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/uploads/{id}/commit": {
      "post": {
        "tags": [
          "Uploads"
        ],
        "summary": "Finish an upload",
        "description": "Puts the upload into the draft in one go: a new tour, a new chapter, or the chapter with exactly the manifest's steps. Nothing is public until the tour is published. A repeated request answers 201 with the same ids. For a replace the answer's publish says what publishing would do now: draft, ready or other_changes.",
        "operationId": "commitUpload",
        "security": [
          {
            "token": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The upload's id, from the answer that started it.",
            "schema": {
              "type": "string",
              "pattern": "^up_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "The draft holds the upload. For the target replace the answer also has publish.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Committed"
                    },
                    {
                      "$ref": "#/components/schemas/ReplaceCommitted"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "No such upload in this workspace: unknown, another workspace's, finished or cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "not_found"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "409": {
            "description": "incomplete: a step's image, or a logo the upload must carry, has not been sent; nothing changes. chapter_changed: another upload replaced the chapter since this one started; nothing changes: cancel this upload and start again.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "incomplete",
                        "chapter_changed"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/uploads/{id}": {
      "delete": {
        "tags": [
          "Uploads"
        ],
        "summary": "Cancel an upload",
        "description": "Removes the upload and only what it stored, never an image a chapter uses. It answers 204 also for an upload that is unknown, finished or already cancelled.",
        "operationId": "cancelUpload",
        "security": [
          {
            "token": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The upload's id, from the answer that started it.",
            "schema": {
              "type": "string",
              "pattern": "^up_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "The upload is gone, or was not there."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/me": {
      "get": {
        "tags": [
          "Workspace"
        ],
        "summary": "The workspace and the server version",
        "description": "The name of the token's workspace and the version of the server: the request to test a connection with. On a server with two addresses the answer also has addresses, the two host names.",
        "operationId": "getMe",
        "security": [
          {
            "token": []
          }
        ],
        "responses": {
          "200": {
            "description": "The workspace and the version.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "The token's workspace no longer exists.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "detail"
                  ],
                  "properties": {
                    "error": {
                      "type": "string",
                      "enum": [
                        "not_found"
                      ]
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "tags": [
          "Server"
        ],
        "summary": "Whether the server is up",
        "description": "Answers 200 when the server runs and reaches its database. It needs no token and answers on every host name. On a server with two addresses, asked on one of them, it also says which of the two it was reached on.",
        "operationId": "getHealth",
        "security": [],
        "responses": {
          "200": {
            "description": "The server is up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "token": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "The shape of every refusal. Each request lists the codes it can answer.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "A stable code, such as not_found."
          },
          "detail": {
            "type": "string",
            "description": "The reason in plain words. The text may change; do not match on it."
          }
        },
        "additionalProperties": false
      },
      "Unauthorized": {
        "type": "object",
        "description": "The one answer for a missing, malformed, unknown or revoked token.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "const": "unauthorized"
          }
        },
        "additionalProperties": false
      },
      "InProgress": {
        "type": "object",
        "description": "A delete that has more to do. Send the same request again.",
        "required": [
          "status",
          "done",
          "total"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "in_progress"
          },
          "done": {
            "type": "integer",
            "minimum": 0,
            "description": "Files removed so far."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Files to remove in all."
          }
        },
        "additionalProperties": false
      },
      "PublishInProgress": {
        "type": "object",
        "description": "A publish that has more images to copy.",
        "required": [
          "status",
          "publish_id",
          "done",
          "total"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "in_progress"
          },
          "publish_id": {
            "type": "string",
            "pattern": "^pub_[0-9a-f]{24}$",
            "description": "Send it back in the next publish request to continue this publish."
          },
          "done": {
            "type": "integer",
            "minimum": 0,
            "description": "Images copied so far."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Images to copy in all."
          }
        },
        "additionalProperties": false
      },
      "UnpublishInProgress": {
        "type": "object",
        "description": "The tour is unpublished, but some of its public images are still to be removed. Send the same request again.",
        "required": [
          "status",
          "detail"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "in_progress"
          },
          "detail": {
            "type": "string",
            "description": "What is left to do, in plain words."
          }
        },
        "additionalProperties": false
      },
      "Tour": {
        "type": "object",
        "required": [
          "id",
          "title",
          "status",
          "slug",
          "url",
          "chapters",
          "steps",
          "updated_at",
          "published_at",
          "unpublished_changes"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^tour_[0-9a-f]{24}$"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published"
            ]
          },
          "slug": {
            "type": "string",
            "description": "The last part of the public link. It never changes, also not on a rename."
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "The public link as a path, /t/<slug>, to put after the server address. null for a draft."
          },
          "chapters": {
            "type": "integer",
            "minimum": 0,
            "description": "How many chapters the draft has."
          },
          "steps": {
            "type": "integer",
            "minimum": 0,
            "description": "How many steps the draft has."
          },
          "updated_at": {
            "type": "integer",
            "minimum": 0,
            "description": "When the draft last changed, in milliseconds since 1970."
          },
          "published_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "When the tour was last published, in milliseconds since 1970. null for a draft."
          },
          "unpublished_changes": {
            "type": "boolean",
            "description": "true when the tour is published and its draft holds a chapter upload or update that is not on the public page yet, so publishing it again would change what visitors see; also when the server cannot tell, which happens only for some tours last published before version 0.1.4. false for a draft, and for a published tour whose page is up to date. A rename is live at once and never sets it."
          }
        },
        "additionalProperties": false
      },
      "TourList": {
        "type": "object",
        "required": [
          "tours"
        ],
        "properties": {
          "tours": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tour"
            },
            "description": "Most recently changed first."
          }
        },
        "additionalProperties": false
      },
      "RenameBody": {
        "type": "object",
        "required": [
          "title"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "The new title: trimmed, no control or format characters."
          }
        }
      },
      "Renamed": {
        "type": "object",
        "required": [
          "id",
          "title"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "description": "The title as saved (trimmed)."
          }
        },
        "additionalProperties": false
      },
      "Deleted": {
        "type": "object",
        "description": "Nothing of the tour is left.",
        "required": [
          "deleted"
        ],
        "properties": {
          "deleted": {
            "type": "boolean",
            "const": true
          }
        },
        "additionalProperties": false
      },
      "PublishBody": {
        "type": "object",
        "required": [],
        "properties": {
          "publish_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^pub_[0-9a-f]{24}$",
            "description": "The publish_id of the previous answer, to continue that publish."
          }
        }
      },
      "Published": {
        "type": "object",
        "description": "The new version is live.",
        "required": [
          "slug",
          "url",
          "steps"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "The tour's link as a path, /t/<slug>, to put after the server address."
          },
          "steps": {
            "type": "integer",
            "minimum": 0,
            "description": "How many steps the published version has."
          }
        },
        "additionalProperties": false
      },
      "Me": {
        "type": "object",
        "required": [
          "workspace",
          "version"
        ],
        "properties": {
          "workspace": {
            "type": "string",
            "description": "The workspace's name."
          },
          "version": {
            "type": "string",
            "description": "The server's version."
          },
          "addresses": {
            "type": "object",
            "description": "Only on a server with two addresses: both host names, without a scheme. Absent means: use the address you were given.",
            "required": [
              "tours",
              "app"
            ],
            "properties": {
              "tours": {
                "type": "string",
                "description": "The host name tour links use."
              },
              "app": {
                "type": "string",
                "description": "The host name of the app address."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "Health": {
        "type": "object",
        "required": [
          "ok"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "address": {
            "type": "string",
            "enum": [
              "tours",
              "app"
            ],
            "description": "Only on a server with two addresses, when asked on one of them: which of the two this request reached."
          }
        },
        "additionalProperties": false
      },
      "UploadTarget": {
        "description": "Where the upload goes.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/TargetNew"
          },
          {
            "$ref": "#/components/schemas/TargetChapter"
          },
          {
            "$ref": "#/components/schemas/TargetReplace"
          }
        ]
      },
      "TargetNew": {
        "type": "object",
        "description": "A new tour, made of this one chapter.",
        "required": [
          "kind"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "const": "new"
          }
        }
      },
      "TargetChapter": {
        "type": "object",
        "description": "A new chapter at the end of an existing tour. The tour keeps its settings and logo.",
        "required": [
          "kind",
          "tour_id"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "const": "chapter"
          },
          "tour_id": {
            "type": "string",
            "pattern": "^tour_[0-9a-f]{24}$"
          }
        }
      },
      "TargetReplace": {
        "type": "object",
        "description": "Replaces one chapter of an existing tour. The chapter keeps its id, title and position and gets exactly the manifest's steps.",
        "required": [
          "kind",
          "tour_id",
          "chapter_id"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "const": "replace"
          },
          "tour_id": {
            "type": "string",
            "pattern": "^tour_[0-9a-f]{24}$"
          },
          "chapter_id": {
            "type": "string",
            "pattern": "^ch_[0-9a-f]{24}$"
          }
        }
      },
      "UploadCreate": {
        "type": "object",
        "required": [
          "manifest",
          "target"
        ],
        "properties": {
          "manifest": {
            "$ref": "#/components/schemas/Manifest"
          },
          "target": {
            "$ref": "#/components/schemas/UploadTarget"
          },
          "sha256": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            },
            "description": "Only with the target replace, and optional: one SHA-256 per step of the manifest, in order, of the image the client would send. The answer's have then lists the steps not to send."
          }
        }
      },
      "UploadCreated": {
        "type": "object",
        "description": "The answer for the targets new and chapter.",
        "required": [
          "upload_id",
          "steps"
        ],
        "properties": {
          "upload_id": {
            "type": "string",
            "pattern": "^up_[0-9a-f]{24}$"
          },
          "steps": {
            "type": "integer",
            "minimum": 1,
            "description": "How many step images the upload expects."
          }
        },
        "additionalProperties": false
      },
      "ReplaceCreated": {
        "type": "object",
        "description": "The answer for the target replace.",
        "required": [
          "upload_id",
          "steps",
          "have",
          "settings"
        ],
        "properties": {
          "upload_id": {
            "type": "string",
            "pattern": "^up_[0-9a-f]{24}$"
          },
          "steps": {
            "type": "integer",
            "minimum": 1,
            "description": "How many steps the manifest has."
          },
          "have": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1
            },
            "description": "The step numbers whose image the chapter already has; do not send them. Empty without sha256."
          },
          "settings": {
            "type": "boolean",
            "description": "true when the chapter is the tour's first: the commit then also replaces the tour's settings and logo with the manifest's."
          }
        },
        "additionalProperties": false
      },
      "Committed": {
        "type": "object",
        "description": "The answer for the targets new and chapter.",
        "required": [
          "tour_id",
          "chapter_id",
          "steps"
        ],
        "properties": {
          "tour_id": {
            "type": "string",
            "pattern": "^tour_[0-9a-f]{24}$"
          },
          "chapter_id": {
            "type": "string",
            "pattern": "^ch_[0-9a-f]{24}$"
          },
          "steps": {
            "type": "integer",
            "minimum": 0,
            "description": "How many steps the chapter has."
          }
        },
        "additionalProperties": false
      },
      "ReplaceCommitted": {
        "type": "object",
        "description": "The answer for the target replace.",
        "required": [
          "tour_id",
          "chapter_id",
          "steps",
          "publish"
        ],
        "properties": {
          "tour_id": {
            "type": "string",
            "pattern": "^tour_[0-9a-f]{24}$"
          },
          "chapter_id": {
            "type": "string",
            "pattern": "^ch_[0-9a-f]{24}$"
          },
          "steps": {
            "type": "integer",
            "minimum": 0,
            "description": "How many steps the chapter has now."
          },
          "publish": {
            "type": "string",
            "enum": [
              "draft",
              "ready",
              "other_changes"
            ],
            "description": "What publishing the tour would do now. draft: the tour is not published; nothing is public and nothing needs publishing. ready: the tour is published and the only changes not public yet are replaces of this chapter; publish it to put the update live. other_changes: the tour is published and its draft holds more than replaces of this chapter that was never published; publishing would put all of it live."
          }
        },
        "additionalProperties": false
      },
      "Manifest": {
        "type": "object",
        "description": "The tour as the recorder wrote it, at most 262,144 bytes. The server checks every field: unknown fields are dropped, and anything out of range, of the wrong type or over a limit is refused with 400 bad_manifest and the field's path, never cut short. Text is trimmed and may hold no control or format characters. theme, zoom, cover, cta, end and autoplay are read from version 3 only. The full rules are in src/manifest.ts.",
        "required": [
          "version",
          "generator",
          "title",
          "steps"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "enum": [
              1,
              2,
              3
            ],
            "description": "Version 1 has steps only; version 2 adds spotlights and notes; version 3 adds cards, the cover, the button, the end card and the tour's look."
          },
          "generator": {
            "type": "string",
            "maxLength": 100,
            "description": "The program that wrote the manifest."
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "The tour's title; for a new chapter, the chapter's."
          },
          "steps": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ManifestStep"
            },
            "description": "The steps in order. No two may name the same image."
          },
          "spotlight_dim": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 10,
            "maximum": 90,
            "description": "From version 2: how dark the rest of the picture gets around a spotlight, in percent. Required when a step has a spotlight."
          },
          "theme": {
            "$ref": "#/components/schemas/Theme"
          },
          "zoom": {
            "$ref": "#/components/schemas/Zoom"
          },
          "cover": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Cover"
              },
              {
                "type": "null"
              }
            ]
          },
          "cta": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "type": "null"
              }
            ]
          },
          "end": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/EndCard"
              },
              {
                "type": "null"
              }
            ]
          },
          "autoplay": {
            "$ref": "#/components/schemas/Autoplay"
          }
        }
      },
      "ManifestStep": {
        "type": "object",
        "description": "One step: a picture, where it was clicked, and what is drawn over it. click is required; null means no click.",
        "required": [
          "image",
          "width",
          "height",
          "bytes",
          "click",
          "t_ms"
        ],
        "properties": {
          "image": {
            "type": "string",
            "pattern": "^step-[0-9]{3}\\.(png|jpg)$",
            "description": "The image's name; its ending says whether a PNG or a JPEG will be sent."
          },
          "width": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4096,
            "description": "The image's width in pixels; the image sent must have it."
          },
          "height": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4096,
            "description": "The image's height in pixels; the image sent must have it."
          },
          "bytes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2000000,
            "description": "The image's length in bytes; the image sent must have it."
          },
          "click": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Point"
              },
              {
                "type": "null"
              }
            ]
          },
          "t_ms": {
            "type": "integer",
            "minimum": 0,
            "description": "When the step was recorded, in milliseconds from the start."
          },
          "spotlight": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Box"
              },
              {
                "type": "null"
              }
            ]
          },
          "notes": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/Note"
            },
            "description": "From version 2."
          },
          "card": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Card"
              },
              {
                "type": "null"
              }
            ]
          },
          "advance": {
            "type": "string",
            "enum": [
              "hotspot",
              "anywhere"
            ],
            "description": "From version 3: whether a click on the hotspot or anywhere moves on. hotspot when absent."
          },
          "zoom": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "From version 3: this step's own zoom; null follows the tour's."
          }
        }
      },
      "Point": {
        "type": "object",
        "required": [
          "x",
          "y"
        ],
        "properties": {
          "x": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Percent of the image's width."
          },
          "y": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Percent of the image's height."
          }
        }
      },
      "Box": {
        "type": "object",
        "description": "A box in percent of the image; it must end inside the image.",
        "required": [
          "x",
          "y",
          "w",
          "h"
        ],
        "properties": {
          "x": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Percent of the width."
          },
          "y": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Percent of the height."
          },
          "w": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Above 0."
          },
          "h": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Above 0."
          }
        }
      },
      "Note": {
        "description": "A note drawn on the picture.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/TextNote"
          },
          {
            "$ref": "#/components/schemas/BubbleNote"
          }
        ]
      },
      "TextNote": {
        "type": "object",
        "required": [
          "kind",
          "x",
          "y",
          "text",
          "size",
          "color"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "const": "text"
          },
          "x": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Percent of the width."
          },
          "y": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Percent of the height."
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "May hold line feeds."
          },
          "size": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 100,
            "description": "The text size, in percent of the image's height."
          },
          "color": {
            "type": "string",
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "description": "The text colour, #rrggbb."
          }
        }
      },
      "BubbleNote": {
        "type": "object",
        "required": [
          "kind",
          "x",
          "y",
          "w",
          "h",
          "tail",
          "text",
          "size",
          "color",
          "fill"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "const": "bubble"
          },
          "x": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Percent of the width."
          },
          "y": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Percent of the height."
          },
          "w": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Above 0."
          },
          "h": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Above 0."
          },
          "tail": {
            "$ref": "#/components/schemas/Point"
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "May hold line feeds."
          },
          "size": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 100,
            "description": "The text size, in percent of the image's height."
          },
          "color": {
            "type": "string",
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "description": "The text colour, #rrggbb."
          },
          "fill": {
            "type": "string",
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "description": "The bubble's colour, #rrggbb."
          }
        }
      },
      "Card": {
        "type": "object",
        "description": "From version 3: the step's card. It needs a title or a body.",
        "required": [],
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 80,
            "description": "Empty when absent."
          },
          "body": {
            "type": "string",
            "maxLength": 300,
            "description": "May hold line feeds. Empty when absent."
          },
          "next_label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 24,
            "description": "Next when absent."
          },
          "anchor": {
            "type": "string",
            "enum": [
              "hotspot",
              "point",
              "none"
            ],
            "description": "Where the card points. hotspot (the default) needs a step with a click; point needs point."
          },
          "point": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Point"
              },
              {
                "type": "null"
              }
            ]
          },
          "placement": {
            "type": "string",
            "enum": [
              "auto",
              "top",
              "bottom",
              "left",
              "right"
            ],
            "description": "auto when absent."
          }
        }
      },
      "Link": {
        "type": "object",
        "description": "A button with a link.",
        "required": [
          "label",
          "url"
        ],
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 24,
            "description": "The button's text."
          },
          "url": {
            "type": "string",
            "maxLength": 500,
            "description": "An https link with a plain host name: no user name, no IP address, no spaces."
          }
        }
      },
      "Theme": {
        "type": "object",
        "description": "From version 3: the tour's look. Every field has a default.",
        "required": [],
        "properties": {
          "card_style": {
            "type": "string",
            "enum": [
              "dark",
              "light",
              "compact",
              "auto"
            ]
          },
          "accent": {
            "type": "string",
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "description": "#rrggbb."
          },
          "hotspot": {
            "type": "string",
            "enum": [
              "pulse",
              "dot",
              "none"
            ]
          },
          "progress_bar": {
            "type": "boolean"
          },
          "backdrop": {
            "type": "string",
            "pattern": "^(auto|#[0-9A-Fa-f]{6})$",
            "description": "auto, or a colour as #rrggbb."
          },
          "spotlight_soft": {
            "type": "boolean"
          }
        }
      },
      "Zoom": {
        "type": "object",
        "description": "From version 3: whether steps zoom in on the click, and how far.",
        "required": [],
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "percent": {
            "type": "integer",
            "minimum": 105,
            "maximum": 140
          }
        }
      },
      "Cover": {
        "type": "object",
        "description": "From version 3: the page shown before the first step.",
        "required": [
          "title"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "The cover's title."
          },
          "body": {
            "type": "string",
            "maxLength": 200,
            "description": "May hold line feeds. Empty when absent."
          },
          "button": {
            "type": "string",
            "minLength": 1,
            "maxLength": 24,
            "description": "Start when absent."
          },
          "logo": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "logo.png",
              "logo.jpg",
              null
            ],
            "description": "Names the logo this upload will send, by its type; null for none."
          }
        }
      },
      "EndCard": {
        "type": "object",
        "description": "From version 3: the card shown after the last step.",
        "required": [],
        "properties": {
          "text": {
            "type": "string",
            "maxLength": 200,
            "description": "May hold line feeds. Empty when absent."
          },
          "primary": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "type": "null"
              }
            ]
          },
          "secondary": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "type": "null"
              }
            ]
          },
          "replay": {
            "type": "boolean",
            "description": "true when absent."
          }
        }
      },
      "Autoplay": {
        "type": "object",
        "description": "From version 3: whether the tour moves on by itself, and after how long.",
        "required": [],
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "seconds": {
            "type": "integer",
            "minimum": 2,
            "maximum": 20
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The token is missing, malformed, unknown or revoked.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Unauthorized"
            }
          }
        }
      }
    }
  }
}
