Please support or provide swagger open api spec file. #4439

New Issue

Closed

opened 2026-02-05 08:53:29 +03:00 by OVERLORD · 4 comments

OVERLORD commented 2026-02-05 08:53:29 +03:00

Owner

Copy Link

Originally created by @ilbw97 on GitHub (Jan 31, 2024).

Describe the feature you'd like

I own my website using bookstack, and i also using waap service.
I want to use api protection that i use, but they require open api spec file to protect my website's api traffic.
i know you guys already provide /api/docs.json and /api/docs but it's very hard to find openapi spec file like yaml or json format.

Describe the benefits this would bring to existing BookStack users

all users that trying to protect api traffic of their website could operate their website more convenience.

Can the goal of this request already be achieved via other means?

no

Have you searched for an existing open/closed issue?

• I have searched for existing issues and none cover my fundamental request

How long have you been using BookStack?

1 to 5 years

Additional context

No response

Originally created by @ilbw97 on GitHub (Jan 31, 2024). ### Describe the feature you'd like I own my website using bookstack, and i also using waap service. I want to use api protection that i use, but they require open api spec file to protect my website's api traffic. i know you guys already provide /api/docs.json and /api/docs but it's very hard to find openapi spec file like yaml or json format. ### Describe the benefits this would bring to existing BookStack users all users that trying to protect api traffic of their website could operate their website more convenience. ### Can the goal of this request already be achieved via other means? no ### Have you searched for an existing open/closed issue? - [X] I have searched for existing issues and none cover my fundamental request ### How long have you been using BookStack? 1 to 5 years ### Additional context _No response_

OVERLORD added the 🌔 Out of scope🔨 Feature Request labels 2026-02-05 08:53:29 +03:00

OVERLORD closed this issue 2026-02-05 08:53:30 +03:00

OVERLORD commented 2026-02-05 08:53:33 +03:00

Author

Owner

Copy Link

@ssddanbrown commented on GitHub (Jan 31, 2024):

Thanks for the request @ilbw97.
Personally, I don't feel like supporting a whole specific spec will be worthwhile for the benefit of what would likely be a very minor part of our audience's usage for certain features in external software/platforms.

I did build a script to (roughly) create postman collections from the API data, you might be able to do something similar (Or import postman and export to openapi) but this kind of thing won't cover app (non-api) routes and may not cover the flexibility & options that is afforded in our API.

@ssddanbrown commented on GitHub (Jan 31, 2024): Thanks for the request @ilbw97. Personally, I don't feel like supporting a whole specific spec will be worthwhile for the benefit of what would likely be a very minor part of our audience's usage for certain features in external software/platforms. I did [build a script](https://github.com/BookStackApp/api-scripts/tree/main/node-generate-postman-collection) to (roughly) create postman collections from the API data, you might be able to do something similar (Or import postman and export to openapi) but this kind of thing won't cover app (non-api) routes and may not cover the flexibility & options that is afforded in our API.

OVERLORD commented 2026-02-05 08:53:35 +03:00

Author

Owner

Copy Link

@ilbw97 commented on GitHub (Feb 1, 2024):

Thank you for answering my request. Finally, I got it :)!

@ilbw97 commented on GitHub (Feb 1, 2024): Thank you for answering my request. Finally, I got it :)!

OVERLORD commented 2026-02-05 08:53:37 +03:00

Author

Owner

Copy Link

@ssddanbrown commented on GitHub (Feb 1, 2024):

No worries, I'll therefore close this off as out of scope.

@ssddanbrown commented on GitHub (Feb 1, 2024): No worries, I'll therefore close this off as out of scope.

OVERLORD commented 2026-02-05 08:53:41 +03:00

Author

Owner

Copy Link

@n0nag0n commented on GitHub (Aug 21, 2025):

For those curious, I took the JSON docs endpoint, fed that through AI to come up with this that is accurate as of today. Worked in an MCP server I needed.

openapi: 3.0.3
info:
  title: BookStack API
  description: API for managing books, chapters, pages, attachments, images, users, roles, imports, and other resources in BookStack.
  version: v25.02.4
servers:
  - url: https://www.example.com
    description: BookStack API server
