Build with Micro.blog logo
Build with Micro.blog
API Documentation

Books and Bookshelves

View .md

Endpoints for book search, bookshelves, bookshelf assignments, reading goals, and the reading calendar. Authenticated requests that read data need the read scope, POST requests need write, and DELETE requests need delete. GET /books/authors/{id} also works without a token.

BASE URL https://micro.blog
GET /books/search

Searches the signed-in user’s books and Micro.blog’s book catalog. Pass format=jsonfeed to get JSON. Without it, the endpoint returns the HTML search page, or redirects to the book page when q is an ISBN.

Note: Books already on one of the user’s bookshelves come first. A catalog result that the user has not saved uses its ISBN as id. _microblog can also include author_id (for GET /books/authors/{id}), genres, background_url, and background_color.

Example Request

curl -X GET "https://micro.blog/books/search?q=Less+is+more&format=jsonfeed" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
q string Required Title, author, or ISBN to search for.
Example: Less is more
format string Required Use jsonfeed to return a JSON Feed.
Example: jsonfeed
count integer Optional Maximum number of catalog results for a title or author search, up to 10. Defaults to 5.
Example: 10

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Response

200 OK application/json

Returns a JSON Feed of matching books.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Book Search",
  "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",
        "author_id": 42
      }
    }
  ]
}
POST /books

Adds a book to a bookshelf. Pass id instead to update a book the user already has.

Note: Errors: 422 with {"error": "Books must have an ISBN."} when the ISBN is missing or empty, and 404 when the bookshelf or book is not found.

Example Request

curl -X POST "https://micro.blog/books?title=Book+title&isbn=9780143127796&bookshelf_id=654" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
isbn string Required Book ISBN. Optional when updating with id.
Example: 9780143127796
bookshelf_id integer Required Bookshelf to add the book to. Optional when updating with id.
Example: 654
title string Optional Book title.
Example: Book title
author string Optional Author name.
Example: Author Name
cover_url string Optional Cover image URL. When omitted on create, Micro.blog looks up a cover by ISBN.
Example: https://example.com/cover.jpg
genres string Optional Comma-separated genre names. genre is also accepted.
Example: Fiction, Mystery
id integer Optional ID of one of the user’s books to update instead of creating a new one. Only the fields you send are changed.
Example: 321

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Response

200 OK application/json

Returns an empty JSON object on success.

Example Response

{}
GET /books/bookshelves

Returns the user’s bookshelves in JSON Feed format. The default bookshelves are created the first time a user has none.

Example Request

curl -X GET "https://micro.blog/books/bookshelves" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Response

200 OK application/json

Returns a JSON Feed of bookshelves. _microblog.type is reading, to-read, finished, or dnf for the built-in shelves and null for custom ones.

Example Response

{
  "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

Creates a bookshelf. The names Currently reading, Want to read, Finished reading, and Did not finish create the matching built-in shelf type. A book can only be on one built-in shelf at a time.

Example Request

curl -X POST "https://micro.blog/books/bookshelves?name=Favorites" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
name string Required Bookshelf name.
Example: Favorites

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Response

200 OK application/json

Returns an empty JSON object on success.

Example Response

{}
POST /books/bookshelves/{bookshelf_id}/assign

Adds a book to a bookshelf. Pass book_id for a book from search results or another shelf, or pass isbn with the book details. Adding a book to a built-in shelf removes it from the other built-in shelves, and adding it to Finished reading sets its finished date if it has none.

Note: Errors: 404 with {"error": "Bookshelf not found"} or {"error": "Book not found"}, and 422 with {"error": "Books must have an ISBN."} when no ISBN can be found.

Example Request

curl -X POST "https://micro.blog/books/bookshelves/654/assign?book_id=321" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
book_id integer Optional Book identifier. When set, the book’s own ISBN and details are used and the other fields are ignored.
Example: 321
isbn string Optional Book ISBN. Required when book_id is not set.
Example: 9780143127796
title string Optional Book title.
Example: Book title
author string Optional Author name.
Example: Author Name
description string Optional Book description.
Example: Description text
cover_url string Optional Cover image URL.
Example: https://example.com/cover.jpg

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
bookshelf_id integer Required Bookshelf identifier.
Example: 654

Response

200 OK application/json

Returns an empty JSON object on success.

Example Response

{}
POST /books/bookshelves/{bookshelf_id}/cover/{book_id}

Changes the cover image for a book on a bookshelf.

Example Request

curl -X POST "https://micro.blog/books/bookshelves/654/cover/321?cover_url=https%3A%2F%2Fexample.com%2Fcover.jpg" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
cover_url string Required Cover image URL.
Example: https://example.com/cover.jpg

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
bookshelf_id integer Required Bookshelf that contains the book.
Example: 654
book_id integer Required Book identifier.
Example: 321

Response

200 OK application/json

Returns an empty JSON object on success, or 404 when the bookshelf or book is not found.

Example Response

{}
DELETE /books/bookshelves/{bookshelf_id}/remove/{book_id}

Removes a book from a bookshelf.

Example Request

curl -X DELETE "https://micro.blog/books/bookshelves/654/remove/321" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
bookshelf_id integer Required Bookshelf identifier.
Example: 654
book_id integer Required Book identifier.
Example: 321

Response

200 OK application/json

Returns an empty JSON object on success, or 404 with an error message when the bookshelf or book is not found.

Example Response

{}
POST /books/bookshelves/{bookshelf_id}/save/{book_id}

Sets or clears the finished date for a book on a bookshelf.

Example Request

curl -X POST "https://micro.blog/books/bookshelves/654/save/321?date_finished=2026-04-26" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
date_finished string Optional Date the book was finished. A date without a time zone is read in the user’s time zone. Leave empty to clear the finished date.
Example: 2026-04-26

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
bookshelf_id integer Required Bookshelf that contains the book.
Example: 654
book_id integer Required Book identifier.
Example: 321

Response

200 OK application/json

Returns an empty JSON object on success. Returns 422 with {"error": "Could not parse finished date."} for an invalid date, and 404 when the bookshelf or book is not found.

Example Response

{}
GET /books/bookshelves/{id}

Returns the books on a bookshelf in JSON Feed format, most recently added first.

Example Request

curl -X GET "https://micro.blog/books/bookshelves/654" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
id integer Required Bookshelf identifier.
Example: 654

Response

200 OK application/json

Returns a JSON Feed of books, or 404 when the bookshelf is not found. date_published is the finished date when set. _microblog can also include author_id, genres, background_url, and background_color.

Example Response

{
  "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",
        "author_id": 42,
        "genres": [
          "Fiction"
        ]
      }
    }
  ]
}
POST /books/bookshelves/{id}

