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

Users and Relationships

View .md

Endpoints for following and unfollowing, relationship checks, user search, follow suggestions, and the user’s activity log. Every endpoint needs an app token. Requests without a token return 401 with the text Token required.

BASE URL https://micro.blog
POST /users/follow

Follows a Micro.blog user, or any feed by URL. A feed Micro.blog hasn’t seen yet is added and followed. Requires the follow or write scope.

Example Request

curl -X POST "https://micro.blog/users/follow?username=manton" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
username string Optional Username to follow. Micro.blog usernames, and Mastodon and Bluesky accounts Micro.blog already knows, both work. Send username or feed_url.
Example: manton
feed_url string Optional RSS, Atom, or JSON Feed URL to follow. Only used when username is not sent.
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 text/html

Returns the text {} on success, sent without a JSON content type. Returns 404 with the text User not found when username doesn’t match a user.

Example Response

{}
POST /users/unfollow

Unfollows a user. Requires the follow or write scope.

Example Request

curl -X POST "https://micro.blog/users/unfollow?username=manton" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
username string Required Username to unfollow.
Example: manton

Header Parameters

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

Response

200 OK text/html

Returns the text {} on success, sent without a JSON content type. Returns 404 with the text User not found when username doesn’t match a user.

Example Response

{}
GET /users/is_following

Checks whether the authenticated user follows another user. Requires the read scope.

Example Request

curl -X GET "https://micro.blog/users/is_following?username=manton" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
username string Required Username to check.
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 object. is_you is true when username is the authenticated user. Returns 404 with the text User not found when username doesn’t match a user.

Example Response

{
  "is_following": true,
  "is_you": false
}
GET /users/following/{username}

Returns everyone a user follows, in one unpaged list. is_following and is_you are from the authenticated user’s point of view. Requires the read scope. Allows cross-origin requests.

Example Request

curl -X GET "https://micro.blog/users/following/manton" \
  --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
username string Required Username whose follows to list.
Example: manton

Response

200 OK application/json

Returns a JSON array of users. Returns 404 with the text User not found when username doesn’t match a user.

Example Response

[
  {
    "name": "Jean MacDonald",
    "url": "https://jean.example.com",
    "avatar": "https://avatars.micro.blog/avatars/2026/45/6.jpg",
    "username": "jean",
    "is_following": true,
    "is_you": false
  }
]
GET /users/discover/{username}

Suggests people to follow. Returns the users that username follows and the authenticated user doesn’t, in one unpaged list. Requires the read scope. Allows cross-origin requests.

Example Request

curl -X GET "https://micro.blog/users/discover/manton" \
  --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
username string Required Username whose follows to draw suggestions from.
Example: manton

Response

200 OK application/json

Returns a JSON array of users with the same keys as GET /users/following/{username}. Returns 404 with the text User not found when username doesn’t match a user.

Example Response

[
  {
    "name": "Jean MacDonald",
    "url": "https://jean.example.com",
    "avatar": "https://avatars.micro.blog/avatars/2026/45/6.jpg",
    "username": "jean",
    "is_following": false,
    "is_you": false
  }
]
GET /users/search

Searches for users. By default it matches the start of Micro.blog usernames, which suits search-as-you-type. Pass done=1 when the user has finished typing to also match names and look up Mastodon handles, profile URLs, and domains. Requires the read scope. Allows cross-origin requests.

Example Request

curl -X GET "https://micro.blog/users/search?q=man" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
q string Required Search text. Queries shorter than 3 characters return an empty array.
Example: man
done integer Optional Set to 1 to run the full search described above. A .tumblr.com or .wordpress.com address always runs the full search.
Example: 1

Header Parameters

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

Response

200 OK application/json

Returns a JSON array of users. Username prefix matches return at most 20 users.

Example Response

[
  {
    "name": "Manton Reece",
    "url": "https://manton.org",
    "avatar": "https://avatars.micro.blog/avatars/2026/22/3.jpg",
    "username": "manton",
    "bio": "Working on Micro.blog.",
    "is_following": true,
    "is_you": false
  }
]
GET /users/logs

Returns the authenticated user’s activity log, newest first, such as publishing, cross-posting, and import messages. Returns at most 250 entries. Requires the read scope.

Example Request

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

Query Parameters

Name Type Required Description
q string Optional Only return entries whose text contains this string.
Example: Publishing
since_id integer Optional Only return entries with an id greater than this one. Use it to poll for new entries.
Example: 9876543

Header Parameters

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

Response

200 OK application/json

Returns a JSON array. message is plain text and html is the same message marked up for display. When Micro.blog has shortened a long message, original holds the full HTML; otherwise it is null. is_done is true for entries that report a finished task. Sent with Cache-Control: no-store.

Example Response

[
  {
    "id": 9876544,
    "date": "2026-04-26T12:00:00+00:00",
    "message": "Publishing: Done publishing the blog — example.micro.blog",
    "html": "<span class=\"log_prefix log_prefix--light_gray\">Publishing</span> Done publishing the blog <span class=\"logs_hostname\">— example.micro.blog</span>",
    "original": null,
    "is_done": true,
    "is_error": false
  }
]
GET /users/logs/errors

Returns only the error entries from the authenticated user’s activity log. Takes the same parameters and returns the same shape as GET /users/logs. Requires the read scope.

Example Request

curl -X GET "https://micro.blog/users/logs/errors" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name Type Required Description
q string Optional Only return entries whose text contains this string.
Example: Bluesky
since_id integer Optional Only return entries with an id greater than this one.
Example: 9876543

Header Parameters

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

Response

200 OK application/json

Returns a JSON array of log entries. Sent with Cache-Control: no-store.

Example Response

[
  {
    "id": 9876545,
    "date": "2026-04-26T12:05:00+00:00",
    "message": "Bluesky: Error sending post, could not connect to the server",
    "html": "<span class=\"log_prefix log_prefix--teal\">Bluesky</span> Error sending post, could not connect to the server",
    "original": null,
    "is_done": false,
    "is_error": true
  }
]