paths:
  /api/docs:
    get:
      operationId: docs-display
      summary: Load the API documentation page
      description: Load the docs page for the API.
      responses:
        '200':
          description: Successful response
          content:
            text/html:
              schema:
                type: string
                description: HTML content of the API documentation page
  /api/docs.json:
    get:
      operationId: docs-json
      summary: Show JSON view of API docs
      description: Show a JSON view of the API docs data.
      responses:
        '200':
          description: JSON view of API documentation
          content:
            application/json:
              schema:
                type: object
                description: JSON representation of the API documentation
  /api/attachments:
    get:
      operationId: attachments-list
      summary: List attachments
      description: Get a listing of attachments visible to the user. The external property indicates whether the attachment is a simple link. A false value for the external property indicates a file upload.
      responses:
        '200':
          description: List of attachments
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Attachment'
                  total:
                    type: integer
                    example: 2
    post:
      operationId: attachments-create
      summary: Create a new attachment
      description: Create a new attachment in the system. An uploaded_to value must be provided containing an ID of the page that this upload will be related to. Either a file or a link must be provided, but not both.
      requestBody:
        content:
          multipart/form-data:
            schema:
              oneOf:
                - type: object
                  required: [name, uploaded_to, file]
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 255
                    uploaded_to:
                      type: integer
                    file:
                      type: string
                      format: binary
                      maxLength: 50000
                - type: object
                  required: [name, uploaded_to, link]
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 255
                    uploaded_to:
                      type: integer
                    link:
                      type: string
                      minLength: 1
                      maxLength: 2000
                      pattern: ^https?://
      responses:
        '201':
          description: Created attachment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attachment'
  /api/attachments/{id}:
    get:
      operationId: attachments-read
      summary: Get attachment details
      description: Get the details & content of a single attachment of the given ID. The attachment link or file content is provided via a 'content' property. For files, the content will be base64 encoded.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Attachment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attachment'
    put:
      operationId: attachments-update
      summary: Update an attachment
      description: Update the details of a single attachment. If a file is being provided, the request should be formatted as a multipart/form-data request.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              oneOf:
                - type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 255
                    uploaded_to:
                      type: integer
                    file:
                      type: string
                      format: binary
                      maxLength: 50000
                - type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 255
                    uploaded_to:
                      type: integer
                    link:
                      type: string
                      minLength: 1
                      maxLength: 2000
                      pattern: ^https?://
      responses:
        '200':
          description: Updated attachment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attachment'
    delete:
      operationId: attachments-delete
      summary: Delete an attachment
      description: Delete an attachment of the given ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Attachment deleted
  /api/books:
    get:
      operationId: books-list
      summary: List books
      description: Get a listing of books visible to the user.
      responses:
        '200':
          description: List of books
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Book'
                  total:
                    type: integer
                    example: 14
    post:
      operationId: books-create
      summary: Create a new book
      description: Create a new book in the system. The cover image can be set by sending a file via an 'image' property within a 'multipart/form-data' request. If the 'image' property is null, the book cover image will be removed.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  maxLength: 255
                description:
                  type: string
                  maxLength: 1900
                description_html:
                  type: string
                  maxLength: 2000
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                image:
                  type: string
                  format: binary
                  enum: [jpeg, png, gif, webp, avif]
                  maxLength: 50000
                default_template_id:
                  type: integer
                  nullable: true
      responses:
        '201':
          description: Created book
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
  /api/books/{id}:
    get:
      operationId: books-read
      summary: Get book details
      description: View the details of a single book. The response data will contain a 'content' property listing the chapters and pages directly within, in the same structure as seen in the BookStack interface.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Book details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
    put:
      operationId: books-update
      summary: Update a book
      description: Update the details of a single book. The cover image can be set by sending a file via an 'image' property within a 'multipart/form-data' request. If the 'image' property is null, the book cover image will be removed.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                description:
                  type: string
                  maxLength: 1900
                description_html:
                  type: string
                  maxLength: 2000
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                image:
                  type: string
                  format: binary
                  enum: [jpeg, png, gif, webp, avif]
                  maxLength: 50000
                default_template_id:
                  type: integer
                  nullable: true
      responses:
        '200':
          description: Updated book
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
    delete:
      operationId: books-delete
      summary: Delete a book
      description: Delete a single book. This will typically send the book to the recycle bin.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Book deleted
  /api/books/{id}/export/html:
    get:
      operationId: books-exportHtml
      summary: Export book as HTML
      description: Export a book as a contained HTML file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: HTML file
          content:
            text/html:
              schema:
                type: string
  /api/books/{id}/export/pdf:
    get:
      operationId: books-exportPdf
      summary: Export book as PDF
      description: Export a book as a PDF file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
  /api/books/{id}/export/plaintext:
    get:
      operationId: books-exportPlainText
      summary: Export book as plain text
      description: Export a book as a plain text file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Plain text file
          content:
            text/plain:
              schema:
                type: string
  /api/books/{id}/export/markdown:
    get:
      operationId: books-exportMarkdown
      summary: Export book as markdown
      description: Export a book as a markdown file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Markdown file
          content:
            text/markdown:
              schema:
                type: string
  /api/books/{id}/export/zip:
    get:
      operationId: books-exportZip
      summary: Export book as ZIP
      description: Export a book as a contained ZIP export file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ZIP file
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /api/chapters:
    get:
      operationId: chapters-list
      summary: List chapters
      description: Get a listing of chapters visible to the user.
      responses:
        '200':
          description: List of chapters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Chapter'
                  total:
                    type: integer
                    example: 40
    post:
      operationId: chapters-create
      summary: Create a new chapter
      description: Create a new chapter in the system.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [book_id, name]
              properties:
                book_id:
                  type: integer
                name:
                  type: string
                  maxLength: 255
                description:
                  type: string
                  maxLength: 1900
                description_html:
                  type: string
                  maxLength: 2000
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                priority:
                  type: integer
                default_template_id:
                  type: integer
                  nullable: true
      responses:
        '201':
          description: Created chapter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chapter'
  /api/chapters/{id}:
    get:
      operationId: chapters-read
      summary: Get chapter details
      description: View the details of a single chapter.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Chapter details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chapter'
    put:
      operationId: chapters-update
      summary: Update a chapter
      description: Update the details of a single chapter. Providing a 'book_id' property will move the chapter into that parent element if you have permissions to do so.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                book_id:
                  type: integer
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                description:
                  type: string
                  maxLength: 1900
                description_html:
                  type: string
                  maxLength: 2000
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                priority:
                  type: integer
                default_template_id:
                  type: integer
                  nullable: true
      responses:
        '200':
          description: Updated chapter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chapter'
    delete:
      operationId: chapters-delete
      summary: Delete a chapter
      description: Delete a chapter. This will typically send the chapter to the recycle bin.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Chapter deleted
  /api/chapters/{id}/export/html:
    get:
      operationId: chapters-exportHtml
      summary: Export chapter as HTML
      description: Export a chapter as a contained HTML file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: HTML file
          content:
            text/html:
              schema:
                type: string
  /api/chapters/{id}/export/pdf:
    get:
      operationId: chapters-exportPdf
      summary: Export chapter as PDF
      description: Export a chapter as a PDF file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
  /api/chapters/{id}/export/plaintext:
    get:
      operationId: chapters-exportPlainText
      summary: Export chapter as plain text
      description: Export a chapter as a plain text file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Plain text file
          content:
            text/plain:
              schema:
                type: string
  /api/chapters/{id}/export/markdown:
    get:
      operationId: chapters-exportMarkdown
      summary: Export chapter as markdown
      description: Export a chapter as a markdown file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Markdown file
          content:
            text/markdown:
              schema:
                type: string
  /api/chapters/{id}/export/zip:
    get:
      operationId: chapters-exportZip
      summary: Export chapter as ZIP
      description: Export a chapter as a contained ZIP file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ZIP file
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /api/pages:
    get:
      operationId: pages-list
      summary: List pages
      description: Get a listing of pages visible to the user.
      responses:
        '200':
          description: List of pages
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Page'
                  total:
                    type: integer
                    example: 322
    post:
      operationId: pages-create
      summary: Create a new page
      description: Create a new page in the system. The ID of a parent book or chapter is required to indicate where this page should be located. Any HTML content provided should be kept to a single-block depth of plain HTML elements to remain compatible with the BookStack front-end and editors. Any images included via base64 data URIs will be extracted and saved as gallery images against the page during upload.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                book_id:
                  type: integer
                chapter_id:
                  type: integer
                name:
                  type: string
                  maxLength: 255
                html:
                  type: string
                markdown:
                  type: string
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                priority:
                  type: integer
      responses:
        '201':
          description: Created page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
  /api/pages/{id}:
    get:
      operationId: pages-read
      summary: Get page details
      description: View the details of a single page. Pages will always have HTML content. They may have markdown content if the markdown editor was used to last update the page. The 'html' property is the fully rendered & escaped HTML content that BookStack would show on page view, with page includes handled. The 'raw_html' property is the direct database stored HTML content, which would be what BookStack shows on page edit.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Page details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
    put:
      operationId: pages-update
      summary: Update a page
      description: Update the details of a single page. Providing a 'book_id' or 'chapter_id' property will move the page into that parent element if you have permissions to do so.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                book_id:
                  type: integer
                chapter_id:
                  type: integer
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                html:
                  type: string
                markdown:
                  type: string
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                priority:
                  type: integer
      responses:
        '200':
          description: Updated page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
    delete:
      operationId: pages-delete
      summary: Delete a page
      description: Delete a page. This will typically send the page to the recycle bin.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Page deleted
  /api/pages/{id}/export/html:
    get:
      operationId: pages-exportHtml
      summary: Export page as HTML
      description: Export a page as a contained HTML file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: HTML file
          content:
            text/html:
              schema:
                type: string
  /api/pages/{id}/export/pdf:
    get:
      operationId: pages-exportPdf
      summary: Export page as PDF
      description: Export a page as a PDF file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
  /api/pages/{id}/export/plaintext:
    get:
      operationId: pages-exportPlainText
      summary: Export page as plain text
      description: Export a page as a plain text file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Plain text file
          content:
            text/plain:
              schema:
                type: string
  /api/pages/{id}/export/markdown:
    get:
      operationId: pages-exportMarkdown
      summary: Export page as markdown
      description: Export a page as a markdown file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Markdown file
          content:
            text/markdown:
              schema:
                type: string
  /api/pages/{id}/export/zip:
    get:
      operationId: pages-exportZip
      summary: Export page as ZIP
      description: Export a page as a contained ZIP file.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ZIP file
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /api/image-gallery:
    get:
      operationId: image-gallery-list
      summary: List images
      description: Get a listing of images in the system. Includes gallery (page content) images and drawings. Requires visibility of the page they're originally uploaded to.
      responses:
        '200':
          description: List of images
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Image'
                  total:
                    type: integer
                    example: 3
    post:
      operationId: image-gallery-create
      summary: Create a new image
      description: Create a new image in the system. Since "image" is expected to be a file, this needs to be a 'multipart/form-data' type request. The provided "uploaded_to" should be an existing page ID in the system. If the "name" parameter is omitted, the filename of the provided image file will be used instead.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required: [type, uploaded_to, image]
              properties:
                type:
                  type: string
                  enum: [gallery, drawio]
                uploaded_to:
                  type: integer
                image:
                  type: string
                  format: binary
                  enum: [jpeg, png, gif, webp, avif]
                  maxLength: 50000
                name:
                  type: string
                  maxLength: 180
      responses:
        '201':
          description: Created image
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
  /api/image-gallery/{id}:
    get:
      operationId: image-gallery-read
      summary: Get image details
      description: View the details of a single image. The "thumbs" response property contains links to scaled variants that BookStack may use in its UI. The "content" response property provides HTML and Markdown content, in the format that BookStack would typically use by default to add the image in page content, as a convenience.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Image details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
    put:
      operationId: image-gallery-update
      summary: Update an image
      description: Update the details of an existing image in the system. Since "image" is expected to be a file, this needs to be a 'multipart/form-data' type request if providing a new image file. Updated image files should be of the same file type as the original image.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 180
                image:
                  type: string
                  format: binary
                  enum: [jpeg, png, gif, webp, avif]
                  maxLength: 50000
      responses:
        '200':
          description: Updated image
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
    delete:
      operationId: image-gallery-delete
      summary: Delete an image
      description: Delete an image from the system. Will also delete thumbnails for the image. Does not check or handle image usage so this could leave pages with broken image references.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Image deleted
  /api/search:
    get:
      operationId: search-all
      summary: Search all content
      description: Run a search query against all main content types (shelves, books, chapters & pages) in the system. Takes the same input as the main search bar within the BookStack interface as a 'query' parameter.
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
        - name: count
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResult'
                  total:
                    type: integer
                    example: 3
  /api/shelves:
    get:
      operationId: shelves-list
      summary: List shelves
      description: Get a listing of shelves visible to the user.
      responses:
        '200':
          description: List of shelves
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Shelf'
                  total:
                    type: integer
                    example: 3
    post:
      operationId: shelves-create
      summary: Create a new shelf
      description: Create a new shelf in the system. An array of book IDs can be provided in the request. These will be added to the shelf in the same order as provided. The cover image can be set by sending a file via an 'image' property within a 'multipart/form-data' request.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  maxLength: 255
                description:
                  type: string
                  maxLength: 1900
                description_html:
                  type: string
                  maxLength: 2000
                books:
                  type: array
                  items:
                    type: integer
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                image:
                  type: string
                  format: binary
                  enum: [jpeg, png, gif, webp, avif]
                  maxLength: 50000
      responses:
        '201':
          description: Created shelf
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shelf'
  /api/shelves/{id}:
    get:
      operationId: shelves-read
      summary: Get shelf details
      description: View the details of a single shelf.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Shelf details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shelf'
    put:
      operationId: shelves-update
      summary: Update a shelf
      description: Update the details of a single shelf. An array of book IDs can be provided in the request. These will be added to the shelf in the same order as provided and overwrite any existing book assignments. The cover image can be set by sending a file via an 'image' property within a 'multipart/form-data' request.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                description:
                  type: string
                  maxLength: 1900
                description_html:
                  type: string
                  maxLength: 2000
                books:
                  type: array
                  items:
                    type: integer
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                image:
                  type: string
                  format: binary
                  enum: [jpeg, png, gif, webp, avif]
                  maxLength: 50000
      responses:
        '200':
          description: Updated shelf
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shelf'
    delete:
      operationId: shelves-delete
      summary: Delete a shelf
      description: Delete a single shelf. This will typically send the shelf to the recycle bin.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Shelf deleted
  /api/users:
    get:
      operationId: users-list
      summary: List users
      description: Get a listing of users in the system. Requires permission to manage users.
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  total:
                    type: integer
                    example: 28
    post:
      operationId: users-create
      summary: Create a new user
      description: Create a new user in the system. Requires permission to manage users.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [name, email]
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                email:
                  type: string
                  format: email
                  minLength: 2
                external_auth_id:
                  type: string
                language:
                  type: string
                  maxLength: 15
                  pattern: ^[a-zA-Z0-9_-]+$
                password:
                  type: string
                  minLength: 8
                roles:
                  type: array
                  items:
                    type: integer
                send_invite:
                  type: boolean
      responses:
        '201':
          description: Created user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /api/users/{id}:
    get:
      operationId: users-read
      summary: Get user details
      description: View the details of a single user. Requires permission to manage users.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      operationId: users-update
      summary: Update a user
      description: Update an existing user in the system. Requires permission to manage users.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                email:
                  type: string
                  format: email
                  minLength: 2
                external_auth_id:
                  type: string
                language:
                  type: string
                  maxLength: 15
                  pattern: ^[a-zA-Z0-9_-]+$
                password:
                  type: string
                  minLength: 8
                roles:
                  type: array
                  items:
                    type: integer
      responses:
        '200':
          description: Updated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    delete:
      operationId: users-delete
      summary: Delete a user
      description: Delete a user from the system. Can optionally accept a user id via `migrate_ownership_id` to indicate who should be the new owner of their related content. Requires permission to manage users.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                migrate_ownership_id:
                  type: integer
      responses:
        '204':
          description: User deleted
  /api/roles:
    get:
      operationId: roles-list
      summary: List roles
      description: Get a listing of roles in the system. Requires permission to manage roles.
      responses:
        '200':
          description: List of roles
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
                  total:
                    type: integer
                    example: 3
    post:
      operationId: roles-create
      summary: Create a new role
      description: Create a new role in the system. Permissions should be provided as an array of permission name strings. Requires permission to manage roles.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [display_name]
              properties:
                display_name:
                  type: string
                  minLength: 3
                  maxLength: 180
                description:
                  type: string
                  maxLength: 180
                mfa_enforced:
                  type: boolean
                external_auth_id:
                  type: string
                  maxLength: 180
                permissions:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Created role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
  /api/roles/{id}:
    get:
      operationId: roles-read
      summary: Get role details
      description: View the details of a single role. Provides the permissions and a high-level list of the users assigned. Requires permission to manage roles.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Role details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
    put:
      operationId: roles-update
      summary: Update a role
      description: Update an existing role in the system. Permissions should be provided as an array of permission name strings. An empty "permissions" array would clear granted permissions. Requires permission to manage roles.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                display_name:
                  type: string
                  minLength: 3
                  maxLength: 180
                description:
                  type: string
                  maxLength: 180
                mfa_enforced:
                  type: boolean
                external_auth_id:
                  type: string
                  maxLength: 180
                permissions:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Updated role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
    delete:
      operationId: roles-delete
      summary: Delete a role
      description: Delete a role from the system. Requires permission to manage roles.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Role deleted
  /api/imports:
    get:
      operationId: imports-list
      summary: List imports
      description: List existing ZIP imports visible to the user. Requires permission to import content.
      responses:
        '200':
          description: List of imports
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Import'
                  total:
                    type: integer
                    example: 2
    post:
      operationId: imports-create
      summary: Create a new import
      description: Start a new import from a ZIP file. This uploads, validates, and stores the ZIP file so it's ready to be imported. Requires permission to import content.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  maxLength: 50000
      responses:
        '201':
          description: Created import
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
  /api/imports/{id}:
    get:
      operationId: imports-read
      summary: Get import details
      description: Read details of a pending ZIP import. The "details" property contains high-level metadata regarding the ZIP import content, and the structure of this will change depending on import "type". Requires permission to import content.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Import details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
    post:
      operationId: imports-run
      summary: Run an import
      description: Run the import process for an uploaded ZIP import. The "parent_id" and "parent_type" parameters are required when the import type is "chapter" or "page". On success, this endpoint returns the imported item. Requires permission to import content.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                parent_type:
                  type: string
                  enum: [book, chapter]
                parent_id:
                  type: integer
      responses:
        '200':
          description: Imported item
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Chapter'
                  - $ref: '#/components/schemas/Page'
    delete:
      operationId: imports-delete
      summary: Delete an import
      description: Delete a pending ZIP import from the system. Requires permission to import content.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Import deleted
  /api/recycle-bin:
    get:
      operationId: recycle-bin-list
      summary: List recycle bin items
      description: Get a top-level listing of the items in the recycle bin. The "deletable" property will reflect the main item deleted. Requires permission to manage both system settings and permissions.
      responses:
        '200':
          description: List of recycle bin items
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecycleBinItem'
                  total:
                    type: integer
                    example: 2
  /api/recycle-bin/{deletionId}:
    put:
      operationId: recycle-bin-restore
      summary: Restore recycle bin item
      description: Restore a single deletion from the recycle bin. Requires permission to manage both system settings and permissions.
      parameters:
        - name: deletionId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Restored item
          content:
            application/json:
              schema:
                type: object
                properties:
                  restore_count:
                    type: integer
                    example: 2
    delete:
      operationId: recycle-bin-destroy
      summary: Delete recycle bin item
      description: Remove a single deletion from the recycle bin. Use this endpoint carefully as it will entirely remove the underlying deleted items from the system. Requires permission to manage both system settings and permissions.
      parameters:
        - name: deletionId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Deleted item
          content:
            application/json:
              schema:
                type: object
                properties:
                  delete_count:
                    type: integer
                    example: 2
  /api/content-permissions/{contentType}/{contentId}:
    get:
      operationId: content-permissions-read
      summary: Read content permissions
      description: Read the configured content-level permissions for the item of the given type and ID. 'contentType' should be one of page, book, chapter, bookshelf. 'contentId' should be the relevant ID of that item type.
      parameters:
        - name: contentType
          in: path
          required: true
          schema:
            type: string
            enum: [page, book, chapter, bookshelf]
        - name: contentId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Content permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentPermissions'
    put:
      operationId: content-permissions-update
      summary: Update content permissions
      description: Update the configured content-level permission overrides for the item of the given type and ID. 'contentType' should be one of page, book, chapter, bookshelf. 'contentId' should be the relevant ID of that item type.
      parameters:
        - name: contentType
          in: path
          required: true
          schema:
            type: string
            enum: [page, book, chapter, bookshelf]
        - name: contentId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                owner_id:
                  type: integer
                role_permissions:
                  type: array
                  items:
                    type: object
                    required: [role_id, view, create, update, delete]
                    properties:
                      role_id:
                        type: integer
                      view:
                        type: boolean
                      create:
                        type: boolean
                      update:
                        type: boolean
                      delete:
                        type: boolean
                fallback_permissions:
                  type: object
                  nullable: true
                  properties:
                    inheriting:
                      type: boolean
                    view:
                      type: boolean
                    create:
                      type: boolean
                    update:
                      type: boolean
                    delete:
                      type: boolean
      responses:
        '200':
          description: Updated permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentPermissions'
  /api/audit-log:
    get:
      operationId: audit-log-list
      summary: List audit log events
      description: Get a listing of audit log events in the system. Requires permission to manage both users and system settings.
      responses:
        '200':
          description: List of audit log events
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditLog'
                  total:
                    type: integer
                    example: 6088
  /api/system:
    get:
      operationId: system-read
      summary: Get system details
      description: Read details regarding the BookStack instance. Some details may be null where not set, like the app logo for example.
      responses:
        '200':
          description: System details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/System'
