API Documentation

Movies

Endpoints for recent movie and TV activity, TMDB search, and post text for watched movies, seasons, and episodes. Every endpoint needs an app token with the read scope and allows cross-origin requests. Requests without a token return 401 with the text Token required.

Note: post_text is ready to use as the text of a new post. It starts with the user’s “watched” prefix from their movie settings (Watched: when none is set), links the title to TMDB, and ends with the user’s movie or TV emoji (🍿 when none is set). The feed-level _microblog object repeats the prefix and emoji so you can build your own text.

BASE URL


                  https://micro.blog

GET


                          /movies/discover

Returns the movies and TV shows Micro.blog users posted about most recently, newest first, in JSON Feed format. Up to 100 recent posts are read and repeated titles are collapsed, so the feed usually holds fewer than 100 items.

Example Request

curl -X GET "https://micro.blog/movies/discover" \
  --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. url is the link from the post, falling back to Letterboxd and then TMDB. image is the poster through Micro.blog’s image proxy. _microblog keys with no value are left out, so letterboxd_url and link_url only appear when the post linked there.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Discover Movies",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/movies/discover",
  "_microblog": {
    "about": "https://micro.blog/about/api"
  },
  "items": [
    {
      "id": "12345",
      "title": "Dune: Part Two",
      "content_text": "Paul Atreides unites with Chani and the Fremen.",
      "date_published": "2026-04-26T12:00:00+00:00",
      "url": "https://www.themoviedb.org/movie/693134",
      "image": "https://micro.blog/photos/100x/https%3A%2F%2Fimage.tmdb.org%2Ft%2Fp%2Fw154%2Fexample.jpg",
      "authors": [
        {
          "name": "Manton Reece",
          "avatar": "https://avatars.micro.blog/avatars/2026/22/3.jpg",
          "url": "https://manton.org",
          "_microblog": {
            "username": "manton",
            "user_id": 123
          }
        }
      ],
      "_microblog": {
        "tmdb_id": "693134",
        "tmdb_url": "https://www.themoviedb.org/movie/693134",
        "poster_url": "https://image.tmdb.org/t/p/w154/example.jpg",
        "username": "manton",
        "user_id": 123,
        "user_avatar_url": "https://avatars.micro.blog/avatars/2026/22/3.jpg",
        "date_timestamp": 1777204800
      }
    }
  ]
}

GET


                          /movies/search

Searches TMDB for movies and TV shows and returns each match with ready-made post text. Adult titles are excluded.

Example Request

curl -X GET "https://micro.blog/movies/search?q=dune&limit=20" \
  --header "Authorization: Bearer ABCDEF1234567890ABCD"

Query Parameters

Name	Type	Required	Description
`q`	string	Required	Movie or TV show title to search for. Example: `dune`
`limit`	integer	Optional	Maximum number of results, from 1 to 50. Values outside that range use the default. Example: `20`

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. _microblog.type is movie or tv. Movies can include director. TV shows can include seasons_count; pass tmdb_id to GET /movies/discover/{id} to list the seasons. Returns 400 with {"error": "Missing query"} when q is empty. If TMDB can’t be reached, items is empty.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Movies Search",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/movies/search",
  "_microblog": {
    "about": "https://micro.blog/about/api",
    "movies_prefix": "Watched:",
    "movies_emoji_movie": "🍿",
    "movies_emoji_tv": "🍿"
  },
  "items": [
    {
      "id": "movie-693134",
      "title": "Dune: Part Two",
      "content_text": "",
      "url": "https://www.themoviedb.org/movie/693134",
      "image": "https://image.tmdb.org/t/p/w154/example.jpg",
      "_microblog": {
        "tmdb_id": "693134",
        "type": "movie",
        "title": "Dune: Part Two",
        "tmdb_url": "https://www.themoviedb.org/movie/693134",
        "year": "2024",
        "director": "Denis Villeneuve",
        "poster_url": "https://image.tmdb.org/t/p/w154/example.jpg",
        "overview": "Paul Atreides unites with Chani and the Fremen.",
        "post_text": "Watched: [Dune: Part Two](https://www.themoviedb.org/movie/693134) 🍿",
        "movies_prefix": "Watched:",
        "movies_emoji_movie": "🍿",
        "movies_emoji_tv": "🍿"
      }
    },
    {
      "id": "tv-95396",
      "title": "Severance",
      "content_text": "",
      "url": "https://www.themoviedb.org/tv/95396",
      "image": "https://image.tmdb.org/t/p/w154/example.jpg",
      "_microblog": {
        "tmdb_id": "95396",
        "type": "tv",
        "title": "Severance",
        "tmdb_url": "https://www.themoviedb.org/tv/95396",
        "year": "2022",
        "poster_url": "https://image.tmdb.org/t/p/w154/example.jpg",
        "overview": "Mark leads a team of office workers whose memories have been surgically divided.",
        "seasons_count": 2,
        "post_text": "Watched: [Severance](https://www.themoviedb.org/tv/95396) 🍿",
        "movies_prefix": "Watched:",
        "movies_emoji_movie": "🍿",
        "movies_emoji_tv": "🍿"
      }
    }
  ]
}

GET


                          /movies/discover/{id}

