JSON API

February 14, 2017

The JSON API is based on JSON Feed, the same format as the JSON versions of the hosted site feeds. Micro.blog adds a few useful fields under an extension named _microblog. A response with posts looks like this:

{
  "title": "Micro.blog - Mentions", 
  "home_page_url": "https://micro.blog/mentions", 
  "feed_url": "https://micro.blog/posts/mentions", 
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": 123,
      "author": {
        "name": "Manton Reece", 
        "url": "http://manton.org", 
        "avatar": "http://www.gravatar.com/avatar/d848ac9a3c64d1b73563895892cb2819?s=96",
        "_microblog": {
          "username": "manton",
          "is_following": true
        }
      }, 
      "url": "https://micro.blog/manton/123", 
      "content_html": "<a href=\"https://micro.blog/manton\">@manton</a> Testing testing, hello world.", 
      "date_published": "2017-02-24T15:38:50-06:00", 
      "_microblog": {
        "is_deletable": true, 
        "is_favorite": false, 
        "date_relative": "3:38 pm"
      }
    }
  ]
}

The following endpoints are supported:

  • POST /account/signin — Pass email, app_name, and redirect_url parameters to let the user sign in via a confirmation email. Email help@micro.blog so we can enable this for your app. The user can also generate app tokens under Account → Edit Apps. Web apps should use IndieAuth for sign-in.
  • POST /account/verify — Accepts a temporary email sign-in token or an app token and returns an auth token and other details. See this help page about authentication.
  • GET /posts/all — JSON timeline for the signed-in user.
  • GET /posts/mentions — JSON mentions for the signed-in user.
  • GET /posts/favorites — JSON favorites for the signed-in user.
  • GET /posts/photos — Photos-only timeline for the signed-in user.
  • GET /posts/discover — JSON for featured posts.
  • GET /posts/discover/[collection] — Emoji collections, e.g. “books” and “music”.
  • GET /posts/[username] — JSON posts written by the given user.
  • GET /posts/conversation?id=[id] — JSON thread for a reply.
  • GET /posts/check?since_id=[id] — Check whether there are new posts in the timeline. The response also includes a suggestion for the number of seconds to wait before polling again.
  • POST /posts/favorites — Favorite a post. Pass an id.
  • DELETE /posts/favorites/[id] — Unfavorite a post. Pass an id.
  • POST /posts/reply — Post a reply to an id with content param.
  • DELETE /posts/[id] — Delete one of your posts, replies, or favorites for the given id.
  • POST /users/follow — Follow user with username param.
  • POST /users/unfollow — Unfollow username.
  • GET /users/is_following?username=[username] — Check if you’re following username.
  • GET /users/following/[username] — List of users username is following.
  • GET /users/discover/[username] — List of users username is following that signed-in user isn’t. The count for this is in discover_count from /posts/[username].
  • POST /micropub — Posting for a hosted microblog uses the Micropub API. See the documentation for more information about posting.

You should pass an authorization token as an HTTP header. This token can be retrieved via one of the authentication options. This is what sending the HTTP token looks like:

GET /posts/all
Authorization: Bearer 123456789

Note: IDs are 64-bit and unique across all posts, mentions, and favorites. Pass count, since_id, and before_id params for paging.