components:
  schemas:
    Attachment:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        extension:
          type: string
        uploaded_to:
          type: integer
        external:
          type: boolean
        order:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by:
          type: integer
        updated_by:
          type: integer
        content:
          type: string
        links:
          type: object
          properties:
            html:
              type: string
            markdown:
              type: string
    Book:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        description_html:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        updated_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        owned_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        cover:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
            url:
              type: string
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            created_by:
              type: integer
            updated_by:
              type: integer
            path:
              type: string
            type:
              type: string
            uploaded_to:
              type: integer
        contents:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/Chapter'
              - $ref: '#/components/schemas/Page'
        tags:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
              order:
                type: integer
        default_template_id:
          type: integer
          nullable: true
    Chapter:
      type: object
      properties:
        id:
          type: integer
        book_id:
          type: integer
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        description_html:
          type: string
        priority:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        updated_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        owned_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        book_slug:
          type: string
        tags:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
              order:
                type: integer
        pages:
          type: array
          items:
            $ref: '#/components/schemas/Page'
        default_template_id:
          type: integer
          nullable: true
    Page:
      type: object
      properties:
        id:
          type: integer
        book_id:
          type: integer
        chapter_id:
          type: integer
        name:
          type: string
        slug:
          type: string
        html:
          type: string
        raw_html:
          type: string
        markdown:
          type: string
        priority:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        updated_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        owned_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        draft:
          type: boolean
        revision_count:
          type: integer
        template:
          type: boolean
        editor:
          type: string
        book_slug:
          type: string
        tags:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
              order:
                type: integer
    Image:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        url:
          type: string
        path:
          type: string
        type:
          type: string
          enum: [gallery, drawio]
        uploaded_to:
          type: integer
        created_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        updated_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        thumbs:
          type: object
          properties:
            gallery:
              type: string
            display:
              type: string
        content:
          type: object
          properties:
            html:
              type: string
            markdown:
              type: string
    SearchResult:
      type: object
      properties:
        id:
          type: integer
        book_id:
          type: integer
        slug:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        type:
          type: string
          enum: [bookshelf, book, chapter, page]
        url:
          type: string
        book:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
            slug:
              type: string
        chapter:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
            slug:
              type: string
        preview_html:
          type: object
          properties:
            name:
              type: string
            content:
              type: string
        tags:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
              order:
                type: integer
    Shelf:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        description_html:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        updated_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        owned_by:
          oneOf:
            - type: integer
            - $ref: '#/components/schemas/UserReference'
        cover:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            name:
              type: string
            url:
              type: string
        books:
          type: array
          items:
            $ref: '#/components/schemas/Book'
        tags:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
              order:
                type: integer
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        external_auth_id:
          type: string
        slug:
          type: string
        last_activity_at:
          type: string
          format: date-time
        profile_url:
          type: string
        edit_url:
          type: string
        avatar_url:
          type: string
        roles:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              display_name:
                type: string
    Role:
      type: object
      properties:
        id:
          type: integer
        display_name:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        system_name:
          type: string
        external_auth_id:
          type: string
        mfa_enforced:
          type: boolean
        permissions:
          type: array
          items:
            type: string
        users:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              slug:
                type: string
        users_count:
          type: integer
        permissions_count:
          type: integer
    Import:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        size:
          type: integer
        type:
          type: string
          enum: [book, chapter, page]
        created_by:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        path:
          type: string
        details:
          type: object
    RecycleBinItem:
      type: object
      properties:
        id:
          type: integer
        deleted_by:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        deletable_type:
          type: string
          enum: [page, book, chapter, bookshelf]
        deletable_id:
          type: integer
        deletable:
          oneOf:
            - $ref: '#/components/schemas/Page'
            - $ref: '#/components/schemas/Book'
            - $ref: '#/components/schemas/Chapter'
            - $ref: '#/components/schemas/Shelf'
    ContentPermissions:
      type: object
      properties:
        owner:
          $ref: '#/components/schemas/UserReference'
        role_permissions:
          type: array
          items:
            type: object
            properties:
              role_id:
                type: integer
              view:
                type: boolean
              create:
                type: boolean
              update:
                type: boolean
              delete:
                type: boolean
              role:
                type: object
                properties:
                  id:
                    type: integer
                  display_name:
                    type: string
        fallback_permissions:
          type: object
          properties:
            inheriting:
              type: boolean
            view:
              type: boolean
            create:
              type: boolean
            update:
              type: boolean
            delete:
              type: boolean
    AuditLog:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
        detail:
          type: string
        user_id:
          type: integer
        loggable_id:
          type: integer
          nullable: true
        loggable_type:
          type: string
          nullable: true
        ip:
          type: string
        created_at:
          type: string
          format: date-time
        user:
          $ref: '#/components/schemas/UserReference'
    System:
      type: object
      properties:
        version:
          type: string
        instance_id:
          type: string
        app_name:
          type: string
        app_logo:
          type: string
          nullable: true
        base_url:
          type: string
    UserReference:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string

