{
  "openapi": "3.1.0",
  "info": {
    "title": "Beezifi Slides API",
    "version": "1.0.0",
    "description": "Create, edit, present and export presentations. Every change goes through the same command engine as the editor, so people with a deck open see API edits live.",
    "contact": {
      "email": "support@beezifi.com"
    }
  },
  "servers": [
    {
      "url": "/api"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "tags": [
    {
      "name": "Auth",
      "description": "Sign in and manage personal access tokens (`bzs_…`)."
    },
    {
      "name": "Presentations",
      "description": "List, create, import, rename, copy and delete decks."
    },
    {
      "name": "Content",
      "description": "Read slides and change them with commands or Markdown outlines."
    },
    {
      "name": "Export",
      "description": "Download as `.pptx`, a self-contained web page, Markdown, text or JSON."
    },
    {
      "name": "Sharing",
      "description": "Invite people as viewers or editors."
    },
    {
      "name": "History",
      "description": "Versions and the activity log."
    },
    {
      "name": "Reference",
      "description": "Command list and accepted option names. No authentication needed."
    }
  ],
  "paths": {
    "/auth/login": {
      "post": {
        "tags": [
          "Auth"
        ],
        "operationId": "login",
        "summary": "Sign in",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Session"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/auth/register": {
      "post": {
        "tags": [
          "Auth"
        ],
        "operationId": "register",
        "summary": "Create an account",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "password"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string",
                    "description": "At least 8 characters."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Session"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/auth/me": {
      "get": {
        "tags": [
          "Auth"
        ],
        "operationId": "me",
        "summary": "The signed-in user",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "$ref": "#/components/schemas/User"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/auth/tokens": {
      "get": {
        "tags": [
          "Auth"
        ],
        "operationId": "listTokens",
        "summary": "List access tokens",
        "description": "Needs a session sign-in, not an access token.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Auth"
        ],
        "operationId": "createToken",
        "summary": "Create an access token",
        "description": "Returns the token once. Needs a session sign-in.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "expiresInDays": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    },
                    "prefix": {
                      "type": "string"
                    },
                    "token": {
                      "type": "string",
                      "example": "bzs_…"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations": {
      "get": {
        "tags": [
          "Presentations"
        ],
        "operationId": "listPresentations",
        "summary": "List presentations",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "presentations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PresentationRow"
                      }
                    },
                    "samples": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "themes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Presentations"
        ],
        "operationId": "createPresentation",
        "summary": "Create a presentation",
        "description": "Blank, from a template (`sample`), or from a Markdown outline (`outline`).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "theme": {
                    "type": "string",
                    "enum": [
                      "Beezifi",
                      "Office",
                      "Harbor",
                      "Ember",
                      "Meadow",
                      "Nocturne",
                      "Paper",
                      "Coral",
                      "Slate",
                      "Midnight"
                    ]
                  },
                  "sample": {
                    "type": "string",
                    "enum": [
                      "aurora",
                      "pitch",
                      "qbr",
                      "onboarding"
                    ]
                  },
                  "outline": {
                    "type": "string",
                    "description": "`# Title`, `## Slide`, `- bullet`, `| table |`, `> notes`."
                  }
                }
              },
              "examples": {
                "example": {
                  "value": {
                    "title": "Launch plan",
                    "theme": "Harbor",
                    "outline": "## Why now\n- Customers asked for it"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "title": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/import": {
      "post": {
        "tags": [
          "Presentations"
        ],
        "operationId": "importPresentation",
        "summary": "Import a file",
        "description": "`.pptx`, `.md`, `.txt` or `.json`. The response lists anything that could not be imported.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "title": {
                      "type": "string"
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "tags": [
          "Presentations"
        ],
        "operationId": "getPresentation",
        "summary": "Get the full presentation JSON",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "role": {
                      "type": "string"
                    },
                    "snapshot": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "tags": [
          "Presentations"
        ],
        "operationId": "renamePresentation",
        "summary": "Rename",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "title": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "tags": [
          "Presentations"
        ],
        "operationId": "deletePresentation",
        "summary": "Delete (owner) or leave (shared)",
        "description": "Owners move the deck to the trash; it is erased after 30 days.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}/duplicate": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "tags": [
          "Presentations"
        ],
        "operationId": "duplicatePresentation",
        "summary": "Make a copy",
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}/summary": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "tags": [
          "Content"
        ],
        "operationId": "getSummary",
        "summary": "Slides, shape ids and text",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Summary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}/slides/{slide}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        {
          "name": "slide",
          "in": "path",
          "required": true,
          "description": "Slide id or 0-based index.",
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "media",
          "in": "query",
          "description": "`1` to include pictures as data URLs.",
          "schema": {
            "type": "integer",
            "enum": [
              0,
              1
            ]
          }
        }
      ],
      "get": {
        "tags": [
          "Content"
        ],
        "operationId": "getSlide",
        "summary": "One slide in full",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}/commands": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "tags": [
          "Content"
        ],
        "operationId": "runCommands",
        "summary": "Run commands",
        "description": "Runs up to 500 commands in order. Each result says whether it worked; a failed command does not undo earlier ones.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "commands"
                ],
                "properties": {
                  "commands": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/Command"
                    }
                  }
                }
              },
              "examples": {
                "example": {
                  "value": {
                    "commands": [
                      {
                        "id": "slide.new",
                        "params": {
                          "layout": "titleAndContent",
                          "title": "Next steps",
                          "body": "Ship the beta\nCollect feedback"
                        }
                      },
                      {
                        "id": "transition.set",
                        "params": {
                          "all": true,
                          "kind": "fade"
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ok": {
                            "type": "boolean"
                          },
                          "seq": {
                            "type": "integer"
                          },
                          "result": {
                            "type": "object"
                          },
                          "error": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}/outline": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "tags": [
          "Content"
        ],
        "operationId": "addOutline",
        "summary": "Add slides from Markdown",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "markdown"
                ],
                "properties": {
                  "markdown": {
                    "type": "string"
                  },
                  "at": {
                    "type": "integer",
                    "description": "0-based position; default is the end."
                  }
                }
              },
              "examples": {
                "example": {
                  "value": {
                    "markdown": "## Results\n- Revenue up 18%\n- 37 new customers\n\n> Pause for questions."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slides": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}/export": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        {
          "name": "format",
          "in": "query",
          "required": true,
          "schema": {
            "type": "string",
            "enum": [
              "pptx",
              "html",
              "md",
              "txt",
              "json"
            ],
            "default": "pptx"
          },
          "example": "pptx"
        }
      ],
      "get": {
        "tags": [
          "Export"
        ],
        "operationId": "exportPresentation",
        "summary": "Download",
        "responses": {
          "200": {
            "description": "The file. `X-Export-Warnings` lists anything left out."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}/shares": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "tags": [
          "Sharing"
        ],
        "operationId": "listShares",
        "summary": "Who has access",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "Sharing"
        ],
        "operationId": "share",
        "summary": "Share with someone (owner only)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "viewer",
                      "editor"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}/shares/{userId}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        {
          "name": "userId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "integer"
          }
        }
      ],
      "delete": {
        "tags": [
          "Sharing"
        ],
        "operationId": "unshare",
        "summary": "Remove access (owner only)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}/versions": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "tags": [
          "History"
        ],
        "operationId": "listVersions",
        "summary": "List versions",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "History"
        ],
        "operationId": "saveVersion",
        "summary": "Save a named version",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}/versions/{versionId}/restore": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        {
          "name": "versionId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "integer"
          }
        }
      ],
      "post": {
        "tags": [
          "History"
        ],
        "operationId": "restoreVersion",
        "summary": "Restore a version",
        "description": "Saves the current state as a version first. Everyone with the deck open reloads.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/presentations/{id}/activity": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Presentation id (a UUID).",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "tags": [
          "History"
        ],
        "operationId": "getActivity",
        "summary": "Recent changes",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/commands": {
      "get": {
        "tags": [
          "Reference"
        ],
        "operationId": "listCommands",
        "summary": "Every command and its parameters",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/options": {
      "get": {
        "tags": [
          "Reference"
        ],
        "operationId": "listOptions",
        "summary": "Layouts, themes, shapes, transitions, effects, table styles, chart types",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "A personal access token (`bzs_…`) or a session token from /auth/login."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid input",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "…",
              "code": "invalid_request",
              "requestId": "…"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid token",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "…",
              "code": "unauthorized",
              "requestId": "…"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Not allowed for your role",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "…",
              "code": "forbidden",
              "requestId": "…"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such presentation, or no access",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "…",
              "code": "not_found",
              "requestId": "…"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "…",
              "code": "rate_limited",
              "requestId": "…"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          }
        }
      },
      "Session": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          },
          "user": {
            "$ref": "#/components/schemas/User"
          }
        }
      },
      "PresentationRow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "editor",
              "viewer"
            ]
          },
          "owner_name": {
            "type": "string"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Command": {
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "presentation.title",
              "presentation.size",
              "slide.new",
              "slide.duplicate",
              "slide.paste",
              "slide.delete",
              "slide.move",
              "slide.layout",
              "slide.reset",
              "slide.hide",
              "slide.notes",
              "slide.background",
              "section.add",
              "section.rename",
              "section.remove",
              "section.move",
              "shape.insert",
              "textbox.insert",
              "image.insert",
              "table.insert",
              "chart.insert",
              "ink.insert",
              "shape.transform",
              "shape.props",
              "shape.delete",
              "shape.duplicate",
              "shape.paste",
              "shape.fill",
              "shape.line",
              "shape.effects",
              "shape.quickStyle",
              "shape.order",
              "shape.align",
              "shape.distribute",
              "picture.format",
              "text.set",
              "text.paras",
              "text.append",
              "text.format",
              "text.para",
              "text.box",
              "text.replaceAll",
              "table.cell",
              "table.setData",
              "table.row",
              "table.col",
              "table.style",
              "chart.update",
              "design.theme",
              "design.colors",
              "design.fonts",
              "design.decor",
              "transition.set",
              "animation.add",
              "animation.update",
              "animation.remove",
              "animation.move",
              "comment.add",
              "comment.reply",
              "comment.resolve",
              "comment.delete",
              "comment.edit",
              "footer.set"
            ]
          },
          "params": {
            "type": "object"
          }
        }
      },
      "Summary": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "size": {
            "type": "object",
            "properties": {
              "w": {
                "type": "number",
                "example": 960
              },
              "h": {
                "type": "number",
                "example": 540
              }
            }
          },
          "theme": {
            "type": "object"
          },
          "slides": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "id": {
                  "type": "string"
                },
                "layout": {
                  "type": "string",
                  "enum": [
                    "title",
                    "titleAndContent",
                    "sectionHeader",
                    "twoContent",
                    "comparison",
                    "titleOnly",
                    "blank",
                    "contentWithCaption",
                    "pictureWithCaption",
                    "titleAndVerticalText",
                    "verticalTitleAndText"
                  ]
                },
                "title": {
                  "type": "string"
                },
                "shapes": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                },
                "notes": {
                  "type": "string"
                },
                "transition": {
                  "type": "string",
                  "enum": [
                    "none",
                    "fade",
                    "push",
                    "wipe",
                    "split",
                    "reveal",
                    "cover",
                    "uncover",
                    "zoom",
                    "flip",
                    "circle",
                    "morph"
                  ]
                }
              }
            }
          }
        }
      },
      "ChartType": {
        "type": "string",
        "enum": [
          "column",
          "stackedColumn",
          "bar",
          "stackedBar",
          "line",
          "area",
          "pie",
          "doughnut",
          "scatter"
        ]
      }
    }
  }
}