Returns the seasons of a TV show, each with ready-made post text. The feed-level _microblog object describes the show and includes post text for the whole series.

Example Request

curl -X GET "https://micro.blog/movies/discover/95396" \
  --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`	string	Required	TMDB TV show ID, as returned in `tmdb_id` from `GET /movies/search`. Example: `95396`

Response

200 OK application/json

Returns a JSON Feed with one item per season. Specials (season 0) are left out. Item images go through Micro.blog’s image proxy. first_air_date and homepage only appear when TMDB has them. Returns 404 when TMDB has no TV show with that ID.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Discover Movies - Severance",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/movies/discover/95396",
  "_microblog": {
    "about": "https://micro.blog/about/api",
    "tmdb_id": "95396",
    "tmdb_url": "https://www.themoviedb.org/tv/95396",
    "movies_prefix": "Watched:",
    "movies_emoji_movie": "🍿",
    "movies_emoji_tv": "🍿",
    "title": "Severance",
    "overview": "Mark leads a team of office workers whose memories have been surgically divided.",
    "poster_url": "https://image.tmdb.org/t/p/w154/example.jpg",
    "number_of_seasons": 2,
    "number_of_episodes": 19,
    "type": "tv",
    "first_air_date": "2022-02-17",
    "homepage": "https://example.com/severance",
    "post_text": "Watched: [Severance](https://www.themoviedb.org/tv/95396) 🍿"
  },
  "items": [
    {
      "id": "tv-95396-season-1",
      "title": "Season 1",
      "content_text": "The Macrodata Refinement team begins to question Lumon Industries.",
      "url": "https://www.themoviedb.org/tv/95396/season/1",
      "_microblog": {
        "tmdb_id": "95396",
        "season_number": 1,
        "tmdb_url": "https://www.themoviedb.org/tv/95396/season/1",
        "post_text": "Watched: [Severance Season 1](https://www.themoviedb.org/tv/95396/season/1) 🍿",
        "movies_prefix": "Watched:",
        "movies_emoji_tv": "🍿",
        "series_title": "Severance",
        "season_title": "Season 1",
        "overview": "The Macrodata Refinement team begins to question Lumon Industries.",
        "air_date": "2022-02-17",
        "episode_count": 9,
        "poster_url": "https://image.tmdb.org/t/p/w154/season.jpg"
      },
      "image": "https://micro.blog/photos/100x/https%3A%2F%2Fimage.tmdb.org%2Ft%2Fp%2Fw154%2Fseason.jpg"
    }
  ]
}

GET


                          /movies/discover/{id}/seasons/{number}

Returns the episodes of one TV season, each with ready-made post text. The feed-level _microblog object describes the season.

Example Request

curl -X GET "https://micro.blog/movies/discover/95396/seasons/1" \
  --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`	string	Required	TMDB TV show ID. Example: `95396`
`number`	integer	Required	Season number, as returned in `season_number` from `GET /movies/discover/{id}`. Example: `1`

Response

200 OK application/json

Returns a JSON Feed with one item per episode. In this response season_number and episode_number are strings. still_url is a small still and large_still_url a 500-pixel-wide one; item images go through Micro.blog’s image proxy. Returns 404 when TMDB has no such show or season.

Example Response

{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Micro.blog - Discover Movies - Severance Season 1",
  "home_page_url": "https://micro.blog",
  "feed_url": "https://micro.blog/movies/discover/95396/seasons/1",
  "_microblog": {
    "about": "https://micro.blog/about/api",
    "tmdb_id": "95396",
    "tmdb_url": "https://www.themoviedb.org/tv/95396/season/1",
    "season_number": "1",
    "movies_prefix": "Watched:",
    "movies_emoji_tv": "🍿",
    "series_title": "Severance",
    "title": "Season 1",
    "overview": "The Macrodata Refinement team begins to question Lumon Industries.",
    "poster_url": "https://image.tmdb.org/t/p/w154/season.jpg",
    "episode_count": 9
  },
  "items": [
    {
      "id": "tv-95396-season-1-episode-1",
      "title": "Severance S1E1: Good News About Hell",
      "content_text": "Mark is promoted to lead a team whose memories are divided between work and home.",
      "url": "https://www.themoviedb.org/tv/95396/season/1/episode/1",
      "_microblog": {
        "tmdb_id": "95396",
        "season_number": "1",
        "episode_number": "1",
        "tmdb_url": "https://www.themoviedb.org/tv/95396/season/1/episode/1",
        "post_text": "Watched: [Severance S1E1, Good News About Hell](https://www.themoviedb.org/tv/95396/season/1/episode/1) 🍿",
        "movies_prefix": "Watched:",
        "movies_emoji_tv": "🍿",
        "series_title": "Severance",
        "episode_title": "Good News About Hell",
        "overview": "Mark is promoted to lead a team whose memories are divided between work and home.",
        "still_url": "https://image.tmdb.org/t/p/w154/still.jpg",
        "large_still_url": "https://image.tmdb.org/t/p/w500/still.jpg",
        "runtime": 57,
        "air_date": "2022-02-18"
      },
      "image": "https://micro.blog/photos/100x/https%3A%2F%2Fimage.tmdb.org%2Ft%2Fp%2Fw154%2Fstill.jpg"
    }
  ]
}