---
title: "Attach book"
method: POST
path: "/api/notebooks/{notebook}/attach-book"
tags: ["notebook-books-controller"]
---

# Attach book

`POST /api/notebooks/{notebook}/attach-book`

## Request

- Base URL: `` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/notebooks/{notebook}/attach-book`
- Auth: none declared

## Path parameters

- `notebook` integer, required

## Request body `multipart/form-data`

- object
  - `metadata` AttachBookRequestFull, required: Attach book metadata as JSON
    - `bookName` string, required
    - `format` 'pdf' | 'epub', required: Book file format
    - `bookLayout` AttachBookLayoutRequestFull
      - `roots` AttachBookLayoutNodeRequestFull[], required: Root nodes of the nested book layout.
        - `title` string, required
        - `children` AttachBookLayoutNodeRequestFull[]
        - `contentBlocks` object[]
    - `contentList` unknown[]: MinerU content_list array; server builds the book layout. Mutually exclusive with non-empty book layout roots.
      - unknown
  - `file` string, binary, required: Book file

## Response `201`

Created

- BookFull
  - `id` integer, required
  - `bookName` string, required
  - `format` string, required
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `blocks` BookBlockFull[], required: Book blocks in depth-first preorder (parent before descendants, then siblings). Order matches ascending book layout sequence in persistence.
    - `id` integer, required
    - `depth` integer, required: Nesting depth in the book layout; root-level blocks are 0.
    - `title` string, required
    - `contentLocators` union[], required
      - union
        - EpubLocatorFull
          - `type` string, required
          - `href` string, required
          - `fragment` string
          - `cfi` string
        - PdfLocatorFull
          - `type` string, required
          - `pageIndex` integer, required
          - `bbox` number[], required
          - `contentBlockId` integer
          - `derivedTitle` string
    - `contentBlocks` BookContentBlockFull[], required
      - `id` integer, required
      - `type` string, required
      - `pageIdx` integer
  - `notebookId` string, required

## Changes

- **2026-09-29** `feba4ecd7257`: 1 info
  - added the optional property `blocks/items/contentLocators/items/oneOf[#/components/schemas/EpubLocator_Full]/allOf[subschema #2]/cfi` to the response with the `201` status
- **2026-08-17** `5bdb7bbe4fef`: 1 warning, 1 info
  - removed the request property `metadata/layout`
  - added the new optional request property `metadata/bookLayout`
- **2026-05-14** `86ad40c3d51e`: 2 breaking
  - the `metadata/layout/roots` request property's minItems was increased to `1`
  - the `metadata/format` request property's minLength was increased from `0` to `1`
- **2026-05-11** `d7c2946139e9`: 1 info
  - the `metadata/format` request property's minLength was decreased from `1` to `0`

[Operation history](https://skmtc.dev/nerds-odd-e/apis/odd-e-open-api/changes/api/notebooks/:notebook/attach-book/post.md)

---

[API](https://skmtc.dev/nerds-odd-e/apis/odd-e-open-api.md) - [All operations](https://skmtc.dev/nerds-odd-e/apis/odd-e-open-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nerds-odd-e/apis/odd-e-open-api/revisions/193c5e89085a?raw)