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

Posts

View .md

Endpoints for the timeline, single posts, photos and media, replies, user profiles, search, and post deletion.

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

Returns the authenticated user’s timeline in JSON Feed format with Micro.blog extensions, newest first. Page backwards with before_id and forwards with since_id. Requires a token with the read scope.

Example Request

curl -X GET "https://micro.blog/posts/all?count=50" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
count integer Optional Maximum number of posts to return.
Example: 50
since_id integer Optional Only return posts published after this post.
Example: 77479242
before_id integer Optional Only return posts published before this post. Use the last id from the previous page to load older posts.
Example: 77494371

Header Parameters

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

Response Properties

version string
JSON Feed version identifier.
Example: https://jsonfeed.org/version/1
title string
Title of the feed.
Example: Micro.blog - Timeline
home_page_url string
URL of the home page for this feed.
Example: https://micro.blog
feed_url string
URL of this feed.
Example: https://micro.blog/posts/all
_microblog object
Micro.blog-specific extensions to the JSON Feed format.
about string
URL to API documentation.
Example: https://micro.blog/about/api
items array of object
Array of post items.
Array item properties:
id string
Unique post identifier (64-bit).
Example: 77494371
content_html string
HTML content of the post.
Example: <p>Post content...</p>
summary string
Summary or excerpt of the post. Only present on blog posts, not on replies.
url string
URL to the post.
Example: https://www.manton.org/2025/11/07/if-you-are-on-the.html
date_published string
ISO 8601 timestamp of when the post was published.
Example: 2025-11-07T18:00:00+00:00
author object
Author information.
name string
Author’s display name.
Example: Manton Reece
url string
URL to author’s profile or website.
Example: https://manton.org
avatar string
URL to author’s avatar image.
Example: https://avatars.micro.blog/avatars/2025/22/3.jpg
_microblog object
Micro.blog-specific author fields.
_microblog object
Micro.blog-specific post fields.
date_relative string
Short display date or time, in the authenticated user’s time zone.
Example: 19:00
date_timestamp integer
Unix timestamp of the post.
Example: 1762538400
is_favorite boolean
Whether the authenticated user has bookmarked the post.
is_bookmark boolean
Whether the post is bookmarked by the authenticated user. Same value as is_favorite.
is_deletable boolean
Whether the post belongs to the authenticated user.
edit_url string
URL for editing the post on Micro.blog. Only set on the authenticated user’s own posts; replies include it as null otherwise.
Example: https://micro.blog/account/posts/12345/edit/67890
is_conversation boolean
Whether the post is part of a conversation. Always true for replies.
is_linkpost boolean
Whether this post is a link post.
is_mention boolean
Whether the item is a reply rather than a blog post.
is_podcast boolean
Whether the post is a podcast episode. Only present on blog posts.
audio object
Podcast audio for the post: url, plus duration_seconds and duration_display when known. Only present when is_podcast is true and an audio URL was found.
Example: {"url": "https://example.com/episode.mp3", "duration_seconds": 1834, "duration_display": "30:34"}
note string
Text of the authenticated user’s note attached to this post, or an empty string. Only present on blog posts.
syndication array
URLs where this post was cross-posted. Only present on blog posts.
Example: [https://example.com/syndication/url]

Response

200 OK application/json

Returns a JSON Feed object containing an array of posts with Micro.blog extensions. Returns 401 without a valid token.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Timeline",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/all",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": "77494371",
      "content_html": "<p>If you are on the TestFlight beta for Micro.blog iOS, you will have seen our experiments to enable Liquid Glass. I'm admitting defeat today, going to opt out of the new UI for the next version. There are too many little glitches.</p>\n",
      "summary": "",
      "url": "https://www.manton.org/2025/11/07/if-you-are-on-the.html",
      "date_published": "2025-11-07T18:00:00+00:00",
      "author": {
        "name": "Manton Reece",
        "url": "https://manton.org",
        "avatar": "https://avatars.micro.blog/avatars/2025/22/3.jpg",
        "_microblog": {
          "username": "manton"
        }
      },
      "_microblog": {
        "date_relative": "19:00",
        "date_timestamp": 1762538400,
        "is_favorite": false,
        "is_bookmark": false,
        "is_deletable": false,
        "is_conversation": false,
        "is_linkpost": false,
        "is_mention": false,
        "is_podcast": false,
        "note": "",
        "syndication": [
          "https://example.com/syndication/url"
        ]
      }
    }
  ]
}
GET /posts/timeline

