# Books and Bookshelves Page: https://microblog.dev/api/books/ API base URL: https://micro.blog Endpoints for book search, bookshelves, bookshelf assignments, and reading goals. ## Endpoints ### GET /books/search URL: `https://micro.blog/books/search` Searches books for discovery and bookshelf workflows. Query parameters: - `q` (string, required): Search query or Micropub query type. Example: `Less is more` Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X GET "https://micro.blog/books/search?q=Less+is+more" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns a JSON Feed response. Example response: ```json { "version": "https://jsonfeed.org/version/1.1", "title": "Micro.blog", "home_page_url": "https://micro.blog", "feed_url": "https://micro.blog/books/search?q=Less+is+more", "_microblog": { "about": "https://micro.blog/about/api" }, "items": [ { "id": 321, "title": "Book title", "content_text": "Description text", "url": "https://micro.blog/books/9780143127796", "image": "https://example.com/cover.jpg", "date_published": "2026-04-26T12:00:00+00:00", "authors": [ { "name": "Author Name" } ], "_microblog": { "isbn": "9780143127796" } } ] } ``` ### POST /books URL: `https://micro.blog/books` Creates a book and assigns it to a bookshelf. Query parameters: - `title` (string, required): Title value. Example: `Book title` - `author` (string, optional): Author name. Example: `Author Name` - `isbn` (string, required): Book ISBN. Example: `9780143127796` - `bookshelf_id` (integer, required): Bookshelf identifier. Example: `654` - `cover_url` (string, optional): Cover image URL. Example: `https://example.com/cover.jpg` Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X POST "https://micro.blog/books?title=Book+title&isbn=9780143127796&bookshelf_id=654" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns an empty JSON object on success. Example response: ```json {} ``` ### GET /books/bookshelves URL: `https://micro.blog/books/bookshelves` Returns bookshelves in JSON Feed format. Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X GET "https://micro.blog/books/bookshelves" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns a JSON Feed response. Example response: ```json { "version": "https://jsonfeed.org/version/1.1", "title": "Micro.blog - Bookshelves", "home_page_url": "https://micro.blog", "feed_url": "https://micro.blog/books/bookshelves", "_microblog": { "about": "https://micro.blog/about/api" }, "items": [ { "id": 654, "title": "Currently reading", "content_text": "", "url": "https://micro.blog/account/bookshelves/654", "date_published": "2026-04-26T12:00:00+00:00", "_microblog": { "type": "reading", "books_count": 3 } } ] } ``` ### POST /books/bookshelves URL: `https://micro.blog/books/bookshelves` Creates a bookshelf. Query parameters: - `name` (string, required): Name value. Example: `Reading` Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X POST "https://micro.blog/books/bookshelves?name=Reading" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns an empty JSON object on success. Example response: ```json {} ``` ### POST /books/bookshelves/{bookshelf_id}/assign URL: `https://micro.blog/books/bookshelves/{bookshelf_id}/assign` Assigns an existing or resolved book to a bookshelf. Path parameters: - `bookshelf_id` (integer, required): Bookshelf identifier. Example: `654` Query parameters: - `book_id` (integer, optional): Book identifier. Example: `321` - `isbn` (string, optional): Book ISBN. Example: `9780143127796` - `title` (string, optional): Title value. Example: `Book title` - `author` (string, optional): Author name. Example: `Author Name` - `description` (string, optional): Description text. Example: `Description text` - `cover_url` (string, optional): Cover image URL. Example: `https://example.com/cover.jpg` Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X POST "https://micro.blog/books/bookshelves/{bookshelf_id}/assign" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns an empty JSON object on success. Example response: ```json {} ``` ### POST /books/bookshelves/{bookshelf_id}/cover/{book_id} URL: `https://micro.blog/books/bookshelves/{bookshelf_id}/cover/{book_id}` Updates a book cover URL. Path parameters: - `bookshelf_id` (integer, required): Bookshelf identifier. Example: `654` - `book_id` (integer, required): Book identifier. Example: `321` Query parameters: - `cover_url` (string, required): Cover image URL. Example: `https://example.com/cover.jpg` Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X POST "https://micro.blog/books/bookshelves/{bookshelf_id}/cover/{book_id}?cover_url=https%3A%2F%2Fexample.com%2Fcover.jpg" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns an empty JSON object on success. Example response: ```json {} ``` ### DELETE /books/bookshelves/{bookshelf_id}/remove/{book_id} URL: `https://micro.blog/books/bookshelves/{bookshelf_id}/remove/{book_id}` Removes a book from a bookshelf. Path parameters: - `bookshelf_id` (integer, required): Bookshelf identifier. Example: `654` - `book_id` (integer, required): Book identifier. Example: `321` Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X DELETE "https://micro.blog/books/bookshelves/{bookshelf_id}/remove/{book_id}" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns an empty JSON object on success. Example response: ```json {} ``` ### POST /books/bookshelves/{bookshelf_id}/save/{book_id} URL: `https://micro.blog/books/bookshelves/{bookshelf_id}/save/{book_id}` Updates the finished date for a book on a bookshelf. Path parameters: - `bookshelf_id` (integer, required): Bookshelf identifier. Example: `654` - `book_id` (integer, required): Book identifier. Example: `321` Query parameters: - `date_finished` (string, required): Date the book was finished. Example: `2026-04-26` Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X POST "https://micro.blog/books/bookshelves/{bookshelf_id}/save/{book_id}?date_finished=2026-04-26" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns an empty JSON object on success. Example response: ```json {} ``` ### GET /books/bookshelves/{id} URL: `https://micro.blog/books/bookshelves/{id}` Returns books in a bookshelf in JSON Feed format. Path parameters: - `id` (integer, required): Resource identifier. Example: `12345` Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X GET "https://micro.blog/books/bookshelves/{id}" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns a JSON Feed response. Example response: ```json { "version": "https://jsonfeed.org/version/1.1", "title": "Micro.blog - Currently reading", "home_page_url": "https://micro.blog", "feed_url": "https://micro.blog/books/bookshelves/654", "_microblog": { "about": "https://micro.blog/about/api" }, "items": [ { "id": 321, "title": "Book title", "content_text": "Description text", "url": "https://micro.blog/books/9780143127796", "image": "https://example.com/cover.jpg", "date_published": "2026-04-26T12:00:00+00:00", "authors": [ { "name": "Author Name" } ], "_microblog": { "isbn": "9780143127796" } } ] } ``` ### POST /books/bookshelves/{id} URL: `https://micro.blog/books/bookshelves/{id}` Renames a bookshelf. Path parameters: - `id` (integer, required): Resource identifier. Example: `12345` Query parameters: - `name` (string, required): Name value. Example: `Reading` Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X POST "https://micro.blog/books/bookshelves/{id}?name=Reading" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns an empty JSON object on success. Example response: ```json {} ``` ### GET /books/goals URL: `https://micro.blog/books/goals` Returns reading goals in JSON Feed format. Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X GET "https://micro.blog/books/goals" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns a JSON Feed response. Example response: ```json { "version": "https://jsonfeed.org/version/1.1", "title": "Micro.blog - Goals", "home_page_url": "https://micro.blog", "feed_url": "https://micro.blog/books/goals", "_microblog": { "about": "https://micro.blog/about/api" }, "items": [ { "id": 123, "title": "Reading 2026", "content_text": "6 of 24 books", "_microblog": { "goal_year": 2026, "goal_value": 24, "goal_progress": 6, "isbns": [ "9780143127796" ] } } ] } ``` ### GET /books/goals/{id} URL: `https://micro.blog/books/goals/{id}` Returns books for one reading goal in JSON Feed format. Path parameters: - `id` (integer, required): Resource identifier. Example: `12345` Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X GET "https://micro.blog/books/goals/{id}" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns a JSON Feed response. Example response: ```json { "version": "https://jsonfeed.org/version/1.1", "title": "Micro.blog - Reading 2026", "home_page_url": "https://micro.blog", "feed_url": "https://micro.blog/books/goals/123", "_microblog": { "about": "https://micro.blog/about/api" }, "items": [ { "id": 321, "title": "Book title", "content_text": "", "url": "https://micro.blog/books/9780143127796", "image": "https://example.com/cover.jpg", "date_published": "2026-04-26T12:00:00+00:00", "authors": [ { "name": "Author Name" } ], "_microblog": { "isbn": "9780143127796" } } ] } ``` ### POST /books/goals/{id} URL: `https://micro.blog/books/goals/{id}` Updates a reading goal target or progress. Path parameters: - `id` (integer, required): Resource identifier. Example: `12345` Query parameters: - `value` (integer, optional): Goal target value. Example: `24` - `progress` (integer, optional): Goal progress value. Example: `5` Header parameters: - `Authorization` (string, required): Bearer token for authentication. Format: `Bearer {token}`. Example: `Bearer EF7BB9BCAC1F6D561C93` Example request: ```sh curl -X POST "https://micro.blog/books/goals/{id}" \ --header "Authorization: Bearer EF7BB9BCAC1F6D561C93" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns a JSON response. Example response: ```json { "id": 123, "name": "Reading goal", "year": 2026, "value": 24, "progress": 6 } ``` ### POST /books/openlibrary/signin URL: `https://micro.blog/books/openlibrary/signin` Signs in to Open Library and returns the session value used by book cover workflows. Query parameters: - `username` (string, required): Open Library username. Example: `openlibrary-user` - `password` (string, required): Open Library password. Example: `openlibrary-password` Example request: ```sh curl -X POST "https://micro.blog/books/openlibrary/signin?username=openlibrary-user&password=openlibrary-password" ``` Response: - Status: 200 - Content-Type: `application/json` - Description: Returns the Open Library session path when sign-in succeeds, or an empty string when no session is available. Example response: ```json { "session": "/people/openlibrary-user-ABCDEFGH123456789" } ```