@n0nag0n commented on GitHub (Aug 21, 2025): For those curious, I took the JSON docs endpoint, fed that through AI to come up with this that is accurate as of today. Worked in an MCP server I needed. ``` openapi: 3.0.3 info: title: BookStack API description: API for managing books, chapters, pages, attachments, images, users, roles, imports, and other resources in BookStack. version: v25.02.4 servers: - url: https://www.example.com description: BookStack API server paths: /api/docs: get: operationId: docs-display summary: Load the API documentation page description: Load the docs page for the API. responses: '200': description: Successful response content: text/html: schema: type: string description: HTML content of the API documentation page /api/docs.json: get: operationId: docs-json summary: Show JSON view of API docs description: Show a JSON view of the API docs data. responses: '200': description: JSON view of API documentation content: application/json: schema: type: object description: JSON representation of the API documentation /api/attachments: get: operationId: attachments-list summary: List attachments description: Get a listing of attachments visible to the user. The external property indicates whether the attachment is a simple link. A false value for the external property indicates a file upload. responses: '200': description: List of attachments content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Attachment' total: type: integer example: 2 post: operationId: attachments-create summary: Create a new attachment description: Create a new attachment in the system. An uploaded_to value must be provided containing an ID of the page that this upload will be related to. Either a file or a link must be provided, but not both. requestBody: content: multipart/form-data: schema: oneOf: - type: object required: [name, uploaded_to, file] properties: name: type: string minLength: 1 maxLength: 255 uploaded_to: type: integer file: type: string format: binary maxLength: 50000 - type: object required: [name, uploaded_to, link] properties: name: type: string minLength: 1 maxLength: 255 uploaded_to: type: integer link: type: string minLength: 1 maxLength: 2000 pattern: ^https?:// responses: '201': description: Created attachment content: application/json: schema: $ref: '#/components/schemas/Attachment' /api/attachments/{id}: get: operationId: attachments-read summary: Get attachment details description: Get the details & content of a single attachment of the given ID. The attachment link or file content is provided via a 'content' property. For files, the content will be base64 encoded. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Attachment details content: application/json: schema: $ref: '#/components/schemas/Attachment' put: operationId: attachments-update summary: Update an attachment description: Update the details of a single attachment. If a file is being provided, the request should be formatted as a multipart/form-data request. parameters: - name: id in: path required: true schema: type: integer requestBody: content: multipart/form-data: schema: oneOf: - type: object properties: name: type: string minLength: 1 maxLength: 255 uploaded_to: type: integer file: type: string format: binary maxLength: 50000 - type: object properties: name: type: string minLength: 1 maxLength: 255 uploaded_to: type: integer link: type: string minLength: 1 maxLength: 2000 pattern: ^https?:// responses: '200': description: Updated attachment content: application/json: schema: $ref: '#/components/schemas/Attachment' delete: operationId: attachments-delete summary: Delete an attachment description: Delete an attachment of the given ID. parameters: - name: id in: path required: true schema: type: integer responses: '204': description: Attachment deleted /api/books: get: operationId: books-list summary: List books description: Get a listing of books visible to the user. responses: '200': description: List of books content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Book' total: type: integer example: 14 post: operationId: books-create summary: Create a new book description: Create a new book in the system. The cover image can be set by sending a file via an 'image' property within a 'multipart/form-data' request. If the 'image' property is null, the book cover image will be removed. requestBody: content: multipart/form-data: schema: type: object required: [name] properties: name: type: string maxLength: 255 description: type: string maxLength: 1900 description_html: type: string maxLength: 2000 tags: type: array items: type: object properties: name: type: string value: type: string image: type: string format: binary enum: [jpeg, png, gif, webp, avif] maxLength: 50000 default_template_id: type: integer nullable: true responses: '201': description: Created book content: application/json: schema: $ref: '#/components/schemas/Book' /api/books/{id}: get: operationId: books-read summary: Get book details description: View the details of a single book. The response data will contain a 'content' property listing the chapters and pages directly within, in the same structure as seen in the BookStack interface. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Book details content: application/json: schema: $ref: '#/components/schemas/Book' put: operationId: books-update summary: Update a book description: Update the details of a single book. The cover image can be set by sending a file via an 'image' property within a 'multipart/form-data' request. If the 'image' property is null, the book cover image will be removed. parameters: - name: id in: path required: true schema: type: integer requestBody: content: multipart/form-data: schema: type: object properties: name: type: string minLength: 1 maxLength: 255 description: type: string maxLength: 1900 description_html: type: string maxLength: 2000 tags: type: array items: type: object properties: name: type: string value: type: string image: type: string format: binary enum: [jpeg, png, gif, webp, avif] maxLength: 50000 default_template_id: type: integer nullable: true responses: '200': description: Updated book content: application/json: schema: $ref: '#/components/schemas/Book' delete: operationId: books-delete summary: Delete a book description: Delete a single book. This will typically send the book to the recycle bin. parameters: - name: id in: path required: true schema: type: integer responses: '204': description: Book deleted /api/books/{id}/export/html: get: operationId: books-exportHtml summary: Export book as HTML description: Export a book as a contained HTML file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: HTML file content: text/html: schema: type: string /api/books/{id}/export/pdf: get: operationId: books-exportPdf summary: Export book as PDF description: Export a book as a PDF file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: PDF file content: application/pdf: schema: type: string format: binary /api/books/{id}/export/plaintext: get: operationId: books-exportPlainText summary: Export book as plain text description: Export a book as a plain text file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Plain text file content: text/plain: schema: type: string /api/books/{id}/export/markdown: get: operationId: books-exportMarkdown summary: Export book as markdown description: Export a book as a markdown file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Markdown file content: text/markdown: schema: type: string /api/books/{id}/export/zip: get: operationId: books-exportZip summary: Export book as ZIP description: Export a book as a contained ZIP export file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: ZIP file content: application/zip: schema: type: string format: binary /api/chapters: get: operationId: chapters-list summary: List chapters description: Get a listing of chapters visible to the user. responses: '200': description: List of chapters content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Chapter' total: type: integer example: 40 post: operationId: chapters-create summary: Create a new chapter description: Create a new chapter in the system. requestBody: content: application/json: schema: type: object required: [book_id, name] properties: book_id: type: integer name: type: string maxLength: 255 description: type: string maxLength: 1900 description_html: type: string maxLength: 2000 tags: type: array items: type: object properties: name: type: string value: type: string priority: type: integer default_template_id: type: integer nullable: true responses: '201': description: Created chapter content: application/json: schema: $ref: '#/components/schemas/Chapter' /api/chapters/{id}: get: operationId: chapters-read summary: Get chapter details description: View the details of a single chapter. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Chapter details content: application/json: schema: $ref: '#/components/schemas/Chapter' put: operationId: chapters-update summary: Update a chapter description: Update the details of a single chapter. Providing a 'book_id' property will move the chapter into that parent element if you have permissions to do so. parameters: - name: id in: path required: true schema: type: integer requestBody: content: application/json: schema: type: object properties: book_id: type: integer name: type: string minLength: 1 maxLength: 255 description: type: string maxLength: 1900 description_html: type: string maxLength: 2000 tags: type: array items: type: object properties: name: type: string value: type: string priority: type: integer default_template_id: type: integer nullable: true responses: '200': description: Updated chapter content: application/json: schema: $ref: '#/components/schemas/Chapter' delete: operationId: chapters-delete summary: Delete a chapter description: Delete a chapter. This will typically send the chapter to the recycle bin. parameters: - name: id in: path required: true schema: type: integer responses: '204': description: Chapter deleted /api/chapters/{id}/export/html: get: operationId: chapters-exportHtml summary: Export chapter as HTML description: Export a chapter as a contained HTML file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: HTML file content: text/html: schema: type: string /api/chapters/{id}/export/pdf: get: operationId: chapters-exportPdf summary: Export chapter as PDF description: Export a chapter as a PDF file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: PDF file content: application/pdf: schema: type: string format: binary /api/chapters/{id}/export/plaintext: get: operationId: chapters-exportPlainText summary: Export chapter as plain text description: Export a chapter as a plain text file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Plain text file content: text/plain: schema: type: string /api/chapters/{id}/export/markdown: get: operationId: chapters-exportMarkdown summary: Export chapter as markdown description: Export a chapter as a markdown file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Markdown file content: text/markdown: schema: type: string /api/chapters/{id}/export/zip: get: operationId: chapters-exportZip summary: Export chapter as ZIP description: Export a chapter as a contained ZIP file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: ZIP file content: application/zip: schema: type: string format: binary /api/pages: get: operationId: pages-list summary: List pages description: Get a listing of pages visible to the user. responses: '200': description: List of pages content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Page' total: type: integer example: 322 post: operationId: pages-create summary: Create a new page description: Create a new page in the system. The ID of a parent book or chapter is required to indicate where this page should be located. Any HTML content provided should be kept to a single-block depth of plain HTML elements to remain compatible with the BookStack front-end and editors. Any images included via base64 data URIs will be extracted and saved as gallery images against the page during upload. requestBody: content: application/json: schema: type: object required: [name] properties: book_id: type: integer chapter_id: type: integer name: type: string maxLength: 255 html: type: string markdown: type: string tags: type: array items: type: object properties: name: type: string value: type: string priority: type: integer responses: '201': description: Created page content: application/json: schema: $ref: '#/components/schemas/Page' /api/pages/{id}: get: operationId: pages-read summary: Get page details description: View the details of a single page. Pages will always have HTML content. They may have markdown content if the markdown editor was used to last update the page. The 'html' property is the fully rendered & escaped HTML content that BookStack would show on page view, with page includes handled. The 'raw_html' property is the direct database stored HTML content, which would be what BookStack shows on page edit. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Page details content: application/json: schema: $ref: '#/components/schemas/Page' put: operationId: pages-update summary: Update a page description: Update the details of a single page. Providing a 'book_id' or 'chapter_id' property will move the page into that parent element if you have permissions to do so. parameters: - name: id in: path required: true schema: type: integer requestBody: content: application/json: schema: type: object properties: book_id: type: integer chapter_id: type: integer name: type: string minLength: 1 maxLength: 255 html: type: string markdown: type: string tags: type: array items: type: object properties: name: type: string value: type: string priority: type: integer responses: '200': description: Updated page content: application/json: schema: $ref: '#/components/schemas/Page' delete: operationId: pages-delete summary: Delete a page description: Delete a page. This will typically send the page to the recycle bin. parameters: - name: id in: path required: true schema: type: integer responses: '204': description: Page deleted /api/pages/{id}/export/html: get: operationId: pages-exportHtml summary: Export page as HTML description: Export a page as a contained HTML file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: HTML file content: text/html: schema: type: string /api/pages/{id}/export/pdf: get: operationId: pages-exportPdf summary: Export page as PDF description: Export a page as a PDF file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: PDF file content: application/pdf: schema: type: string format: binary /api/pages/{id}/export/plaintext: get: operationId: pages-exportPlainText summary: Export page as plain text description: Export a page as a plain text file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Plain text file content: text/plain: schema: type: string /api/pages/{id}/export/markdown: get: operationId: pages-exportMarkdown summary: Export page as markdown description: Export a page as a markdown file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Markdown file content: text/markdown: schema: type: string /api/pages/{id}/export/zip: get: operationId: pages-exportZip summary: Export page as ZIP description: Export a page as a contained ZIP file. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: ZIP file content: application/zip: schema: type: string format: binary /api/image-gallery: get: operationId: image-gallery-list summary: List images description: Get a listing of images in the system. Includes gallery (page content) images and drawings. Requires visibility of the page they're originally uploaded to. responses: '200': description: List of images content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Image' total: type: integer example: 3 post: operationId: image-gallery-create summary: Create a new image description: Create a new image in the system. Since "image" is expected to be a file, this needs to be a 'multipart/form-data' type request. The provided "uploaded_to" should be an existing page ID in the system. If the "name" parameter is omitted, the filename of the provided image file will be used instead. requestBody: content: multipart/form-data: schema: type: object required: [type, uploaded_to, image] properties: type: type: string enum: [gallery, drawio] uploaded_to: type: integer image: type: string format: binary enum: [jpeg, png, gif, webp, avif] maxLength: 50000 name: type: string maxLength: 180 responses: '201': description: Created image content: application/json: schema: $ref: '#/components/schemas/Image' /api/image-gallery/{id}: get: operationId: image-gallery-read summary: Get image details description: View the details of a single image. The "thumbs" response property contains links to scaled variants that BookStack may use in its UI. The "content" response property provides HTML and Markdown content, in the format that BookStack would typically use by default to add the image in page content, as a convenience. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Image details content: application/json: schema: $ref: '#/components/schemas/Image' put: operationId: image-gallery-update summary: Update an image description: Update the details of an existing image in the system. Since "image" is expected to be a file, this needs to be a 'multipart/form-data' type request if providing a new image file. Updated image files should be of the same file type as the original image. parameters: - name: id in: path required: true schema: type: integer requestBody: content: multipart/form-data: schema: type: object properties: name: type: string maxLength: 180 image: type: string format: binary enum: [jpeg, png, gif, webp, avif] maxLength: 50000 responses: '200': description: Updated image content: application/json: schema: $ref: '#/components/schemas/Image' delete: operationId: image-gallery-delete summary: Delete an image description: Delete an image from the system. Will also delete thumbnails for the image. Does not check or handle image usage so this could leave pages with broken image references. parameters: - name: id in: path required: true schema: type: integer responses: '204': description: Image deleted /api/search: get: operationId: search-all summary: Search all content description: Run a search query against all main content types (shelves, books, chapters & pages) in the system. Takes the same input as the main search bar within the BookStack interface as a 'query' parameter. parameters: - name: query in: query required: true schema: type: string - name: page in: query schema: type: integer minimum: 1 - name: count in: query schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Search results content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/SearchResult' total: type: integer example: 3 /api/shelves: get: operationId: shelves-list summary: List shelves description: Get a listing of shelves visible to the user. responses: '200': description: List of shelves content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Shelf' total: type: integer example: 3 post: operationId: shelves-create summary: Create a new shelf description: Create a new shelf in the system. An array of book IDs can be provided in the request. These will be added to the shelf in the same order as provided. The cover image can be set by sending a file via an 'image' property within a 'multipart/form-data' request. requestBody: content: multipart/form-data: schema: type: object required: [name] properties: name: type: string maxLength: 255 description: type: string maxLength: 1900 description_html: type: string maxLength: 2000 books: type: array items: type: integer tags: type: array items: type: object properties: name: type: string value: type: string image: type: string format: binary enum: [jpeg, png, gif, webp, avif] maxLength: 50000 responses: '201': description: Created shelf content: application/json: schema: $ref: '#/components/schemas/Shelf' /api/shelves/{id}: get: operationId: shelves-read summary: Get shelf details description: View the details of a single shelf. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Shelf details content: application/json: schema: $ref: '#/components/schemas/Shelf' put: operationId: shelves-update summary: Update a shelf description: Update the details of a single shelf. An array of book IDs can be provided in the request. These will be added to the shelf in the same order as provided and overwrite any existing book assignments. The cover image can be set by sending a file via an 'image' property within a 'multipart/form-data' request. parameters: - name: id in: path required: true schema: type: integer requestBody: content: multipart/form-data: schema: type: object properties: name: type: string minLength: 1 maxLength: 255 description: type: string maxLength: 1900 description_html: type: string maxLength: 2000 books: type: array items: type: integer tags: type: array items: type: object properties: name: type: string value: type: string image: type: string format: binary enum: [jpeg, png, gif, webp, avif] maxLength: 50000 responses: '200': description: Updated shelf content: application/json: schema: $ref: '#/components/schemas/Shelf' delete: operationId: shelves-delete summary: Delete a shelf description: Delete a single shelf. This will typically send the shelf to the recycle bin. parameters: - name: id in: path required: true schema: type: integer responses: '204': description: Shelf deleted /api/users: get: operationId: users-list summary: List users description: Get a listing of users in the system. Requires permission to manage users. responses: '200': description: List of users content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/User' total: type: integer example: 28 post: operationId: users-create summary: Create a new user description: Create a new user in the system. Requires permission to manage users. requestBody: content: application/json: schema: type: object required: [name, email] properties: name: type: string minLength: 1 maxLength: 100 email: type: string format: email minLength: 2 external_auth_id: type: string language: type: string maxLength: 15 pattern: ^[a-zA-Z0-9_-]+$ password: type: string minLength: 8 roles: type: array items: type: integer send_invite: type: boolean responses: '201': description: Created user content: application/json: schema: $ref: '#/components/schemas/User' /api/users/{id}: get: operationId: users-read summary: Get user details description: View the details of a single user. Requires permission to manage users. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: User details content: application/json: schema: $ref: '#/components/schemas/User' put: operationId: users-update summary: Update a user description: Update an existing user in the system. Requires permission to manage users. parameters: - name: id in: path required: true schema: type: integer requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 email: type: string format: email minLength: 2 external_auth_id: type: string language: type: string maxLength: 15 pattern: ^[a-zA-Z0-9_-]+$ password: type: string minLength: 8 roles: type: array items: type: integer responses: '200': description: Updated user content: application/json: schema: $ref: '#/components/schemas/User' delete: operationId: users-delete summary: Delete a user description: Delete a user from the system. Can optionally accept a user id via `migrate_ownership_id` to indicate who should be the new owner of their related content. Requires permission to manage users. parameters: - name: id in: path required: true schema: type: integer requestBody: content: application/json: schema: type: object properties: migrate_ownership_id: type: integer responses: '204': description: User deleted /api/roles: get: operationId: roles-list summary: List roles description: Get a listing of roles in the system. Requires permission to manage roles. responses: '200': description: List of roles content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Role' total: type: integer example: 3 post: operationId: roles-create summary: Create a new role description: Create a new role in the system. Permissions should be provided as an array of permission name strings. Requires permission to manage roles. requestBody: content: application/json: schema: type: object required: [display_name] properties: display_name: type: string minLength: 3 maxLength: 180 description: type: string maxLength: 180 mfa_enforced: type: boolean external_auth_id: type: string maxLength: 180 permissions: type: array items: type: string responses: '201': description: Created role content: application/json: schema: $ref: '#/components/schemas/Role' /api/roles/{id}: get: operationId: roles-read summary: Get role details description: View the details of a single role. Provides the permissions and a high-level list of the users assigned. Requires permission to manage roles. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Role details content: application/json: schema: $ref: '#/components/schemas/Role' put: operationId: roles-update summary: Update a role description: Update an existing role in the system. Permissions should be provided as an array of permission name strings. An empty "permissions" array would clear granted permissions. Requires permission to manage roles. parameters: - name: id in: path required: true schema: type: integer requestBody: content: application/json: schema: type: object properties: display_name: type: string minLength: 3 maxLength: 180 description: type: string maxLength: 180 mfa_enforced: type: boolean external_auth_id: type: string maxLength: 180 permissions: type: array items: type: string responses: '200': description: Updated role content: application/json: schema: $ref: '#/components/schemas/Role' delete: operationId: roles-delete summary: Delete a role description: Delete a role from the system. Requires permission to manage roles. parameters: - name: id in: path required: true schema: type: integer responses: '204': description: Role deleted /api/imports: get: operationId: imports-list summary: List imports description: List existing ZIP imports visible to the user. Requires permission to import content. responses: '200': description: List of imports content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Import' total: type: integer example: 2 post: operationId: imports-create summary: Create a new import description: Start a new import from a ZIP file. This uploads, validates, and stores the ZIP file so it's ready to be imported. Requires permission to import content. requestBody: content: multipart/form-data: schema: type: object required: [file] properties: file: type: string format: binary maxLength: 50000 responses: '201': description: Created import content: application/json: schema: $ref: '#/components/schemas/Import' /api/imports/{id}: get: operationId: imports-read summary: Get import details description: Read details of a pending ZIP import. The "details" property contains high-level metadata regarding the ZIP import content, and the structure of this will change depending on import "type". Requires permission to import content. parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Import details content: application/json: schema: $ref: '#/components/schemas/Import' post: operationId: imports-run summary: Run an import description: Run the import process for an uploaded ZIP import. The "parent_id" and "parent_type" parameters are required when the import type is "chapter" or "page". On success, this endpoint returns the imported item. Requires permission to import content. parameters: - name: id in: path required: true schema: type: integer requestBody: content: application/json: schema: type: object properties: parent_type: type: string enum: [book, chapter] parent_id: type: integer responses: '200': description: Imported item content: application/json: schema: oneOf: - $ref: '#/components/schemas/Chapter' - $ref: '#/components/schemas/Page' delete: operationId: imports-delete summary: Delete an import description: Delete a pending ZIP import from the system. Requires permission to import content. parameters: - name: id in: path required: true schema: type: integer responses: '204': description: Import deleted /api/recycle-bin: get: operationId: recycle-bin-list summary: List recycle bin items description: Get a top-level listing of the items in the recycle bin. The "deletable" property will reflect the main item deleted. Requires permission to manage both system settings and permissions. responses: '200': description: List of recycle bin items content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/RecycleBinItem' total: type: integer example: 2 /api/recycle-bin/{deletionId}: put: operationId: recycle-bin-restore summary: Restore recycle bin item description: Restore a single deletion from the recycle bin. Requires permission to manage both system settings and permissions. parameters: - name: deletionId in: path required: true schema: type: integer responses: '200': description: Restored item content: application/json: schema: type: object properties: restore_count: type: integer example: 2 delete: operationId: recycle-bin-destroy summary: Delete recycle bin item description: Remove a single deletion from the recycle bin. Use this endpoint carefully as it will entirely remove the underlying deleted items from the system. Requires permission to manage both system settings and permissions. parameters: - name: deletionId in: path required: true schema: type: integer responses: '200': description: Deleted item content: application/json: schema: type: object properties: delete_count: type: integer example: 2 /api/content-permissions/{contentType}/{contentId}: get: operationId: content-permissions-read summary: Read content permissions description: Read the configured content-level permissions for the item of the given type and ID. 'contentType' should be one of page, book, chapter, bookshelf. 'contentId' should be the relevant ID of that item type. parameters: - name: contentType in: path required: true schema: type: string enum: [page, book, chapter, bookshelf] - name: contentId in: path required: true schema: type: integer responses: '200': description: Content permissions content: application/json: schema: $ref: '#/components/schemas/ContentPermissions' put: operationId: content-permissions-update summary: Update content permissions description: Update the configured content-level permission overrides for the item of the given type and ID. 'contentType' should be one of page, book, chapter, bookshelf. 'contentId' should be the relevant ID of that item type. parameters: - name: contentType in: path required: true schema: type: string enum: [page, book, chapter, bookshelf] - name: contentId in: path required: true schema: type: integer requestBody: content: application/json: schema: type: object properties: owner_id: type: integer role_permissions: type: array items: type: object required: [role_id, view, create, update, delete] properties: role_id: type: integer view: type: boolean create: type: boolean update: type: boolean delete: type: boolean fallback_permissions: type: object nullable: true properties: inheriting: type: boolean view: type: boolean create: type: boolean update: type: boolean delete: type: boolean responses: '200': description: Updated permissions content: application/json: schema: $ref: '#/components/schemas/ContentPermissions' /api/audit-log: get: operationId: audit-log-list summary: List audit log events description: Get a listing of audit log events in the system. Requires permission to manage both users and system settings. responses: '200': description: List of audit log events content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/AuditLog' total: type: integer example: 6088 /api/system: get: operationId: system-read summary: Get system details description: Read details regarding the BookStack instance. Some details may be null where not set, like the app logo for example. responses: '200': description: System details content: application/json: schema: $ref: '#/components/schemas/System' components: schemas: Attachment: type: object properties: id: type: integer name: type: string extension: type: string uploaded_to: type: integer external: type: boolean order: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time created_by: type: integer updated_by: type: integer content: type: string links: type: object properties: html: type: string markdown: type: string Book: type: object properties: id: type: integer name: type: string slug: type: string description: type: string description_html: type: string created_at: type: string format: date-time updated_at: type: string format: date-time created_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' updated_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' owned_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' cover: type: object nullable: true properties: id: type: integer name: type: string url: type: string created_at: type: string format: date-time updated_at: type: string format: date-time created_by: type: integer updated_by: type: integer path: type: string type: type: string uploaded_to: type: integer contents: type: array items: oneOf: - $ref: '#/components/schemas/Chapter' - $ref: '#/components/schemas/Page' tags: type: array items: type: object properties: name: type: string value: type: string order: type: integer default_template_id: type: integer nullable: true Chapter: type: object properties: id: type: integer book_id: type: integer slug: type: string name: type: string description: type: string description_html: type: string priority: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time created_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' updated_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' owned_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' book_slug: type: string tags: type: array items: type: object properties: name: type: string value: type: string order: type: integer pages: type: array items: $ref: '#/components/schemas/Page' default_template_id: type: integer nullable: true Page: type: object properties: id: type: integer book_id: type: integer chapter_id: type: integer name: type: string slug: type: string html: type: string raw_html: type: string markdown: type: string priority: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time created_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' updated_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' owned_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' draft: type: boolean revision_count: type: integer template: type: boolean editor: type: string book_slug: type: string tags: type: array items: type: object properties: name: type: string value: type: string order: type: integer Image: type: object properties: id: type: integer name: type: string url: type: string path: type: string type: type: string enum: [gallery, drawio] uploaded_to: type: integer created_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' updated_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' created_at: type: string format: date-time updated_at: type: string format: date-time thumbs: type: object properties: gallery: type: string display: type: string content: type: object properties: html: type: string markdown: type: string SearchResult: type: object properties: id: type: integer book_id: type: integer slug: type: string name: type: string created_at: type: string format: date-time updated_at: type: string format: date-time type: type: string enum: [bookshelf, book, chapter, page] url: type: string book: type: object properties: id: type: integer name: type: string slug: type: string chapter: type: object nullable: true properties: id: type: integer name: type: string slug: type: string preview_html: type: object properties: name: type: string content: type: string tags: type: array items: type: object properties: name: type: string value: type: string order: type: integer Shelf: type: object properties: id: type: integer name: type: string slug: type: string description: type: string description_html: type: string created_at: type: string format: date-time updated_at: type: string format: date-time created_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' updated_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' owned_by: oneOf: - type: integer - $ref: '#/components/schemas/UserReference' cover: type: object nullable: true properties: id: type: integer name: type: string url: type: string books: type: array items: $ref: '#/components/schemas/Book' tags: type: array items: type: object properties: name: type: string value: type: string order: type: integer User: type: object properties: id: type: integer name: type: string email: type: string format: email created_at: type: string format: date-time updated_at: type: string format: date-time external_auth_id: type: string slug: type: string last_activity_at: type: string format: date-time profile_url: type: string edit_url: type: string avatar_url: type: string roles: type: array items: type: object properties: id: type: integer display_name: type: string Role: type: object properties: id: type: integer display_name: type: string description: type: string created_at: type: string format: date-time updated_at: type: string format: date-time system_name: type: string external_auth_id: type: string mfa_enforced: type: boolean permissions: type: array items: type: string users: type: array items: type: object properties: id: type: integer name: type: string slug: type: string users_count: type: integer permissions_count: type: integer Import: type: object properties: id: type: integer name: type: string size: type: integer type: type: string enum: [book, chapter, page] created_by: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time path: type: string details: type: object RecycleBinItem: type: object properties: id: type: integer deleted_by: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time deletable_type: type: string enum: [page, book, chapter, bookshelf] deletable_id: type: integer deletable: oneOf: - $ref: '#/components/schemas/Page' - $ref: '#/components/schemas/Book' - $ref: '#/components/schemas/Chapter' - $ref: '#/components/schemas/Shelf' ContentPermissions: type: object properties: owner: $ref: '#/components/schemas/UserReference' role_permissions: type: array items: type: object properties: role_id: type: integer view: type: boolean create: type: boolean update: type: boolean delete: type: boolean role: type: object properties: id: type: integer display_name: type: string fallback_permissions: type: object properties: inheriting: type: boolean view: type: boolean create: type: boolean update: type: boolean delete: type: boolean AuditLog: type: object properties: id: type: integer type: type: string detail: type: string user_id: type: integer loggable_id: type: integer nullable: true loggable_type: type: string nullable: true ip: type: string created_at: type: string format: date-time user: $ref: '#/components/schemas/UserReference' System: type: object properties: version: type: string instance_id: type: string app_name: type: string app_logo: type: string nullable: true base_url: type: string UserReference: type: object properties: id: type: integer name: type: string slug: type: string ```

