# buzz.bookhive.uploadPersonalBook

> Upload an ebook file to the authenticated user's personal library. Accepts EPUB, MOBI/AZW/AZW3, FB2 (including .fb2.zip) and CBZ. The declared Content-Type is advisory only: the format is determined from the file's magic bytes checked against the `filename` extension, and a file that matches neither is rejected. `application/octet-stream` is accepted because mobile document pickers and plain curl uploads routinely send it.

- Kind: procedure
- Authority: bookhive.buzz
- Lexicon: 1
- Published by [bookhive.buzz](https://lexicon.garden/identity/did:plc:enu2j5xjlqsjaylv3du4myh4), the NSID's authority

## Links

- [Documentation](https://lexicon.garden/lexicon/did:plc:enu2j5xjlqsjaylv3du4myh4/buzz.bookhive.uploadPersonalBook)
- [Schema JSON](https://lexicon.garden/lexicon/did:plc:enu2j5xjlqsjaylv3du4myh4/buzz.bookhive.uploadPersonalBook/schema.json)
- [Analytics](https://lexicon.garden/lexicon/did:plc:enu2j5xjlqsjaylv3du4myh4/buzz.bookhive.uploadPersonalBook/analytics)

## Procedure (`buzz.bookhive.uploadPersonalBook`)

Type: procedure · POST

### Parameters (query string)

- `filename` (string, required): Original file name including extension. Required: the extension is the only thing distinguishing the zip-container formats (.epub / .cbz / .fb2.zip) from each other, and it is the key used to match e-reader sync documents to this file.
  - Constraints: minLength: 1, maxLength: 512

### Input (application/epub+zip,application/x-mobipocket-ebook,application/vnd.amazon.ebook,application/vnd.amazon.mobi8-ebook,application/x-fictionbook+xml,application/vnd.comicbook+zip,application/x-cbz,application/zip,application/octet-stream)


### Output (application/json)

- `book` (ref, required)
  - Reference: `buzz.bookhive.getPersonalLibrary#personalBookView`
- `storageQuotaBytes` (integer, required): Total bytes this user is allowed to store
  - Constraints: minimum: 0
- `storageUsedBytes` (integer, required): Total bytes stored for this user after the upload
  - Constraints: minimum: 0

### Errors

- `UnsupportedFormat`: The bytes are not a recognised ebook, or do not match the filename's extension
- `AlreadyExists`: A book with this content hash is already in the library
- `TooLarge`: The file exceeds the per-file size limit
- `QuotaExceeded`: The upload would take the library over its total storage quota
- `Busy`: Too many uploads are being processed; retry shortly

## Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "main": {
      "description": "Upload an ebook file to the authenticated user's personal library. Accepts EPUB, MOBI/AZW/AZW3, FB2 (including .fb2.zip) and CBZ. The declared Content-Type is advisory only: the format is determined from the file's magic bytes checked against the `filename` extension, and a file that matches neither is rejected. `application/octet-stream` is accepted because mobile document pickers and plain curl uploads routinely send it.",
      "errors": [
        {
          "description": "The bytes are not a recognised ebook, or do not match the filename's extension",
          "name": "UnsupportedFormat"
        },
        {
          "description": "A book with this content hash is already in the library",
          "name": "AlreadyExists"
        },
        {
          "description": "The file exceeds the per-file size limit",
          "name": "TooLarge"
        },
        {
          "description": "The upload would take the library over its total storage quota",
          "name": "QuotaExceeded"
        },
        {
          "description": "Too many uploads are being processed; retry shortly",
          "name": "Busy"
        }
      ],
      "input": {
        "encoding": "application/epub+zip,application/x-mobipocket-ebook,application/vnd.amazon.ebook,application/vnd.amazon.mobi8-ebook,application/x-fictionbook+xml,application/vnd.comicbook+zip,application/x-cbz,application/zip,application/octet-stream"
      },
      "output": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "book": {
              "ref": "buzz.bookhive.getPersonalLibrary#personalBookView",
              "type": "ref"
            },
            "storageQuotaBytes": {
              "description": "Total bytes this user is allowed to store",
              "minimum": 0,
              "type": "integer"
            },
            "storageUsedBytes": {
              "description": "Total bytes stored for this user after the upload",
              "minimum": 0,
              "type": "integer"
            }
          },
          "required": [
            "book",
            "storageUsedBytes",
            "storageQuotaBytes"
          ],
          "type": "object"
        }
      },
      "parameters": {
        "properties": {
          "filename": {
            "description": "Original file name including extension. Required: the extension is the only thing distinguishing the zip-container formats (.epub / .cbz / .fb2.zip) from each other, and it is the key used to match e-reader sync documents to this file.",
            "maxLength": 512,
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "filename"
        ],
        "type": "params"
      },
      "type": "procedure"
    }
  },
  "id": "buzz.bookhive.uploadPersonalBook",
  "lexicon": 1
}
```
