diff --git a/.tool-versions b/.tool-versions new file mode 100644 index 000000000..5ca8a7bf6 --- /dev/null +++ b/.tool-versions @@ -0,0 +1 @@ +hugo extended_0.130.0 diff --git a/content/en/entities/Tag.md b/content/en/entities/Tag.md index fb9535b54..df51ddc18 100644 --- a/content/en/entities/Tag.md +++ b/content/en/entities/Tag.md @@ -16,6 +16,7 @@ aliases: [ ```json { + "id": "802", "name": "nowplaying", "url": "https://mastodon.social/tags/nowplaying", "history": [ @@ -61,6 +62,14 @@ aliases: [ ## Attributes +### `id` {#id} + +**Description:** ID of the hashtag in the database. Useful for constructing URLs for the moderation tools & Admin API.\ +**Type:** String (cast from an integer but not guaranteed to be a number)\ +**Version history:**\ +3.5.0 - added to admin APIs +4.3.1 - added to public APIs + ### `name` {#name} **Description:** The value of the hashtag after the # sign.\ @@ -114,6 +123,7 @@ aliases: [ ```json { + "id": "802", "name": "caturday", "url": "https://mastodon.example/tags/caturday", "history": [ @@ -153,20 +163,12 @@ aliases: [ "uses": "22" } ], - "id": "802", "trendable": true, "usable": true, "requires_review": false } ``` -### `id` {#id} - -**Description:** The ID of the Tag in the database.\ -**Type:** String (cast from integer, but not guaranteed to be a number)\ -**Version history:**\ -3.5.0 - added - ### `trendable` {#trendable} **Description:** Whether the hashtag has been approved to trend.\ diff --git a/content/en/methods/admin/trends.md b/content/en/methods/admin/trends.md index 3b9d88fa0..bc651b898 100644 --- a/content/en/methods/admin/trends.md +++ b/content/en/methods/admin/trends.md @@ -195,6 +195,7 @@ Authorization ```json [ { + "id": "802", "name": "caturday", "url": "https://mastodon.example/tags/caturday", "history": [ @@ -234,7 +235,6 @@ Authorization "uses": "22" } ], - "id": "802", "trendable": true, "usable": true, "requires_review": false diff --git a/content/en/methods/featured_tags.md b/content/en/methods/featured_tags.md index 51ebf4303..c6f5e65b7 100644 --- a/content/en/methods/featured_tags.md +++ b/content/en/methods/featured_tags.md @@ -40,6 +40,10 @@ Authorization #### Response ##### 200: OK +{{< hint style="info" >}} +The `id` property of the items in this response refers to the [FeaturedTag]({{< relref "entities/featuredtag" >}}) entity, and is not the `id` for a [Tag]({{< relref "entities/tag" >}}) entity. +{{< /hint >}} + ```json [ { @@ -208,6 +212,7 @@ Truncated results to first and last tag. ```json [ { + "id": "4325", "name": "nowplaying", "url": "https://mastodon.social/tags/nowplaying", "history": [ @@ -250,6 +255,7 @@ Truncated results to first and last tag. }, // ... { + "id": "1684", "name": "mastothemes", "url": "https://mastodon.social/tags/mastothemes", "history": [ diff --git a/content/en/methods/followed_tags.md b/content/en/methods/followed_tags.md index fac0c7377..541e96455 100644 --- a/content/en/methods/followed_tags.md +++ b/content/en/methods/followed_tags.md @@ -60,8 +60,9 @@ List of followed hashtags ```json [ { - "name": "Test", - "url": "http://mastodon.example/tags/test", + "id": "802", + "name": "Caturday", + "url": "http://mastodon.example/tags/caturday", "history": [ { "day": "1668556800", @@ -105,7 +106,7 @@ List of followed hashtags ] ``` -Because TagFollow IDs are generally not exposed via any API responses, you will have to parse the HTTP `Link` header to load older or newer results. See [Paginating through API responses]({{}}) for more information. +To paginate through the records in the followed tags collection, you must use the HTTP `Link` header to load older or newer results. The `id` property in the results refers to the [Tag]({{< relref "entities/Tag" >}}), not the record representing the following relationship to a Tag. See [Paginating through API responses]({{}}) for more information. ```http Link: ; rel="next", ; rel="prev" diff --git a/content/en/methods/search.md b/content/en/methods/search.md index f0dcd1b54..982fac481 100644 --- a/content/en/methods/search.md +++ b/content/en/methods/search.md @@ -113,6 +113,7 @@ Truncated results of a sample search for "cats" with limit=2. ], "hashtags": [ { + "id": "205", "name": "cats", "url": "https://mastodon.social/tags/cats", "history": [ @@ -125,6 +126,7 @@ Truncated results of a sample search for "cats" with limit=2. ] }, { + "id": "708", "name": "catsofmastodon", "url": "https://mastodon.social/tags/catsofmastodon", "history": [ diff --git a/content/en/methods/tags.md b/content/en/methods/tags.md index 71c514fa8..7cfd87b06 100644 --- a/content/en/methods/tags.md +++ b/content/en/methods/tags.md @@ -20,7 +20,7 @@ aliases: [ ## View information about a single tag {#get} ```http -GET /api/v1/tags/:id HTTP/1.1 +GET /api/v1/tags/:name HTTP/1.1 ``` Show a hashtag and its associated information @@ -34,8 +34,8 @@ Show a hashtag and its associated information ##### Path parameters -:id -: {{}} String. The name of the hashtag. +:name +: {{}} String. The name of the hashtag, case-insensitive. ##### Headers @@ -47,8 +47,9 @@ Authorization ```json { - "name": "Test", - "url": "http://mastodon.example/tags/test", + "id": "802", + "name": "Caturday", + "url": "http://mastodon.example/tags/caturday", "history": [ { "day": "1668556800", @@ -95,7 +96,7 @@ Authorization ## Follow a hashtag {#follow} ```http -POST /api/v1/tags/:id/follow HTTP/1.1 +POST /api/v1/tags/:name/follow HTTP/1.1 ``` Follow a hashtag. Posts containing a followed hashtag will be inserted into your home timeline. @@ -110,8 +111,8 @@ Follow a hashtag. Posts containing a followed hashtag will be inserted into your ##### Path parameters -:id -: {{}} String. The name of the hashtag. +:name +: {{}} String. The name of the hashtag, case-insensitive. ##### Headers @@ -125,8 +126,9 @@ Tag has been successfully followed ```json { - "name": "Test", - "url": "http://mastodon.example/tags/test", + "id": "802", + "name": "Caturday", + "url": "http://mastodon.example/tags/caturday", "history": [ { "day": "1668556800", @@ -193,7 +195,7 @@ Prior to 4.1.0: Tag was already followed ## Unfollow a hashtag {#unfollow} ```http -POST /api/v1/tags/:id/unfollow HTTP/1.1 +POST /api/v1/tags/:name/unfollow HTTP/1.1 ``` Unfollow a hashtag. Posts containing this hashtag will no longer be inserted into your home timeline. @@ -207,8 +209,8 @@ Unfollow a hashtag. Posts containing this hashtag will no longer be inserted int ##### Path parameters -:id -: {{}} String. The name of the hashtag. +:name +: {{}} String. The name of the hashtag, case-insensitive. ##### Headers @@ -222,8 +224,9 @@ Tag has been successfully unfollowed, or was already unfollowed ```json { - "name": "Test", - "url": "http://mastodon.example/tags/test", + "id": "802", + "name": "Caturday", + "url": "http://mastodon.example/tags/caturday", "history": [ { "day": "1668556800", diff --git a/content/en/methods/trends.md b/content/en/methods/trends.md index 31865ea95..88458e28e 100644 --- a/content/en/methods/trends.md +++ b/content/en/methods/trends.md @@ -48,6 +48,7 @@ offset ```json [ { + "id": "201", "name": "hola", "url": "https://mastodon.social/tags/hola", "history": [ @@ -60,6 +61,7 @@ offset ] }, { + "id": "695", "name": "SaveDotOrg", "url": "https://mastodon.social/tags/SaveDotOrg", "history": [ @@ -72,6 +74,7 @@ offset ] }, { + "id": "415", "name": "introduction", "url": "https://mastodon.social/tags/introduction", "history": [