Sign in to join this conversation.

No Branch/Tag Specified

Branches Tags

development

further_theme_development

l10n_development

release

llm_only

vectors

v25-11

docker_env

drawio_rendering

user_permissions

ldap_host_failover

svg_image

prosemirror

captcha_example

fix/video-export

v25.12.3

v25.12.2

v25.12.1

v25.12

v25.11.6

v25.11.5

v25.11.4

v24.11.4

v25.11.3

v25.11.2

v25.11.1

v25.11

v25.07.3

v25.07.2

v25.07.1

v25.07

v25.05.2

v25.05.1

v25.05

v25.02.5

v25.02.4

v25.02.3

v25.02.2

v25.02.1

v25.02

v24.12.1

v24.12

v24.10.3

v24.10.2

v24.10.1

v24.10

v24.05.4

v24.05.3

v24.05.2

v24.05.1

v24.05

v24.02.3

v24.02.2

v24.02.1

v24.02

v23.12.3

v23.12.2

v23.12.1

v23.12

v23.10.4

v23.10.3

v23.10.2

v23.10.1

v23.10

v23.08.3

v23.08.2

v23.08.1

v23.08

v23.06.2

v23.06.1

v23.06

v23.05.2

v23.05.1

v23.05

v23.02.3

v23.02.2