Returns the authenticated user’s timeline in JSON Feed format. Same parameters and response as GET /posts/all, except the feed URL. Requires a token with the read scope.

Example Request

curl -X GET "https://micro.blog/posts/timeline?count=50" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
count integer Optional Maximum number of posts to return.
Example: 50
since_id integer Optional Only return posts published after this post.
Example: 77479242
before_id integer Optional Only return posts published before this post. Use the last id from the previous page to load older posts.
Example: 77494371

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 object. Items have the same shape as GET /posts/all.

Example Response

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

Returns a single post by ID as a timeline post object, not wrapped in a feed. Requires a token with the read scope.

Example Request

curl -X GET "https://micro.blog/posts/timeline/77494371" \
  --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 Post ID.
Example: 77494371

Response

200 OK application/json

Returns one post with the same shape as an item in GET /posts/all. Returns 404 with a plain-text message when the post does not exist.

Example Response

{
  "id": "77494371",
  "content_html": "<p>If you are on the TestFlight beta for Micro.blog iOS, you will have seen our experiments to enable Liquid Glass.</p>\n",
  "summary": "",
  "url": "https://www.manton.org/2025/11/07/if-you-are-on-the.html",
  "date_published": "2025-11-07T18:00:00+00:00",
  "author": {
    "name": "Manton Reece",
    "url": "https://manton.org",
    "avatar": "https://avatars.micro.blog/avatars/2025/22/3.jpg",
    "_microblog": {
      "username": "manton"
    }
  },
  "_microblog": {
    "date_relative": "19:00",
    "date_timestamp": 1762538400,
    "is_favorite": false,
    "is_bookmark": false,
    "is_deletable": false,
    "is_conversation": false,
    "is_linkpost": false,
    "is_mention": false,
    "is_podcast": false,
    "note": "",
    "syndication": []
  }
}
GET /posts/all/by_id

Returns a single post by ID as a timeline post object, not wrapped in a feed. Same as GET /posts/timeline/{id} with the ID in the query string. Requires a token with the read scope.

Example Request

curl -X GET "https://micro.blog/posts/all/by_id?id=77494371" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
id integer Required Post ID.
Example: 77494371

Header Parameters

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

Response

200 OK application/json

Returns one post with the same shape as an item in GET /posts/all. Returns 404 with a plain-text message when id is missing or the post does not exist.

Example Response

{
  "id": "77494371",
  "content_html": "<p>If you are on the TestFlight beta for Micro.blog iOS, you will have seen our experiments to enable Liquid Glass.</p>\n",
  "summary": "",
  "url": "https://www.manton.org/2025/11/07/if-you-are-on-the.html",
  "date_published": "2025-11-07T18:00:00+00:00",
  "author": {
    "name": "Manton Reece",
    "url": "https://manton.org",
    "avatar": "https://avatars.micro.blog/avatars/2025/22/3.jpg",
    "_microblog": {
      "username": "manton"
    }
  },
  "_microblog": {
    "date_relative": "19:00",
    "date_timestamp": 1762538400,
    "is_favorite": false,
    "is_bookmark": false,
    "is_deletable": false,
    "is_conversation": false,
    "is_linkpost": false,
    "is_mention": false,
    "is_podcast": false,
    "note": "",
    "syndication": []
  }
}
GET /posts/photos

Returns posts with images from the authenticated user’s timeline in JSON Feed format. Without before_id, only the 200 most recent timeline posts are scanned, so a page can hold fewer than count posts. Requires a token with the read scope.

Example Request

