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

Books and Bookshelves

View .md

Endpoints for book search, bookshelves, bookshelf assignments, and reading goals.

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

Searches books for discovery and bookshelf workflows.

Example Request

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

Query Parameters

Name Type Required Description
q string Required Search query or Micropub query type.
Example: Less is more

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 response.

Example Response

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

Creates a book and assigns it to a bookshelf.

Example Request

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

Query Parameters

Name Type Required Description
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

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 bookshelves in JSON Feed format.

Example Request

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

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 response.

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.

Example Request

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

Query Parameters

Name Type Required Description
name string Required Name value.
Example: Reading

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

Assigns an existing or resolved book to a bookshelf.

Example Request

curl -X POST "https://micro.blog/books/bookshelves/{bookshelf_id}/assign" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"

Query Parameters

Name Type Required Description
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

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}

Updates a book cover URL.

Example Request

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"

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 identifier.
Example: 654
book_id integer Required Book identifier.
Example: 321

Response

200 OK application/json

Returns an empty JSON object on success.

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/{bookshelf_id}/remove/{book_id}" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"

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.

Example Response

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

Updates the finished date for a book on a bookshelf.

Example Request

curl -X POST "https://micro.blog/books/bookshelves/{bookshelf_id}/save/{book_id}?date_finished=2026-04-26" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"

Query Parameters

Name Type Required Description
date_finished string Required Date the book was finished.
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 identifier.
Example: 654
book_id integer Required Book identifier.
Example: 321

Response

200 OK application/json

Returns an empty JSON object on success.

Example Response

{}
GET /books/bookshelves/{id}

Returns books in a bookshelf in JSON Feed format.

Example Request

curl -X GET "https://micro.blog/books/bookshelves/{id}" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"

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 Resource identifier.
Example: 12345

Response

200 OK application/json

Returns a JSON Feed response.

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"
      }
    }
  ]
}
POST /books/bookshelves/{id}

Renames a bookshelf.

Example Request

curl -X POST "https://micro.blog/books/bookshelves/{id}?name=Reading" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"

Query Parameters

Name Type Required Description
name string Required Name value.
Example: Reading

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 Resource identifier.
Example: 12345

Response

200 OK application/json

Returns an empty JSON object on success.

Example Response

{}
GET /books/goals

Returns reading goals in JSON Feed format.

Example Request

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

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 response.

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 books for one reading goal in JSON Feed format.

Example Request

curl -X GET "https://micro.blog/books/goals/{id}" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"

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 Resource identifier.
Example: 12345

Response

200 OK application/json

Returns a JSON Feed response.

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 target or progress.

Example Request

curl -X POST "https://micro.blog/books/goals/{id}" \
  --header "Authorization: Bearer EF7BB9BCAC1F6D561C93"

Query Parameters

Name Type Required Description
value integer Optional Goal target value.
Example: 24
progress integer Optional Goal progress value.
Example: 5

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 Resource identifier.
Example: 12345

Response

200 OK application/json

Returns a JSON response.

Example Response

{
  "id": 123,
  "name": "Reading goal",
  "year": 2026,
  "value": 24,
  "progress": 6
}
POST /books/openlibrary/signin

Signs in to Open Library and returns the session value used by book cover workflows.

Example Request

curl -X POST "https://micro.blog/books/openlibrary/signin?username=openlibrary-user&password=openlibrary-password"

Query Parameters

Name Type Required Description
username string Required Open Library username.
Example: openlibrary-user
password string Required Open Library password.
Example: openlibrary-password

Response

200 OK application/json

Returns the Open Library session path when sign-in succeeds, or an empty string when no session is available.

Example Response

{
  "session": "/people/openlibrary-user-ABCDEFGH123456789"
}