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

Discover

View .md

Endpoints for Micro.blog’s curated Discover timeline, topic feeds, featured photos, books, best sellers, and slow reads. No authentication is required and every endpoint allows cross-origin requests.

Note: Sending an app token is optional. With one, posts from users you mute are left out and fields such as is_favorite reflect your account. A token sent to these endpoints needs the read scope, or the request fails with 403.
BASE URL https://micro.blog
GET /posts/discover

Returns the 50 most recent featured posts in JSON Feed format, plus the list of Discover topics in _microblog.tagmoji. Page backwards with before_id.

Example Request

curl -X GET "https://micro.blog/posts/discover"

Query Parameters

Name Type Required Description
before_id integer Optional Only return posts published before this post. Use the last id from the previous page.
Example: 77494371

Header Parameters

Name Type Required Description
Authorization string Optional Optional bearer token. Format: Bearer {token}. Needs the read scope when sent.

Response

200 OK application/json

Returns a JSON Feed object. Items have the same shape as GET /posts/all. Each tagmoji entry’s name is the topic to pass to GET /posts/discover/{topic}; the photos topic comes first, then featured topics, then the rest.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Discover",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/discover",
  "_microblog": {
    "about": "https://micro.blog/about/api",
    "tagmoji": [
      {
        "name": "photos",
        "title": "Photos",
        "emoji": "📷",
        "is_featured": true
      },
      {
        "name": "music",
        "title": "Music",
        "emoji": "🎵",
        "is_featured": true
      }
    ]
  },
  "items": [
    {
      "id": "77494371",
      "content_html": "<p>Spring is finally here.</p>",
      "url": "https://www.manton.org/2026/04/26/spring-is-finally.html",
      "date_published": "2026-04-26T12:00:00+00:00",
      "author": {
        "name": "Manton Reece",
        "url": "https://manton.org",
        "avatar": "https://avatars.micro.blog/avatars/2026/22/3.jpg",
        "_microblog": {
          "username": "manton"
        }
      },
      "_microblog": {
        "date_relative": "12:00",
        "date_timestamp": 1777204800,
        "is_favorite": false,
        "is_bookmark": false,
        "is_deletable": false,
        "is_conversation": false,
        "is_linkpost": false,
        "is_mention": false
      }
    }
  ]
}
GET /posts/discover/{topic}

Returns up to 40 posts from a Discover topic, newest first, in JSON Feed format. Page backwards with before_id. An unknown topic returns an empty feed.

Note: The photos, books, and slowreads topics have their own endpoints, which match first: GET /posts/discover/photos, GET /posts/discover/books, and GET /posts/discover/slowreads. Their item counts and paging differ from this endpoint, so use those pages for them.

Example Request

curl -X GET "https://micro.blog/posts/discover/music?before_id=77494371"

Query Parameters

Name Type Required Description
before_id integer Optional Only return posts that come after this post in the topic. Use the last id from the previous page.
Example: 77494371

Header Parameters

Name Type Required Description
Authorization string Optional Optional bearer token. Format: Bearer {token}. Needs the read scope when sent.

Path Parameters

Name Type Required Description
topic string Required Topic name from _microblog.tagmoji in GET /posts/discover.
Example: music

Response

200 OK application/json

Returns a JSON Feed object. Items have the same shape as GET /posts/all.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Discover music",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/discover/music",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": []
}
GET /posts/discover/photos

Returns up to 40 recently featured photo posts in JSON Feed format. There is no paging.

Example Request

curl -X GET "https://micro.blog/posts/discover/photos"

Header Parameters

Name Type Required Description
Authorization string Optional Optional bearer token. Format: Bearer {token}. Needs the read scope when sent.

Response

200 OK application/json

Returns a JSON Feed object. Items have the same shape as GET /posts/all. The feed’s title and feed_url don’t name the photos topic.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Discover ",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/discover/",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": []
}
GET /posts/discover/books

Returns the 60 most recent posts about books from Micro.blog users, newest first, in JSON Feed format. There is no paging.

Example Request

curl -X GET "https://micro.blog/posts/discover/books"

Header Parameters

Name Type Required Description
Authorization string Optional Optional bearer token. Format: Bearer {token}. Needs the read scope when sent.

Response

200 OK application/json

