API Documentation

Microsub

Microsub endpoints for channels, timelines, feed subscriptions, and read state. Requests need an app token with the scope listed for each action.

BASE URL


                  https://micro.blog

GET


                          /microsub

Lists channels, reads a channel timeline, or lists the feeds followed in a channel. Requires the read scope.

Note: Every user has five built-in channels: default (Timeline), notifications (Mentions), bookmarks, discover, and feeds. Custom channels created with POST /microsub?action=channels are listed after them. Only feeds and custom channels hold feed subscriptions and report an unread count.

Note: Timeline items are newest first. Pass the last item’s _id from paging.after as after to load older items, or the first item’s _id from paging.before as before to load newer items. Items from feeds and custom channels also include name, summary, _is_read, _source, and photo, audio, or video arrays when the feed entry has media.

Note: Errors return {"error": "...", "error_description": "..."} with status 400 for an unsupported action or a channel without feeds, and 404 when the channel does not exist.

Example Request

curl -X GET "https://micro.blog/microsub?action=timeline&channel=default" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Examples

List channels

curl -X GET "https://micro.blog/microsub?action=channels" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

List the feeds followed in the Feeds channel

curl -X GET "https://micro.blog/microsub?action=follow&channel=feeds" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name	Type	Required	Description
`action`	string	Required	One of `channels`, `timeline`, or `follow`. `follow` lists the feeds followed in the channel. Example: `timeline`
`channel`	string	Optional	Channel `uid`. Required for `timeline` and `follow`. `follow` only accepts `feeds` or a custom channel. Example: `default`
`after`	string	Optional	Item `_id` to page from. Returns items older than this item. Example: `12345`
`before`	string	Optional	Item `_id` to page from. Returns items newer than this item. Example: `67890`
`limit`	integer	Optional	Number of timeline items to return, up to 100. Defaults to 20. Example: `20`
`source`	string	Optional	For `feeds` and custom channel timelines, limits items to one followed feed. Accepts the source `_id`, its feed URL, or its site URL. Example: `https://example.com/feed.json`

Header Parameters

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

Response

200 OK application/json

timeline returns items and paging. channels returns {"channels": [{"uid": "default", "name": "Timeline"}, ...]}. follow returns {"items": [{"type": "feed", "url": "...", "name": "...", "photo": "...", "description": "..."}]}.

Example Response

{
  "items": [
    {
      "type": "entry",
      "published": "2026-04-26T12:00:00Z",
      "content": {
        "html": "<p>Hello from Micro.blog.</p>"
      },
      "url": "https://vincent.micro.blog/2026/04/26/hello.html",
      "_id": "12345",
      "author": {
        "type": "card",
        "name": "Vincent",
        "url": "https://vincent.micro.blog/",
        "photo": "https://avatars.micro.blog/avatars/2025/39/3008.jpg"
      }
    }
  ],
  "paging": {
    "before": "12345",
    "after": "12340"
  }
}

POST


                          /microsub

Manages channels, follows and unfollows feeds, marks entries read or unread, searches for feeds, and previews a feed. The scope depends on action.

Note: Scopes: channels needs the channels scope. follow and unfollow need the follow scope. timeline, search, and preview need the read scope.

Note: follow subscribes to the feed found at url and returns it as a feed object. When the URL advertises more than one feed, it returns status 300 with {"results": [...]} so the user can choose one. Unfollowing from feeds removes the subscription. Unfollowing from a custom channel only removes the feed from that channel.

Note: Errors return {"error": "...", "error_description": "..."} with status 400 or 404.

Example Request

curl -X POST "https://micro.blog/microsub" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD" \
  --data "action=follow" \
  --data "channel=feeds" \
  --data "url=https://example.com/"

Examples

Create a channel

curl -X POST "https://micro.blog/microsub" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD" \
  --data "action=channels" \
  --data "name=News"

Mark entries as read

curl -X POST "https://micro.blog/microsub" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD" \
  --data "action=timeline" \
  --data "method=mark_read" \
  --data "channel=feeds" \
  --data "entry[]=12345"

Search for feeds

curl -X POST "https://micro.blog/microsub" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD" \
  --data "action=search" \
  --data "query=example.com"

Header Parameters

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

Request Body

Name	Type	Required	Description
`action`	string	Required	One of `channels`, `follow`, `unfollow`, `timeline`, `search`, or `preview`. Example: `follow`
`method`	string	Optional	For `channels`, one of `create`, `update`, `delete`, or `order`. When omitted, creates a channel if `channel` is empty and renames it otherwise. For `timeline`, `mark_read` or `mark_unread` (required). Example: `mark_read`
`channel`	string	Optional	Channel `uid`. Required for `follow`, `unfollow`, `timeline`, and channel `update` and `delete`. Must not be set for `search`. Example: `feeds`
`name`	string	Optional	Channel name. Required to create or rename a channel. Example: `News`
`channels[]`	array	Optional	For `channels` with `method=order`, custom channel uids in the new order. Example: `a1b2c3d4e5f6a7b8c9d0`
`url`	string	Optional	Site or feed URL. Required for `follow`, `unfollow`, and `preview`. Example: `https://example.com/`
`entry[]`	array	Optional	For `timeline`, one or more entry `_id` values to mark read or unread. Example: `12345`
`last_read_entry`	string	Optional	For `timeline`, an entry `_id`. Marks that entry and every newer entry in the channel. Example: `12345`
`query`	string	Optional	For `search`, a URL or domain to look for feeds on. Required for `search`. Example: `example.com`

Response

200 OK application/json

follow returns the followed feed. Creating or renaming a channel returns {"uid": "...", "name": "..."}. search returns {"results": [...]} and preview returns {"items": [...]}. Other actions return an empty JSON object.

Example Response

{
  "type": "feed",
  "url": "https://example.com/feed.json",
  "name": "Example Blog",
  "photo": "https://example.com/icon.png"
}