{"openapi":"3.1.0","info":{"title":"flightbooks API","version":"1.0.0","description":"Programmatic access to flightbooks: book & chapter CRUD, image upload, and PDF build/download. Authenticate with a bearer token (fb_live_...) created in the web app under Settings."},"servers":[{"url":"http://flightbooks.pub/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"fb_live"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]},"Book":{"type":"object","properties":{"id":{"type":"string"},"user_id":{"type":"string"},"title":{"type":"string"},"author":{"type":"string"},"config":{"type":"string","description":"JSON string. Keys: paper (JIS-B5|A5|JIS-A4|TABLET), cover/toc/imprint/introduction/conclusion (booleans, default true), first_release_date, print_at, copyright (colophon strings)."},"created_at":{"type":"integer"},"updated_at":{"type":"integer"}}},"Chapter":{"type":"object","properties":{"id":{"type":"string"},"book_id":{"type":"string"},"kind":{"type":"string","enum":["introduction","chapter","conclusion"]},"sort_order":{"type":"integer"},"title":{"type":"string"},"body_md":{"type":"string","description":"Chapter body in Markdown."},"updated_at":{"type":"integer"}}},"Asset":{"type":"object","properties":{"id":{"type":"string"},"book_id":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"size":{"type":"integer"},"created_at":{"type":"integer"}}},"Build":{"type":"object","properties":{"id":{"type":"string"},"book_id":{"type":"string"},"status":{"type":"string","enum":["running","done","error"]},"r2_key":{"type":["string","null"]},"error_log":{"type":["string","null"]},"settings":{"type":["string","null"],"description":"JSON snapshot of this build's paper size, included pages, optimize, and draft_stamp settings."},"created_at":{"type":"integer"},"finished_at":{"type":["integer","null"]}}}}},"paths":{"/books":{"get":{"summary":"List your books","responses":{"200":{"description":"Books","content":{"application/json":{"schema":{"type":"object","properties":{"books":{"type":"array","items":{"$ref":"#/components/schemas/Book"}}}}}}}}},"post":{"summary":"Create a book","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"author":{"type":"string"}}}}}},"responses":{"200":{"description":"Created book","content":{"application/json":{"schema":{"type":"object","properties":{"book":{"$ref":"#/components/schemas/Book"}}}}}}}}},"/books/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a book","responses":{"200":{"description":"Book","content":{"application/json":{"schema":{"type":"object","properties":{"book":{"$ref":"#/components/schemas/Book"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a book","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"author":{"type":"string"},"config":{"type":"object","description":"Merged into the stored config JSON."}}}}}},"responses":{"200":{"description":"Updated book","content":{"application/json":{"schema":{"type":"object","properties":{"book":{"$ref":"#/components/schemas/Book"}}}}}}}},"delete":{"summary":"Delete a book (cascades chapters/assets/builds)","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/books/{bookId}/chapters":{"parameters":[{"name":"bookId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List chapters of a book","responses":{"200":{"description":"Chapters","content":{"application/json":{"schema":{"type":"object","properties":{"chapters":{"type":"array","items":{"$ref":"#/components/schemas/Chapter"}}}}}}}}},"post":{"summary":"Add a chapter","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"kind":{"type":"string","enum":["introduction","chapter","conclusion"],"default":"chapter"}}}}}},"responses":{"200":{"description":"Created chapter","content":{"application/json":{"schema":{"type":"object","properties":{"chapter":{"$ref":"#/components/schemas/Chapter"}}}}}}}}},"/books/{bookId}/chapters/order":{"parameters":[{"name":"bookId","in":"path","required":true,"schema":{"type":"string"}}],"put":{"summary":"Reorder chapters","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"},"description":"All chapter ids of the book, in the desired order."}}}}}},"responses":{"200":{"description":"Reordered","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/chapters/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a chapter","responses":{"200":{"description":"Chapter","content":{"application/json":{"schema":{"type":"object","properties":{"chapter":{"$ref":"#/components/schemas/Chapter"}}}}}}}},"patch":{"summary":"Update a chapter (title / body_md / kind)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"body_md":{"type":"string"},"kind":{"type":"string","enum":["introduction","chapter","conclusion"]}}}}}},"responses":{"200":{"description":"Updated chapter","content":{"application/json":{"schema":{"type":"object","properties":{"chapter":{"$ref":"#/components/schemas/Chapter"},"preview_url":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a chapter","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/books/{bookId}/assets":{"parameters":[{"name":"bookId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List image assets of a book","responses":{"200":{"description":"Assets","content":{"application/json":{"schema":{"type":"object","properties":{"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}}}}}}}}},"post":{"summary":"Upload an image (multipart, field `file`)","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Uploaded asset. `markdown` is the ![](asset://id) snippet to embed.","content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"$ref":"#/components/schemas/Asset"},"markdown":{"type":"string"}}}}}}}}},"/books/{bookId}/assets/import":{"parameters":[{"name":"bookId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Import an image from a URL","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"alt":{"type":"string"}}}}}},"responses":{"200":{"description":"Imported asset","content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"$ref":"#/components/schemas/Asset"},"markdown":{"type":"string"}}}}}}}}},"/assets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an asset","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/books/{bookId}/builds":{"parameters":[{"name":"bookId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List builds of a book (newest first)","responses":{"200":{"description":"Builds","content":{"application/json":{"schema":{"type":"object","properties":{"builds":{"type":"array","items":{"$ref":"#/components/schemas/Build"}}}}}}}}},"post":{"summary":"Build a PDF (synchronous; returns when the render finishes)","requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Overrides apply for this generation only, on top of the book's saved config; paper and the page-inclusion flags (cover/toc/introduction/conclusion/imprint) are also saved back as the book's new defaults.","properties":{"optimize":{"type":"boolean","description":"Downscale/recompress images for a smaller distributable PDF."},"draft_stamp":{"type":"boolean","description":"Print a DRAFT stamp with the generation timestamp in each page's margin."},"paper":{"type":"string","description":"Paper size override, e.g. \"JIS-B5\" | \"A5\" | \"JIS-A4\" | \"TABLET\"."},"cover":{"type":"boolean","description":"Override whether to include the cover page."},"toc":{"type":"boolean","description":"Override whether to include the table of contents."},"introduction":{"type":"boolean","description":"Override whether to include the introduction chapter."},"conclusion":{"type":"boolean","description":"Override whether to include the conclusion chapter."},"imprint":{"type":"boolean","description":"Override whether to include the imprint (colophon) page."}}}}}},"responses":{"200":{"description":"Finished build. Download via /builds/{id}/download.","content":{"application/json":{"schema":{"type":"object","properties":{"build":{"$ref":"#/components/schemas/Build"},"warnings":{"type":"integer"}}}}}},"400":{"description":"No chapters, or a referenced image is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/builds/{id}/download":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a finished build's PDF","responses":{"200":{"description":"PDF bytes","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not found or not finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}