curl -X GET "https://micro.blog/posts/photos?count=25" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
count integer Optional Maximum number of posts to return.
Example: 25
since_id integer Optional Only return posts published after this post.
Example: 77479242
before_id integer Optional Only return posts published before this post.
Example: 77494371

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 object. Items have the same shape as GET /posts/all.

Example Response

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

Returns posts with photos or video from the authenticated user’s timeline in JSON Feed format. Each item adds a media classification and, when known, the size and blurhash of its first image. Requires a token with the read scope.

Example Request

curl -X GET "https://micro.blog/posts/media?count=25&filter=photos" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
count integer Optional Maximum number of posts to return.
Example: 25
since_id integer Optional Only return posts published after this post.
Example: 77479242
before_id integer Optional Only return posts published before this post.
Example: 77494371
filter string Optional Comma-separated media types to keep, photos and/or videos. The photos filter skips images classified as screenshots or graphics. Omit to return all media posts.
Example: photos,videos

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 object. Items have the same shape as GET /posts/all, plus _microblog.classification (photo, video, screenshot, graphic, or unknown) and, when known, _microblog.default_photo with width, height, and blurhash.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Media",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/media",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": "77494371",
      "content_html": "<p><img src=\"https://manton.org/uploads/2025/photo.jpg\" width=\"600\" height=\"450\" alt=\"\"></p>\n",
      "summary": "",
      "url": "https://www.manton.org/2025/11/07/photo.html",
      "date_published": "2025-11-07T18:00:00+00:00",
      "author": {
        "name": "Manton Reece",
        "url": "https://manton.org",
        "avatar": "https://avatars.micro.blog/avatars/2025/22/3.jpg",
        "_microblog": {
          "username": "manton"
        }
      },
      "_microblog": {
        "date_relative": "19:00",
        "date_timestamp": 1762538400,
        "is_favorite": false,
        "is_bookmark": false,
        "is_deletable": false,
        "is_conversation": false,
        "is_linkpost": false,
        "is_mention": false,
        "is_podcast": false,
        "note": "",
        "syndication": [],
        "classification": "photo",
        "default_photo": {
          "width": 1200,
          "height": 900,
          "blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
        }
      }
    }
  ]
}
GET /posts/replies

Returns the authenticated user’s own replies, newest first, in JSON Feed format. Requires a token with the read scope.

Example Request

curl -X GET "https://micro.blog/posts/replies?count=50" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
count integer Optional Maximum number of replies to return. Values above 100 are capped at 100.
Example: 50
q string Optional Only return replies whose text contains this string.
Example: thanks

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 object with the user as the feed author. Reply items have a smaller shape than timeline posts, including content_text and only date_relative and is_deletable under _microblog.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Replies",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/replies",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "author": {
    "name": "Manton Reece",
    "url": "https://manton.org",
    "avatar": "https://avatars.micro.blog/avatars/2025/22/3.jpg"
  },
  "items": [
    {
      "id": "98765",
      "content_html": "<p><a href=\"https://micro.blog/jean\">@jean</a> Thanks!</p>",
      "content_text": "@jean Thanks!",
      "url": "https://micro.blog/manton/98765",
      "date_published": "2025-11-07T18:00:00+00:00",
      "author": {
        "name": "Manton Reece",
        "url": "https://manton.org",
        "avatar": "https://avatars.micro.blog/avatars/2025/22/3.jpg",
        "_microblog": {
          "username": "manton"
        }
      },
      "_microblog": {
        "date_relative": "19:00",
        "is_deletable": true
      }
    }
  ]
}
GET /posts/search

Searches recent posts featured in Discover. Every word in the query must appear in the post text. Returns up to 50 posts in JSON Feed format. No authentication is required; with a token, posts from muted users are removed and is_favorite reflects the user’s bookmarks.

Example Request

curl -X GET "https://micro.blog/posts/search?q=coffee"

Query Parameters

Name Type Required Description
q string Required Search words. Queries shorter than 4 characters return no results. Characters other than letters, digits, and spaces are ignored.
Example: coffee

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.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Search",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": []
}
DELETE /posts/{id}

Deletes one of the authenticated user’s posts. A blog post is removed from the blog as well as the timeline. Requires a token with the delete scope.