v23.02.1

v23.02

v23.01.1

v23.01

v22.11.1

v22.11

v22.10.2

v22.10.1

v22.10

v22.09.1

v22.09

v22.07.3

v22.07.2

v22.07.1

v22.07

v22.06.2

v22.06.1

v22.06

v22.04.2

v22.04.1

v22.04

v22.03.1

v22.03

v22.02.3

v22.02.2

v22.02.1

v22.02

v21.12.5

v21.12.4

v21.12.3

v21.12.2

v21.12.1

v21.12

v21.11.3

v21.11.2

v21.11.1

v21.11

v21.10.3

v21.10.2

v21.10.1

v21.10

v21.08.6

v21.08.5

v21.08.4

v21.08.3

v21.08.2

v21.08.1

v21.08

v21.05.4

v21.05.3

v21.05.2

v21.05.1

v21.05

v21.04.6

v21.04.5

v21.04.4

v21.04.3

v21.04.2

v21.04.1

v21.04

v0.31.8

v0.31.7

v0.31.6

v0.31.5

v0.31.4

v0.31.3

v0.31.2

v0.31.1

v0.31.0

v0.30.7

v0.30.6

v0.30.5

v0.30.4

v0.30.3

v0.30.2

v0.30.1

v0.30.0

v0.29.3

