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

Bookmarks

View .md

Endpoints for bookmarks, bookmark tags, bookmark highlights, Listen Later episodes, and saved Reader pages.

BASE URL https://micro.blog
GET /posts/bookmarks

Returns the authenticated user’s 25 most recent bookmarks in JSON Feed format. Use before_id to page through older bookmarks. Podcast episodes are omitted from this feed; they appear in GET /posts/bookmarks/listenlater. Requires the read scope.

Example Request

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

Query Parameters

Name Type Required Description
before_id integer Optional Only return bookmarks saved before the bookmark with this id.
Example: 15563191
tag string Optional Only return bookmarks with this tag.
Example: life
q string Optional Only return bookmarks of posts by this username. Ignored when tag is set.
Example: manton

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. content_html ends with links to the saved Reader copies listed in _microblog.links. tags is a comma-separated string. _microblog.is_showing_summaries reflects the user’s setting for showing summary.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Bookmarks",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/bookmarks",
  "_microblog": {
    "about": "https://micro.blog/about/api",
    "is_showing_summaries": true
  },
  "items": [
    {
      "id": "12345",
      "content_html": "<p>Saved bookmark text.</p><a class=\"post_archived_links\" href=\"https://micro.blog/bookmarks/987\">Reader: <span>example.com</span></a> ",
      "summary": "Saved bookmark summary.",
      "url": "https://example.com/article",
      "date_published": "2026-04-26T12:00:00+00:00",
      "tags": "reading, reference",
      "author": {
        "name": "Manton Reece",
        "url": "https://manton.micro.blog/",
        "avatar": "https://avatars.micro.blog/avatars/2026/1.jpg",
        "_microblog": {
          "username": "manton"
        }
      },
      "_microblog": {
        "date_relative": "12:00",
        "date_favorited": "2026-04-26T12:05:00+00:00",
        "date_timestamp": 1777204800,
        "links": [
          {
            "id": 987,
            "url": "https://example.com/article",
            "archived_url": "https://micro.blog/archives/987"
          }
        ],
        "is_bookmark": true,
        "is_favorite": true,
        "is_deletable": false,
        "is_conversation": false
      }
    }
  ]
}
POST /posts/bookmarks

Adds a timeline post to the authenticated user’s bookmarks. If the post is a podcast episode, it is saved to Listen Later instead of the bookmarks feed. There is no separate Listen Later POST endpoint. Bookmarking a post that is already bookmarked, or an unknown post ID, does nothing and still returns {}. Requires the create scope.

Example Request

curl -X POST "https://micro.blog/posts/bookmarks?id=1760000" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
id integer Required ID of the timeline post to bookmark.
Example: 1760000

Header Parameters

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

Response

200 OK text/html

Returns {}. The body is JSON, but this route doesn’t set a JSON Content-Type.

Example Response

{}
GET /posts/bookmarks/listenlater

Returns the authenticated user’s Listen Later queue in JSON Feed format. Each item is a saved podcast episode. The feed returns 25 items; use before_id to page through older episodes. Add and remove episodes with POST /posts/bookmarks and DELETE /posts/bookmarks/{id}. Requires the read scope.

Example Request

curl -X GET "https://micro.blog/posts/bookmarks/listenlater" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
before_id integer Optional Only return episodes saved before the Listen Later item with this id.
Example: 15563191

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 saved podcast episodes. Items include _microblog.is_podcast and, when audio is available, _microblog.audio with url and optional duration fields.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Listen Later",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/bookmarks/listenlater",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": "12345",
      "content_html": "<p>Episode title</p><p><audio controls preload=\"none\" src=\"https://cdn.micro.blog/episode.m4a\"></audio></p>",
      "url": "https://example.com/episode",
      "date_published": "2026-04-26T12:00:00+00:00",
      "tags": "",
      "author": {
        "name": "Manton Reece",
        "url": "https://manton.micro.blog/",
        "avatar": "https://avatars.micro.blog/avatars/2026/1.jpg",
        "_microblog": {
          "username": "manton"
        }
      },
      "_microblog": {
        "date_relative": "12:00",
        "date_favorited": "2026-04-26T12:05:00+00:00",
        "date_timestamp": 1777204800,
        "is_bookmark": true,
        "is_favorite": true,
        "is_podcast": true,
        "is_deletable": false,
        "is_conversation": false,
        "audio": {
          "url": "https://cdn.micro.blog/episode.m4a",
          "duration_seconds": 125,
          "duration_display": "2:05"
        }
      }
    }
  ]
}
GET /posts/bookmarks/highlights

Returns up to 200 of the most recent highlights made in bookmarked Reader pages, in JSON Feed format. Requires the read scope.

Example Request