Example Request

curl -X DELETE "https://micro.blog/posts/77494371" \
  --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 Post ID.
Example: 77494371

Response

200 OK application/json

Returns an empty JSON object. The response is the same when the post does not exist or belongs to someone else; nothing is deleted in those cases. Returns 403 when the token lacks the delete scope.

Example Response

{}
GET /posts/{username}

Returns a user’s profile and recent blog posts and replies, newest first, in JSON Feed format. No authentication is required; with a token, is_following, is_you, and is_favorite reflect the authenticated user and posts from muted users are removed.

Example Request

curl -X GET "https://micro.blog/posts/manton?count=10"

Query Parameters

Name Type Required Description
count integer Optional Maximum number of blog posts, and separately of replies, to include. The feed can hold up to twice this many items.
Example: 10

Header Parameters

Name Type Required Description
Authorization string Optional Optional bearer token. Format: Bearer {token}. Needs the read scope when sent. Required to view a user who has hidden their profile.

Path Parameters

Name Type Required Description
username string Required Micro.blog username.
Example: manton

Response

200 OK application/json

Returns a JSON Feed object with profile fields under _microblog and the user as the feed author. Items have the same shape as GET /posts/all. Returns 404 when the user does not exist, or has hidden their profile and no token is sent.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Manton Reece",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/manton",
  "_microblog": {
    "about": "https://micro.blog/about/api",
    "id": "12345",
    "username": "manton",
    "bio": "Founder of Micro.blog.",
    "pronouns": "",
    "is_following": false,
    "is_you": false,
    "following_count": 300,
    "discover_count": 10
  },
  "author": {
    "name": "Manton Reece",
    "url": "https://manton.org",
    "avatar": "https://avatars.micro.blog/avatars/2025/22/3.jpg"
  },
  "items": []
}
GET /posts/{username}/photos

Returns a user’s recent photo posts in JSON Feed format, with the same profile fields as GET /posts/{username}. No authentication is required; with a token, is_following, is_you, and is_favorite reflect the authenticated user.

Example Request

curl -X GET "https://micro.blog/posts/manton/photos?count=10"

Query Parameters

Name Type Required Description
count integer Optional Maximum number of photo posts to return.
Example: 10

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
username string Required Micro.blog username.
Example: manton

Response

200 OK application/json

Returns a JSON Feed object. Each item adds image (the photo URL) and _microblog.thumbnail_url (a 400-pixel thumbnail). Returns 404 when the user does not exist.

Example Response

{
  "version": "https://jsonfeed.org/version/1",
  "title": "Micro.blog - Manton Reece - Photos",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/posts/manton",
  "_microblog": {
    "about": "https://micro.blog/about/api",
    "id": "12345",
    "username": "manton",
    "bio": "Founder of Micro.blog.",
    "pronouns": "",
    "is_following": false,
    "is_you": false,
    "following_count": 300,
    "discover_count": 10
  },
  "author": {
    "name": "Manton Reece",
    "url": "https://manton.org",
    "avatar": "https://avatars.micro.blog/avatars/2025/22/3.jpg"
  },
  "items": [
    {
      "id": "77494371",
      "content_html": "<p><img src=\"https://manton.org/uploads/2025/photo.jpg\" width=\"600\" height=\"450\" alt=\"\"></p>\n",
      "url": "https://www.manton.org/2025/11/07/photo.html",
      "date_published": "2025-11-07T18:00:00+00:00",
      "image": "https://manton.org/uploads/2025/photo.jpg",
      "author": {
        "name": "Manton Reece",
        "url": "https://manton.org",
        "avatar": "https://avatars.micro.blog/avatars/2025/22/3.jpg",
        "_microblog": {
          "username": "manton"
        }
      },
      "_microblog": {
        "date_relative": "19:00",
        "date_timestamp": 1762538400,
        "is_favorite": false,
        "is_bookmark": false,
        "is_deletable": true,
        "is_conversation": false,
        "thumbnail_url": "https://micro.blog/photos/400/https://manton.org/uploads/2025/photo.jpg"
      }
    }
  ]
}