Renames a bookshelf.

Example Request

curl -X POST "https://micro.blog/books/bookshelves/654?name=Favorites" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
name string Required New bookshelf name.
Example: Favorites

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
id integer Required Bookshelf identifier.
Example: 654

Response

200 OK application/json

Returns an empty JSON object on success, or 404 when the bookshelf is not found.

Example Response

{}
GET /books/goals

Returns the user’s reading goals in JSON Feed format, newest year first. A goal for the current year is created if it is missing.

Example Request

curl -X GET "https://micro.blog/books/goals" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Response

200 OK application/json

Returns a JSON Feed of goals.

Example Response

{
  "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}

Returns the books counted toward one reading goal in JSON Feed format.

Example Request

curl -X GET "https://micro.blog/books/goals/123" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
id integer Required Goal identifier.
Example: 123

Response

200 OK application/json

Returns a JSON Feed of books, or 404 when the goal is not found.

Example Response

{
  "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}

Updates a reading goal’s target or progress.

Example Request

curl -X POST "https://micro.blog/books/goals/123?value=24" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
value integer Optional Number of books to read this year.
Example: 24
progress integer Optional Number of books read so far.
Example: 6

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
id integer Required Goal identifier.
Example: 123

Response

200 OK application/json

Returns the updated goal, or 404 when the goal is not found.

Example Response

{
  "id": 123,
  "name": "Reading 2026",
  "year": 2026,
  "value": 24,
  "progress": 6
}
GET /books/calendar

Returns the books the user finished in the last two years, grouped by month, for a reading calendar. Requires an app token. A signed-in web session gets 401.

Example Request

curl -X GET "https://micro.blog/books/calendar" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Header Parameters

Name Type Required Description
Authorization string Required Bearer token for authentication. Format: Bearer {token}.

Response

200 OK application/json

Returns months newest first. week_start is sun or mon based on the user’s time zone. link_url is the user’s blog post about the book, or an empty string.

Example Response

{
  "title": "Book Calendar",
  "week_start": "mon",
  "months": [
    {
      "year": 2026,
      "month": 4,
      "month_key": "2026-04",
      "books": [
        {
          "id": 321,
          "title": "Book title",
          "author": "Author Name",
          "isbn": "9780143127796",
          "cover_url": "https://example.com/cover.jpg",
          "link_url": "https://vincent.micro.blog/2026/04/26/finished-reading.html",
          "background_url": "",
          "background_color": "#4a5a6a",
          "page_count": 320,
          "finished_date": "2026-04-26",
          "finished_label": "Apr 26",
          "day": 26
        }
      ],
      "book_count": 1,
      "page_count": 320,
      "background_url": "",
      "background_color": "#4a5a6a"
    }
  ]
}
GET /books/authors/{id}

Returns an author’s books in JSON Feed format. Pass format=jsonfeed to get JSON; without it, the endpoint returns the HTML author page. Authentication is optional. With a token, the user’s own copies of each book are used where they exist.

Example Request

curl -X GET "https://micro.blog/books/authors/42?format=jsonfeed"

Query Parameters

Name Type Required Description
format string Required Use jsonfeed to return a JSON Feed.
Example: jsonfeed

Header Parameters

Name Type Required Description
Authorization string Optional Bearer token for authentication. Format: Bearer {token}.

Path Parameters

Name Type Required Description
id integer Required Author identifier, from _microblog.author_id on a book.
Example: 42

Response

200 OK application/json

Returns a JSON Feed of books, or 404 when the author is not found.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Books by Author Name",
  "home_page_url": "https://micro.blog/books/authors/42",
  "feed_url": "https://micro.blog/books/authors/42?format=jsonfeed",
  "_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",
        "author_id": 42
      }
    }
  ]
}