v0.29.2

v0.29.1

v0.29.0

v0.28.3

v0.28.2

v0.28.1

v0.28.0

v0.27.5

v0.27.4

v0.27.3

v0.27.2

v0.27.1

v0.27

v0.26.4

v0.26.3

v0.26.2

v0.26.1

v0.26.0

v0.25.5

v0.25.4

v0.25.3

v0.25.2

v0.25.1

v0.25.0

v0.24.3

v0.24.2

v0.24.1

v0.24.0

v0.23.2

v0.23.1

v0.23.0

v0.22.0

v0.21.0

v0.20.3

v0.20.2

v0.20.1

v0.20.0

v0.19.0

v0.18.5

v0.18.4

v0.18.3

v0.18.2

v0.18.1

v0.18.0

v0.17.4

v0.17.3

v0.17.2

v0.17.1

v0.17.0

v0.16.3

v0.16.2

v0.16.1

v0.16.0

v0.15.3

v0.15.2

v0.15.1

v0.15.0

v0.14.3

v0.14.2

v0.14.1

v0.14.0

v0.13.1

v0.13.0

v0.12.2

v0.12.1

v0.12.0

v0.11.2

v0.11.1

v0.11.0

v0.10.0

v0.9.3

v0.9.2

v0.9.1

v0.9.0

v0.8.2

v0.8.1

v0.8.0

v0.7.6

v0.7.5

v0.7.4

v0.7.3

0.7.2

v.0.7.1

v0.7.0

v0.6.3

v0.6.2

v0.6.1

v0.6.0

v0.5.0

Labels

Clear labels

🎨 Design

📖 Docs Update

🐛 Bug

🐛 Bug

:cat2:🐈 Possible duplicate

💿 Database

☕ Open to discussion

💻 Front-End

🐕 Support

🚪 Authentication

🌍 Translations

🔌 API Task

🏭 Back-End

⛲ Upstream

🔨 Feature Request

🛠️ Enhancement

🛠️ Enhancement

🛠️ Enhancement

❤️ Happy feedback

🔒 Security

🔍 Pending Validation

💆 UX

📝 WYSIWYG Editor

🌔 Out of scope

🔩 API Request

:octocat: Admin/Meta

🖌️ View Customization

❓ Question

🚀 Priority

🛡️ Blocked

🚚 Export System

♿ A11y

🔧 Maintenance

> Markdown Editor

pull-request

Mirrored from GitHub Pull Request

No Label 🔨 Feature Request 🌔 Out of scope

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

OVERLORD

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#4439