featured_tags

Feature tags that you use frequently.

View your featured tags

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

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

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200

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

401 Invalid or missing Authorization header

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

Feature a tag

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

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

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

Request Body

Name	Type	Description
name	string	The hashtag to be featured.

200 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 If name is not a valid hashtag, e.g. contains illegal characters or only numbers

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

Unfeature a tag

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

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

Path Parameters

Name	Type	Description
:id	string	The id of the FeaturedTag to be unfeatured.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

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

{}

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

{
  "error": "Record not found"
}

Suggested tags to feature

GET 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

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 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

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