curl -X GET "https://micro.blog/posts/bookmarks/highlights" \
  --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. Each item is one highlight, with the page title, the highlighted text in content_text, and the original page URL. _microblog.count is the total number of highlights, which can be more than the items returned.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Highlights",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/bookmarks/highlights",
  "_microblog": {
    "about": "https://micro.blog/about/api",
    "count": 1
  },
  "items": [
    {
      "id": 456,
      "title": "Saved article title",
      "content_text": "Highlighted passage from the saved article.",
      "url": "https://example.com/article",
      "date_published": "2026-04-26T12:00:00+00:00"
    }
  ]
}
DELETE /posts/bookmarks/highlights/{id}

Deletes a bookmark highlight. Requires the delete scope.

Example Request

curl -X DELETE "https://micro.blog/posts/bookmarks/highlights/{id}" \
  --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 Highlight id from GET /posts/bookmarks/highlights.
Example: 12345

Response

200 OK application/json

Returns an empty JSON object, including when no matching highlight exists.

Example Response

{}
GET /posts/bookmarks/links

Returns the 100 most recent web pages Micro.blog saved as Reader copies for the authenticated user’s bookmarks, in JSON Feed format. Requires the read scope.

Example Request

curl -X GET "https://micro.blog/posts/bookmarks/links" \
  --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. Each item is a saved page with its original url and title. content_text is always empty, and _microblog.thumbnail_url is an empty string when there is no thumbnail.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Links",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/bookmarks/links",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": 987,
      "url": "https://example.com/article",
      "title": "Saved article title",
      "content_text": "",
      "_microblog": {
        "thumbnail_url": ""
      }
    }
  ]
}
GET /posts/bookmarks/tags

Returns the authenticated user’s bookmark tag names, sorted alphabetically. Requires the read scope.

Example Request

curl -X GET "https://micro.blog/posts/bookmarks/tags?recent=1&count=10" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
recent boolean Optional When present with any value, returns only the most recently used tags, newest first.
Example: 1
count integer Optional Number of recent tags to return. Only used with recent.
Example: 10

Header Parameters

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

Response

200 OK application/json

Returns an array of bookmark tag names.

Example Response

[
  "reading",
  "reference"
]
DELETE /posts/bookmarks/tags/{id}

Deletes a bookmark tag and removes it from every bookmark that uses it. Requires the delete scope.

Example Request

curl -X DELETE "https://micro.blog/posts/bookmarks/tags/{id}" \
  --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 Numeric tag ID. GET /posts/bookmarks/tags returns tag names only, not IDs.
Example: 12345

Response

200 OK application/json

Returns an empty JSON object on success. An unknown tag ID returns 404 with the plain-text message Tag not found.

Example Response

{}
DELETE /posts/bookmarks/{id}

Removes a bookmark or Listen Later episode by bookmark ID or original post ID. There is no separate Listen Later DELETE endpoint. Requires the delete scope.

Example Request

curl -X DELETE "https://micro.blog/posts/bookmarks/{id}" \
  --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 Bookmark id, or the ID of the bookmarked timeline post.
Example: 12345

Response

200 OK text/html

Returns {}, including when no matching bookmark exists. The body is JSON, but this route doesn’t set a JSON Content-Type.

Example Response

{}
GET /posts/bookmarks/{id}

Returns a single bookmark or Listen Later episode by bookmark ID or original post ID. Listen Later items in this response do not include _microblog.audio. Use GET /posts/bookmarks/listenlater for audio metadata. Requires the read scope.

Example Request

curl -X GET "https://micro.blog/posts/bookmarks/{id}" \
  --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 Bookmark id, or the ID of the bookmarked timeline post.
Example: 12345

Response

200 OK application/json

Returns a JSON Feed with one item. content_html is the saved text without Reader links, and date_published is when the bookmark was saved. An unknown ID returns 404 with the plain-text message Bookmark not found.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Bookmark",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/bookmarks/12345",
  "icon": "https://micro.blog/images/icons/favicon_256.png",
  "favicon": "https://micro.blog/images/icons/favicon_32.png",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": "12345",
      "content_html": "<p>Saved bookmark text.</p>",
      "url": "https://example.com/article",
      "date_published": "2026-04-26T12:00:00+00:00",
      "tags": "reading, reference"
    }
  ]
}
POST /posts/bookmarks/{id}

Replaces the tags on an existing bookmark. Requires the write scope.

Example Request

curl -X POST "https://micro.blog/posts/bookmarks/{id}?tags=html%2C+robots%2C+something" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
tags string Required Comma-separated bookmark tags. Send an empty value to remove all tags.
Example: html, robots, something

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 Bookmark id. Unlike the other bookmark routes, the original post ID is not accepted.
Example: 12345

Response

200 OK application/json

Returns an empty JSON object, including when no matching bookmark exists.

Example Response

{}