Returns a JSON Feed object. Each item has the post plus the book’s isbn, book_title, book_author, and cover_url in _microblog. When Micro.blog knows them, _microblog also has author_id, genres, background_url, and background_color. The author appears in both authors and author.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Discover books",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/discover/books",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": "77494371",
      "content_html": "<p>Finished reading: <a href=\"https://micro.blog/books/9780441172719\">Dune</a> by Frank Herbert 📚</p>",
      "url": "https://micro.blog/books/9780441172719",
      "date_published": "2026-04-26T12:00:00+00:00",
      "authors": [
        {
          "name": "Manton Reece",
          "url": "https://manton.org",
          "avatar": "https://avatars.micro.blog/avatars/2026/22/3.jpg",
          "_microblog": {
            "username": "manton"
          }
        }
      ],
      "author": {
        "name": "Manton Reece",
        "url": "https://manton.org",
        "avatar": "https://avatars.micro.blog/avatars/2026/22/3.jpg",
        "_microblog": {
          "username": "manton"
        }
      },
      "_microblog": {
        "isbn": "9780441172719",
        "book_title": "Dune",
        "book_author": "Frank Herbert",
        "cover_url": "https://micro.blog/books/9780441172719/cover.jpg",
        "date_relative": "12:00",
        "date_timestamp": 1777204800,
        "is_favorite": false,
        "is_bookmark": false,
        "is_deletable": false,
        "is_conversation": false,
        "is_linkpost": false,
        "is_mention": false,
        "author_id": 345,
        "genres": [
          "Science Fiction"
        ]
      }
    }
  ]
}
GET /posts/discover/books/bestsellers

Returns a New York Times best seller list in JSON Feed format, from a copy Micro.blog refreshes regularly.

Example Request

curl -X GET "https://micro.blog/posts/discover/books/bestsellers?list=hardcover-nonfiction"

Query Parameters

Name Type Required Description
list string Optional List slug. Micro.blog keeps these lists: combined-print-and-e-book-fiction, combined-print-and-e-book-nonfiction, hardcover-fiction, hardcover-nonfiction, trade-fiction-paperback, paperback-nonfiction, young-adult-hardcover, series-books, and science-fiction-and-fantasy. An unknown slug returns an empty feed.
Example: hardcover-nonfiction

Response

200 OK application/json

Returns a JSON Feed object. Each item is a book, not a post, with id set to the ISBN and url pointing to the book’s page on Micro.blog. _microblog.rank is the book’s place on the list. When the book is in Micro.blog’s catalog, content_text holds its description and _microblog adds the same optional book fields as GET /posts/discover/books.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - NYT Best Sellers",
  "home_page_url": "https://micro.blog/discover/books/bestsellers?list=hardcover-nonfiction",
  "feed_url": "https://micro.blog/posts/discover/books/bestsellers?list=hardcover-nonfiction",
  "_microblog": {
    "about": "https://micro.blog/about/api",
    "list": "hardcover-nonfiction",
    "list_name": "Hardcover Nonfiction",
    "published_date": "2026-04-26"
  },
  "items": [
    {
      "id": "9780000000001",
      "title": "Example Book",
      "content_text": "A short description of the book.",
      "url": "https://micro.blog/books/9780000000001",
      "authors": [
        {
          "name": "Example Author"
        }
      ],
      "_microblog": {
        "isbn": "9780000000001",
        "book_title": "Example Book",
        "book_author": "Example Author",
        "cover_url": "https://example.com/covers/9780000000001.jpg",
        "rank": 1
      },
      "image": "https://example.com/covers/9780000000001.jpg"
    }
  ]
}
GET /posts/discover/slowreads

Returns up to 40 recent slow reads, longer blog posts picked by the Micro.blog team, newest first, in JSON Feed format. Page backwards with before_id.

Example Request

curl -X GET "https://micro.blog/posts/discover/slowreads"

Query Parameters

Name Type Required Description
before_id integer Optional Only return slow reads older than this one. Use the last id from the previous page; these IDs are slow read IDs, not post IDs.
Example: 4567

Response

200 OK application/json

Returns a JSON Feed object. content_html links to the article and includes its summary and a quote when there is one. author is the Micro.blog user who wrote it, and url is the article.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Discover slowreads",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/discover/slowreads",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": "4567",
      "content_html": "<p><a href=\"https://example.com/essay\">An Essay About the Open Web</a></p><p>Why personal sites still matter.</p>",
      "url": "https://example.com/essay",
      "date_published": "2026-04-26T12:00:00+00:00",
      "author": {
        "name": "Manton Reece",
        "url": "https://micro.blog/manton",
        "avatar": "https://avatars.micro.blog/avatars/2026/22/3.jpg",
        "_microblog": {
          "username": "manton"
        }
      },
      "_microblog": {
        "date_relative": "12:00",
        "date_timestamp": 1777204800,
        "is_favorite": false,
        "is_bookmark": false,
        "is_deletable": false,
        "is_conversation": false,
        "is_slowread": true,
        "is_linkpost": true,
        "is_mention": false
      }
    }
  ]
}