featured_tags

Feature tags that you use frequently.

get
View your featured tags

https://mastodon.example/api/v1/featured_tags

Returns: Array of FeaturedTag
OAuth: User token + read:accounts
Version history:
3.0.0 - added

Request

Headers
Authorization
required
string
Bearer <user token>

Response

200: Success

[
  {
    "id": "627",
    "name": "nowplaying",
    "statuses_count": 36,
    "last_status_at": "2019-11-15T07:14:43.524Z"
  }
]

401: Unauthorized

Invalid or missing Authorization header

{
  "error": "The access token is invalid"
}

post
Feature a tag

https://mastodon.example/api/v1/featured_tags

Returns: FeaturedTag
OAuth: User token + write:accounts
Version history:
3.0.0 - added

Request

Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
name
required
string
The hashtag to be featured.

Response

200: Success

A FeaturedTag will be created with the specified name.

{
  "id": "13174",
  "name": "circasurvive",
  "statuses_count": 11,
  "last_status_at": "2019-11-15T06:20:32.769Z"
}

422: Unprocessable Entity

If name is not a valid hashtag, e.g. contains illegal characters or only numbers

{
  "error": "Validation failed: Tag is invalid"
}

delete
Unfeature a tag

https://mastodon.example/api/v1/featured_tags/:id

Returns: empty object
OAuth: User token + write:accounts
Version history:
3.0.0 - added

Request

Path Parameters
:id
required
string
The id of the FeaturedTag to be unfeatured.
Headers
Authorization
required
string
Bearer <user token>

Response

200: Success

An empty object will be returned if the featured tag was successfully deleted.

{}

404: Not Found

If the ID does not exist or is not owned by you

{
  "error": "Record not found"
}

get
Suggested tags to feature

https://mastodon.example/api/v1/featured_tags/suggestions

Shows your 10 most-used tags, with usage history for the past week.

Returns: Array of Tag with History
OAuth: User token + read:accounts
Version history:
3.0.0 - added

Request

Headers
Authorization
required
string
Bearer <user token>

Response

200: Success

Truncated results to first and last tag.

[
  {
    "name": "nowplaying",
    "url": "https://mastodon.social/tags/nowplaying",
    "history": [
      {
        "day": "1574553600",
        "uses": "200",
        "accounts": "31"
      },
      {
        "day": "1574467200",
        "uses": "272",
        "accounts": "39"
      },
      {
        "day": "1574380800",
        "uses": "345",
        "accounts": "40"
      },
      {
        "day": "1574294400",
        "uses": "366",
        "accounts": "46"
      },
      {
        "day": "1574208000",
        "uses": "226",
        "accounts": "32"
      },
      {
        "day": "1574121600",
        "uses": "217",
        "accounts": "42"
      },
      {
        "day": "1574035200",
        "uses": "214",
        "accounts": "34"
      }
    ]
  },
  ...
  {
    "name": "mastothemes",
    "url": "https://mastodon.social/tags/mastothemes",
    "history": [
      {
        "day": "1574553600",
        "uses": "0",
        "accounts": "0"
      },
      {
        "day": "1574467200",
        "uses": "0",
        "accounts": "0"
      },
      {
        "day": "1574380800",
        "uses": "0",
        "accounts": "0"
      },
      {
        "day": "1574294400",
        "uses": "0",
        "accounts": "0"
      },
      {
        "day": "1574208000",
        "uses": "0",
        "accounts": "0"
      },
      {
        "day": "1574121600",
        "uses": "0",
        "accounts": "0"
      },
      {
        "day": "1574035200",
        "uses": "0",
        "accounts": "0"
      }
    ]
  }
]

401: Unauthorized

{
  "error": "The access token is invalid"
}

Last updated December 27, 2020 · Improve this page