docs-mastodon/content/zh-cn/methods/accounts.md at f7e0b18748edfa56f0ca1fadbc10dc628b126cea

wholetrans/docs-mastodon

Fork 0

CDN f7e0b18748

Update zh-cn translation snippets

2025-04-21 08:11:27 +08:00

59 KiB

Raw Blame History

title

description

aliases

accounts API 方法

关于账户和账户资料的方法。

docs

weight	name	parent	identifier
20	accounts	methods	methods-accounts

/methods/accounts

/api/methods/accounts

注册账户

POST /api/v1/accounts HTTP/1.1

创建账户记录。返回发起请求的应用的账户访问令牌。应用应保存此令牌以供将来使用，并应等待用户通过点击其电子邮件收件箱中的链接来确认其账户。

OAuth 应用和创建的用户账户之间的关系将被存储。

返回: [Token]({{< relref "entities/token" >}})
OAuth: 应用令牌 + write:accounts
版本历史:
2.7.0 - 添加
3.0.0 - 添加 reason 参数
3.4.0 - 向失败响应添加 details
4.4.0 - 添加 date_of_birth 参数

请求

标头

Authorization: {{}} 提供此标头与 Bearer <app_token>，以获得对此 API 方法的访问授权。

表单数据参数

username: {{}} 字符串。账户所需的用户名。
email: {{}} 字符串。用于登录的电子邮件地址。
password: {{}} 字符串。用于登录的密码。
agreement: {{}} 布尔值。用户是否同意本站规则、条款和政策。应向用户展示这些内容，以便他们在将此参数设置为 TRUE 之前表示同意。
locale: {{}} 字符串。将发送的确认电子邮件的语言。
reason: 字符串。若注册需要手动批准，则版主将审查此文本。
date_of_birth: 字符串 (Date)，若实例有最低年龄要求，则为必填。

响应

200: OK

401: Unauthorized

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

422: Unprocessable entity

details 参数包含所有检测到的错误。其结构是一个哈希，键是错误的参数，值是找到的所有错误的数组。

错误响应示例：

{
  "error": "Validation failed: Password can't be blank, Username must contain only letters, numbers and underscores, Agreement must be accepted",
  "details": {
    "password": [
      {
        "error": "ERR_BLANK",
        "description": "can't be blank"
      }
    ],
    "username": [
      {
        "error": "ERR_INVALID",
        "description": "must contain only letters, numbers and underscores"
      }
    ],
    "agreement": [
      {
        "error": "ERR_ACCEPTED",
        "description": "must be accepted"
      }
    ]
  }
}

你可能会遇到以下错误：

ERR_BLOCKED: 当电子邮件提供商不被允许时出现
ERR_UNREACHABLE: 当电子邮件地址无法通过 DNS（MX、A、AAAA）解析到任何 IP 时出现
ERR_TAKEN: 当用户名或电子邮件已被占用时出现
ERR_RESERVED: 当用户名被保留时出现，例如注册使用的用户名为“webmaster”或“admin”
ERR_ACCEPTED: 当未接受协议时出现
ERR_BLANK: 当未填写必填项时出现
ERR_INVALID: 当某一项格式错误时，例如错误的字符或无效的电子邮件地址出现
ERR_TOO_LONG: 当某一项超过字符数限制时出现
ERR_TOO_SHORT: 当某一项低于字符数要求时出现
ERR_INCLUSION: 当某一项的值不是允许的值之一时出现，例如填写了不受支持的语言

429: Rate limited

{
  "error": "请求过多"
}

验证账户凭据

GET /api/v1/accounts/verify_credentials HTTP/1.1

测试以确保用户令牌有效。

返回: [CredentialAccount]({{< relref "entities/Account#CredentialAccount">}})
OAuth: 用户令牌 + profile 或 read:accounts
版本历史:
0.0.0 - 添加 4.3.0 - 添加 profile 段

请求

标头

Authorization: {{}} 提供此标头与 Bearer <user_token>，以获得对此 API 方法的访问授权。

响应

200: OK

请注意额外的 source 属性，该属性在你自己的账户之外不可见。另请注意，纯文本用于 source 中，而 HTML 用于其相应的属性，例如 note 和 fields。

{
  "id": "14715",
  "username": "trwnh",
  "acct": "trwnh",
  "display_name": "infinite love ⴳ",
  "locked": false,
  "bot": false,
  "created_at": "2016-11-24T10:02:12.085Z",
  "note": "<p>i have approximate knowledge of many things. perpetual student. (nb/ace/they)</p><p>xmpp/email: a@trwnh.com<br /><a href=\"https://trwnh.com\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a><br />help me live: <a href=\"https://liberapay.com/at\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a> or <a href=\"https://paypal.me/trwnh\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">paypal.me/trwnh</span><span class=\"invisible\"></span></a></p><p>- my triggers are moths and glitter<br />- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise<br />- dm me if i did something wrong, so i can improve<br />- purest person on fedi, do not lewd in my presence<br />- #1 ami cole fan account</p><p>:fatyoshi:</p>",
  "url": "https://mastodon.social/@trwnh",
  "avatar": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
  "avatar_static": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
  "header": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
  "header_static": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
  "followers_count": 821,
  "following_count": 178,
  "statuses_count": 33120,
  "last_status_at": "2019-11-24T15:49:42.251Z",
  "source": {
    "privacy": "public",
    "sensitive": false,
    "language": "",
    "note": "i have approximate knowledge of many things. perpetual student. (nb/ace/they)\r\n\r\nxmpp/email: a@trwnh.com\r\nhttps://trwnh.com\r\nhelp me live: https://liberapay.com/at or https://paypal.me/trwnh\r\n\r\n- my triggers are moths and glitter\r\n- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise\r\n- dm me if i did something wrong, so i can improve\r\n- purest person on fedi, do not lewd in my presence\r\n- #1 ami cole fan account\r\n\r\n:fatyoshi:",
    "fields": [
      {
        "name": "Website",
        "value": "https://trwnh.com",
        "verified_at": "2019-08-29T04:14:55.571+00:00"
      },
      {
        "name": "Sponsor",
        "value": "https://liberapay.com/at",
        "verified_at": "2019-11-15T10:06:15.557+00:00"
      },
      {
        "name": "Fan of:",
        "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
        "verified_at": null
      },
      {
        "name": "Main topics:",
        "value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people!",
        "verified_at": null
      }
    ],
    "follow_requests_count": 0
  },
  "emojis": [
    {
      "shortcode": "fatyoshi",
      "url": "https://files.mastodon.social/custom_emojis/images/000/023/920/original/e57ecb623faa0dc9.png",
      "static_url": "https://files.mastodon.social/custom_emojis/images/000/023/920/static/e57ecb623faa0dc9.png",
      "visible_in_picker": true
    }
  ],
  "fields": [
    {
      "name": "Website",
      "value": "<a href=\"https://trwnh.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-08-29T04:14:55.571+00:00"
    },
    {
      "name": "Sponsor",
      "value": "<a href=\"https://liberapay.com/at\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-11-15T10:06:15.557+00:00"
    },
    {
      "name": "Fan of:",
      "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo&apos;s Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
      "verified_at": null
    },
    {
      "name": "Main topics:",
      "value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i&apos;m just here to hang out and talk to cool people!",
      "verified_at": null
    }
  ]
}

401: Unauthorized

若令牌无效或不正确，凭据验证将失败。

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

403: Forbidden

你的用户账户当前已禁用，缺少已验证的电子邮件地址或正在等待批准。

{
  "error": "Your login is currently disabled"
}

{
  "error": "Your login is missing a confirmed e-mail address"
}

{
  "error": "Your login is currently pending approval"
}

422: Unprocessable entity

令牌没有授权用户

{
  "error": "This method requires an authenticated user"
}

更新账户凭据

PATCH /api/v1/accounts/update_credentials HTTP/1.1

更新用户的显示和偏好设置。

返回: 用户自己的 [Account]({{< relref "entities/Account">}})，带有 [source]({{< relref "entities/Account#source">}}) 属性
OAuth: 用户令牌 + write:accounts
版本历史:
1.1.1 - 添加
2.3.0 - 添加 locked 参数
2.4.0 - 添加 source[privacy,sensitive] 参数
2.4.2 - 添加 source[language] 参数
2.7.0 - 添加 discoverable 参数
4.1.0 - 添加 hide_collections 参数
4.2.0 - 添加 indexable 参数
4.4.0 (mastodon [API 版本]({{< relref "entities/Instance#api-versions" >}}) 3) - 添加 attribution_domains 参数

请求

标头

Authorization: {{}} 提供此标头与 Bearer <user_token>，以获得对此 API 方法的访问授权。

表单数据参数

display_name: 字符串。用于 profile 的昵称。
note: 字符串。账户简介。
avatar: 使用“multipart/form-data”编码的头像图片
header: 使用“multipart/form-data”编码的横幅图片
locked: 布尔值。是否需要手动批准关注请求。
bot: 布尔值。账户是否具有机器人标志。
discoverable: 布尔值。账户是否应被展示在用户列表中。
hide_collections: 布尔值。是否隐藏关注者和关注的账户。
indexable: 布尔值。公开嘟文是否应可供任何人搜索。
attribution_domains[]: 字符串数组。允许授权该账户的网站域名。
fields_attributes: 哈希。要设置的个人资料字段。在此哈希中，键是被强制转换为字符串的整数（尽管确切的整数并不重要），值是另一个包含 name 和 value 的哈希。默认情况下，最多 4 个字段。
fields_attributes[:index][name]: 字符串。个人资料字段的名称。默认情况下，最多 255 个字符。
fields_attributes[:index][value]: 字符串。个人资料字段的值。默认情况下，最多 255 个字符。
source[privacy]: 字符串。默认发嘟可见性设置。可以是“public”、“unlisted”或“private”。
source[sensitive]: 布尔值。是否默认将嘟文标记为敏感。
source[language]: 字符串。新嘟文默认语言（ISO 6391）

响应

200: OK

要更新账户字段，你需要参照一下结构构造你的哈希，例如：

{
  "fields_attributes": {
    "0": {
      "name": "Website",
      "value": "https://trwnh.com"
    },
    "1": {
      "name": "Sponsor",
      "value": "https://liberapay.com/at"
    },
    // ...
  }
}

作为查询参数，你的请求可能如下所示：

PATCH https://mastodon.example/api/v1/accounts/update_credentials
?fields_attributes[0][name]=Website
&fields_attributes[0][value]=https://trwnh.com
&fields_attributes[1][name]=Sponsor
&fields_attributes[1][value]=https://liberapay.com/at
&...

请注意，整数索引实际上并不重要 - 字段将按提供的顺序填充。例如：

{
  "fields_attributes": {
    "420": {
      "name": "1st",
      "value": "field"
    },
    "69": {
      "name": "2nd",
      "value": "field"
    },
    "1312": {
      "name": "3rd",
      "value": "field"
    },
    "-99999999999999999999999999999999": {
      "name": "4th",
      "value": "field"
    },
  }
}

你应该使用 accounts/verify_credentials，首先从 source 参数中获取纯文本表示形式，然后允许用户编辑这些纯文本表示形式，然后再通过此 API 提交它们。实例将生成相应的 HTML。

{
  "id": "14715",
  "username": "trwnh",
  "acct": "trwnh",
  "display_name": "infinite love ⴳ",
  "locked": false,
  "bot": false,
  "created_at": "2016-11-24T10:02:12.085Z",
  "note": "<p>i have approximate knowledge of many things. perpetual student. (nb/ace/they)</p><p>xmpp/email: a@trwnh.com<br /><a href=\"https://trwnh.com\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a><br />help me live: <a href=\"https://liberapay.com/at\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a> or <a href=\"https://paypal.me/trwnh\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">paypal.me/trwnh</span><span class=\"invisible\"></span></a></p><p>- my triggers are moths and glitter<br />- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise<br />- dm me if i did something wrong, so i can improve<br />- purest person on fedi, do not lewd in my presence<br />- #1 ami cole fan account</p><p>:fatyoshi:</p>",
  "url": "https://mastodon.social/@trwnh",
  "avatar": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
  "avatar_static": "https://files.mastodon.social/accounts/avatars/000/014/715/original/34aa222f4ae2e0a9.png",
  "header": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
  "header_static": "https://files.mastodon.social/accounts/headers/000/014/715/original/5c6fc24edb3bb873.jpg",
  "followers_count": 834,
  "following_count": 182,
  "statuses_count": 33760,
  "last_status_at": "2019-12-01T00:12:08.731Z",
  "source": {
    "privacy": "public",
    "sensitive": false,
    "language": "",
    "note": "i have approximate knowledge of many things. perpetual student. (nb/ace/they)\r\n\r\nxmpp/email: a@trwnh.com\r\nhttps://trwnh.com\r\nhelp me live: https://liberapay.com/at or https://paypal.me/trwnh\r\n\r\n- my triggers are moths and glitter\r\n- i have all notifs except mentions turned off, so please interact if you wanna be friends! i literally will not notice otherwise\r\n- dm me if i did something wrong, so i can improve\r\n- purest person on fedi, do not lewd in my presence\r\n- #1 ami cole fan account\r\n\r\n:fatyoshi:",
    "fields": [
      {
        "name": "Website",
        "value": "https://trwnh.com",
        "verified_at": "2019-08-29T04:14:55.571+00:00"
      },
      {
        "name": "Sponsor",
        "value": "https://liberapay.com/at",
        "verified_at": "2019-11-15T10:06:15.557+00:00"
      },
      {
        "name": "Fan of:",
        "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo's Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
        "verified_at": null
      },
      {
        "name": "Main topics:",
        "value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i'm just here to hang out and talk to cool people!",
        "verified_at": null
      }
    ],
    "follow_requests_count": 0
  },
  "emojis": [
    {
      "shortcode": "fatyoshi",
      "url": "https://files.mastodon.social/custom_emojis/images/000/023/920/original/e57ecb623faa0dc9.png",
      "static_url": "https://files.mastodon.social/custom_emojis/images/000/023/920/static/e57ecb623faa0dc9.png",
      "visible_in_picker": true
    }
  ],
  "fields": [
    {
      "name": "Website",
      "value": "<a href=\"https://trwnh.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">trwnh.com</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-08-29T04:14:55.571+00:00"
    },
    {
      "name": "Sponsor",
      "value": "<a href=\"https://liberapay.com/at\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">liberapay.com/at</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-11-15T10:06:15.557+00:00"
    },
    {
      "name": "Fan of:",
      "value": "Punk-rock and post-hardcore (Circa Survive, letlive., La Dispute, THE FEVER 333)Manga (Yu-Gi-Oh!, One Piece, JoJo&apos;s Bizarre Adventure, Death Note, Shaman King)Platformers and RPGs (Banjo-Kazooie, Boktai, Final Fantasy Crystal Chronicles)",
      "verified_at": null
    },
    {
      "name": "Main topics:",
      "value": "systemic analysis, design patterns, anticapitalism, info/tech freedom, theory and philosophy, and otherwise being a genuine and decent wholesome poster. i&apos;m just here to hang out and talk to cool people!",
      "verified_at": null
    }
  ]
}

401: Unauthorized

{
  "error": "访问令牌无效"
}

422: Unprocessable entity

令牌没有授权用户

{
  "error": "This method requires an authenticated user"
}

获取账户

GET /api/v1/accounts/:id HTTP/1.1

查看账户信息。

返回: [Account]({{< relref "entities/Account">}})
OAuth: 公开
版本历史:
0.0.0 - 添加
2.4.0 - 若账户已封禁，则返回 410
3.3.0 - 返回一个带有 suspended: true 的账户，而不是 410

请求

路径参数

:id: {{}} 字符串。数据库中账户的 ID。

标头

Authorization: 提供此标头与 Bearer <user_token>，以获得对此 API 方法的访问授权。

响应

200: OK

将返回账户记录。请注意，本站用户的 acct 不包括域名。

本站用户

{
  "id": "1",
  "username": "Gargron",
  "acct": "Gargron",
  "display_name": "Eugen",
  "locked": false,
  "bot": false,
  "created_at": "2016-03-16T14:34:26.392Z",
  "note": "<p>Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.</p>",
  "url": "https://mastodon.social/@Gargron",
  "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
  "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
  "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
  "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
  "followers_count": 318699,
  "following_count": 453,
  "statuses_count": 61013,
  "last_status_at": "2019-11-30T20:02:08.277Z",
  "emojis": [],
  "fields": [
    {
      "name": "Patreon",
      "value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>",
      "verified_at": null
    },
    {
      "name": "Homepage",
      "value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-07-15T18:29:57.191+00:00"
    }
  ]
}

外站用户

{
  "id": "23634",
  "username": "noiob",
  "acct": "noiob@awoo.space",
  "display_name": "shork",
  "locked": false,
  "bot": false,
  "created_at": "2017-02-08T02:00:53.274Z",
  "note": "<p>:ms_rainbow_flag: :ms_bisexual_flag: :ms_nonbinary_flag: <a href=\"https://awoo.space/tags/awoo\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>awoo</span></a>.space <a href=\"https://awoo.space/tags/admin\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>admin</span></a> ~ <a href=\"https://awoo.space/tags/bi\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>bi</span></a> ~ <a href=\"https://awoo.space/tags/nonbinary\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>nonbinary</span></a> ~ compsci student ~ likes video <a href=\"https://awoo.space/tags/games\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>games</span></a> and weird/ old electronics and will post obsessively about both ~ avatar by <span class=\"h-card\"><a href=\"https://weirder.earth/@dzuk\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>dzuk</span></a></span></p>",
  "url": "https://awoo.space/@noiob",
  "avatar": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
  "avatar_static": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
  "header": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
  "header_static": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
  "followers_count": 553,
  "following_count": 405,
  "statuses_count": 28982,
  "last_status_at": "2019-12-01T00:39:57.264Z",
  "emojis": [
    {
      "shortcode": "ms_rainbow_flag",
      "url": "https://files.mastodon.social/custom_emojis/images/000/028/691/original/6de008d6281f4f59.png",
      "static_url": "https://files.mastodon.social/custom_emojis/images/000/028/691/static/6de008d6281f4f59.png",
      "visible_in_picker": true
    },
    {
      "shortcode": "ms_bisexual_flag",
      "url": "https://files.mastodon.social/custom_emojis/images/000/050/744/original/02f94a5fca7eaf78.png",
      "static_url": "https://files.mastodon.social/custom_emojis/images/000/050/744/static/02f94a5fca7eaf78.png",
      "visible_in_picker": true
    },
    {
      "shortcode": "ms_nonbinary_flag",
      "url": "https://files.mastodon.social/custom_emojis/images/000/105/099/original/8106088bd4782072.png",
      "static_url": "https://files.mastodon.social/custom_emojis/images/000/105/099/static/8106088bd4782072.png",
      "visible_in_picker": true
    }
  ],
  "fields": [
    {
      "name": "Pronouns",
      "value": "they/them",
      "verified_at": null
    },
    {
      "name": "Alt",
      "value": "<span class=\"h-card\"><a href=\"https://cybre.space/@noiob\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>noiob</span></a></span>",
      "verified_at": null
    },
    {
      "name": "Bots",
      "value": "<span class=\"h-card\"><a href=\"https://botsin.space/@darksouls\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>darksouls</span></a></span>, <span class=\"h-card\"><a href=\"https://botsin.space/@nierautomata\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>nierautomata</span></a></span>, code for <span class=\"h-card\"><a href=\"https://botsin.space/@awoobot\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>awoobot</span></a></span>",
      "verified_at": null
    },
    {
      "name": "Website",
      "value": "<a href=\"http://shork.xyz\" rel=\"nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">http://</span><span class=\"\">shork.xyz</span><span class=\"invisible\"></span></a>",
      "verified_at": "2019-11-23T20:25:47.907+00:00"
    }
  ]
}

已封禁用户

{
  "id": "14",
  "username": "stigatle",
  "acct": "stigatle@quitter.no",
  "display_name": "",
  "locked": false,
  "bot": false,
  "discoverable": false,
  "group": false,
  "created_at": "2016-03-18T10:04:51.700Z",
  "note": "",
  "url": "https://quitter.no/stigatle",
  "avatar": "https://mastodon.social/avatars/original/missing.png",
  "avatar_static": "https://mastodon.social/avatars/original/missing.png",
  "header": "https://mastodon.social/headers/original/missing.png",
  "header_static": "https://mastodon.social/headers/original/missing.png",
  "followers_count": 0,
  "following_count": 0,
  "statuses_count": 0,
  "last_status_at": null,
  "suspended": true,
  "emojis": [],
  "fields": []
}

401: Unauthorized

若实例处于白名单模式，且 Authorization 标头缺失或无效。

{
  "error": "此 API 需要已认证的用户"
}

404: Not found

账户不存在。

{
  "error": "记录未找到"
}

410: Gone

账户已被封禁（版本 2.4.0 起至 3.3.0 止）。

获取多个账户信息

GET /api/v1/accounts HTTP/1.1

查看多个账户的信息。

返回： [Account]({{< relref "entities/Account">}}) 数组 OAuth： 公开 版本历史： 4.3.0 - 添加

请求

标头

查询参数

id[]: 字符串数组。数据库中账户的 ID。

标头

Authorization: 提供此标头并附带 Bearer <用户令牌> 以获得对此 API 方法的访问授权。

响应

200: OK

将返回请求的已验证且已被批准账户的 [Account]({{< relref "entities/Account">}}) 记录。若账户不存在或未确认，返回的记录数可能会少于请求的数量。

使用 id[]=1&id[]=2 的调用示例（当 ID 为 2 的账户不存在时）：

[
  {
    "id": "1",
    "username": "Gargron",
    "acct": "Gargron",
    "display_name": "Eugen",
    "locked": false,
    "bot": false,
    "created_at": "2016-03-16T14:34:26.392Z",
    "note": "<p>Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.</p>",
    "url": "https://mastodon.social/@Gargron",
    "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
    "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
    "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
    "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
    "followers_count": 318699,
    "following_count": 453,
    "statuses_count": 61013,
    "last_status_at": "2019-11-30T20:02:08.277Z",
    "emojis": [],
    "fields": [
      {
        "name": "Patreon",
        "value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>",
        "verified_at": null
      },
      {
        "name": "Homepage",
        "value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span></a>",
        "verified_at": "2019-07-15T18:29:57.191+00:00"
      }
    ]
  }
]

401: Unauthorized

若实例处于白名单模式，且 Authorization 标头缺失或无效，则返回此错误。

{
  "error": "This API requires an authenticated user"
}

获取账户的嘟文

GET /api/v1/accounts/:id/statuses HTTP/1.1

获取指定账户发布的嘟文。

返回： [Status]({{< relref "entities/status">}}) 数组 OAuth： 公开访问（仅限公开嘟文），或用户令牌 + read:statuses（用于访问用户有权查看的私密嘟文） 版本历史： 0.0.0 - 添加 1.4.2 - 添加 only_media 和 exclude_replies 1.6.0 - 添加 pinned 2.6.0 - 添加 min_id 2.7.0 - 添加 exclude_reblogs 并允许未经身份验证的使用 2.8.0 - 添加 tagged 参数 3.3.0 - 现在可以同时使用 min_id 和 max_id

请求

路径参数

:id: {{}} 字符串。数据库中账户的 ID。

标头

Authorization: 提供此标头并附带 Bearer <用户令牌> 以获得对此 API 方法的访问授权。

查询参数

max_id: 字符串。返回的所有结果 ID 都将小于此 ID。事实上设置结果的上限。
since_id: 字符串。返回的所有结果 ID 都将大于此 ID。事实上是设置结果的下限。
min_id: 字符串。返回紧邻此 ID 之后的新结果。事实上在此 ID 设置游标并向前分页。
limit: 整数。返回的最大结果数。默认为 20 条嘟文。最多 40 条嘟文。
only_media: 布尔值。过滤没有附件的嘟文。
exclude_replies: 布尔值。过滤回复给其他账户的嘟文。
exclude_reblogs: 布尔值。过滤转嘟。
pinned: 布尔值。仅筛选置顶的嘟文。默认为 false，包含所有嘟文。置顶嘟文在返回结果的顺序中没有特殊优先级。
tagged: 字符串。筛选使用了特定话题标签的嘟文。

响应

200: OK

[
  {
    "id": "108880211901672326",
    "created_at": "2022-08-24T22:29:46.493Z",
    "in_reply_to_id": "108880209317577809",
    "in_reply_to_account_id": "103641",
    "sensitive": false,
    // ...
  },
  // ...
]

401: Unauthorized

若实例处于白名单模式，且 Authorization 标头缺失或无效，则返回此错误。

白名单模式的响应示例：

{
  "error": "This API requires an authenticated user"
}

2.7.0 版本之前的响应示例：

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

404: Not found

账户不存在。

{
  "error": "Record not found"
}

410: Gone

账户已被封禁（版本 2.4.0 起至 3.3.0 止）。

获取账户的关注者

GET /api/v1/accounts/:id/followers HTTP/1.1

获取关注指定账户的用户列表，前提是该账户所有者未隐藏其社交关系网络。

返回： [Account]({{< relref "entities/Account">}}) 数组 OAuth： 公开访问 版本历史： 0.0.0 - 添加 3.3.0 - 现在可以同时使用 min_id 和 max_id 4.0.0 - 不再需要应用令牌 + read:accounts

请求

路径参数

:id: {{}} 字符串。数据库中账户的 ID。

标头

Authorization: 提供此标头并附带 Bearer <用户令牌> 以获得对此 API 方法的访问授权。

查询参数

max_id: 内部参数。 使用 HTTP Link 标头进行分页。
since_id: 内部参数。 使用 HTTP Link 标头进行分页。
min_id: 内部参数。 使用 HTTP Link 标头进行分页。
limit: 整数。返回的最大结果数。默认为 40 个账户。最多 80 个账户。

响应

200: OK

limit=2 的输出示例。

[
  {
    "id": "1020382",
    "username": "atul13061987",
    "acct": "atul13061987",
    "display_name": "",
    // ...
  },
  {
    "id": "1020381",
    "username": "linuxliner",
    "acct": "linuxliner",
    "display_name": "",
    // ...
  }
]

由于关注关系 ID 通常不会通过任何 API 响应公开，你需要解析 HTTP Link 标头来加载更早或更新的结果。更多信息请参见 [通过 API 响应分页]({{<relref "api/guidelines#pagination">}})。

Link: <https://mastodon.example/api/v1/accounts/14715/followers?limit=2&max_id=7486869>; rel="next", <https://mastodon.example/api/v1/accounts/14715/followers?limit=2&since_id=7489740>; rel="prev"

401: Unauthorized

Authorization 标头无效或缺失，或者实例处于白名单模式且你的令牌未获得用户授权。

白名单模式的响应示例：

{
  "error": "This API requires an authenticated user"
}

标头缺失或令牌无效的响应示例：

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

404: Not found

账户不存在。

{
  "error": "Record not found"
}

410: Gone

账户已被封禁（版本 2.4.0 起至 3.3.0 止）。

获取账户正在关注的用户

GET /api/v1/accounts/:id/following HTTP/1.1

获取指定账户正在关注的用户列表，前提是该账户所有者未隐藏其社交关系网络。

请求

路径参数

:id: {{}} 字符串。数据库中账户的 ID。

标头

Authorization: 提供此标头并附带 Bearer <用户令牌> 以获得对此 API 方法的访问授权。

查询参数

max_id: 内部参数。 使用 HTTP Link 标头进行分页。
since_id: 内部参数。 使用 HTTP Link 标头进行分页。
min_id: 内部参数。 使用 HTTP Link 标头进行分页。
limit: 整数。返回的最大结果数。默认为 40 个账户。最多 80 个账户。

响应

200: OK

limit=2 的输出示例。

[
  {
    "id": "963410",
    "username": "gautambhatia",
    "acct": "gautambhatia",
    "display_name": "Gautam Bhatia",
    // ...
  },
  {
    "id": "1007400",
    "username": "seafrog",
    "acct": "seafrog@glitterkitten.co.uk",
    "display_name": "🐓🦃 Heck Partridge 🤠 🦆",
    // ...
]

Link: <https://mastodon.example/api/v1/accounts/1/followers?limit=2&max_id=7628164>; rel="next", <https://mastodon.example/api/v1/accounts/1/followers?limit=2&since_id=7628165>; rel="prev"

401: Unauthorized

Authorization 标头无效或缺失，或者实例处于白名单模式且你的令牌未获得用户授权。

白名单模式的响应示例：

{
  "error": "This API requires an authenticated user"
}

标头缺失或令牌无效的响应示例：

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

404: Not found

账户不存在。

{
  "error": "Record not found"
}

410: Gone

账户已被封禁（版本 2.4.0 起至 3.3.0 止）。

获取账户的精选话题标签

GET /api/v1/accounts/:id/featured_tags HTTP/1.1

获取此账户的精选话题标签。

返回： [FeaturedTag]({{< relref "entities/featuredtag">}}) 数组 OAuth： 公开 版本历史： 3.3.0 - 添加

请求

路径参数

:id: {{}} 字符串。数据库中账户的 ID。

标头

Authorization: 提供此标头并附带 Bearer <用户令牌> 以获得对此 API 方法的访问授权。

响应

200: OK

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

获取包含此账户的列表

GET /api/v1/accounts/:id/lists HTTP/1.1

获取你已将此账户添加到的用户列表。

返回： [List]({{< relref "entities/list">}}) 数组 OAuth： 用户令牌 + read:lists 版本历史： 2.1.0 - 添加

请求

路径参数

:id: {{}} 字符串。数据库中账户的 ID。

标头

Authorization: {{}} 提供此标头并附带 Bearer <用户令牌> 以获得对此 API 方法的访问授权。

响应

200: OK

若该账户属于任何列表，将返回这些列表的实体。若该账户不属于你的任何列表，则返回空数组。

[
  {
    "id": "13694",
    "title": "dev"
  }
]

[]

401: Unauthorized

Authorization 标头无效或缺失，或者实例处于白名单模式且你的令牌未获得用户授权。

白名单模式的响应示例：

{
  "error": "This API requires an authenticated user"
}

标头缺失或令牌无效的响应示例：

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

404: Not found

账户不存在。

{
  "error": "Record not found"
}

410: Gone

账户已被封禁（版本 2.4.0 起至 3.3.0 止）。

422: Unprocessable entity

令牌没有授权用户。

{
  "error": "This method requires an authenticated user"
}

关注账户

POST /api/v1/accounts/:id/follow HTTP/1.1

关注指定账户。也可用于更新是否显示转嘟或启用通知。

返回： [Relationship]({{< relref "entities/relationship">}}) OAuth： 用户令牌 + write:follows 版本历史： 0.0.0 - 添加 3.3.0 - 添加 notify 3.5.0 - 弃用 follow 作用域。现在额外接受 write 4.0.0 - 添加 languages

请求

路径参数

:id: {{}} 字符串。数据库中账户的 ID。

标头

Authorization: {{}} 提供此标头并附带 Bearer <用户令牌> 以获得对此 API 方法的访问授权。

表单数据参数

reblogs: 布尔值。是否在主页时间线上接收此账户的转嘟？默认为 true。
notify: 布尔值。当此账户发布嘟文时是否接收通知？默认为 false。
languages[]: 字符串数组（ISO 639-1 双字符语言代码）。根据设置的语言过滤接收到的嘟文。若未提供，你将接收此账户所有语言的嘟文。

响应

200: OK

成功关注，或账户已被关注。

{
  "id": "3",
  "following": true,
  "showing_reblogs": false,
  "notifying": false,
  "followed_by": false,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}

403: Forbidden

试图关注你屏蔽的或屏蔽你的用户。

{
  "error": "This action is not allowed"
}

422: Unprocessable entity

令牌没有授权用户。

{
  "error": "This method requires an authenticated user"
}

取消关注账户

POST /api/v1/accounts/:id/unfollow HTTP/1.1

取消关注指定账户。

返回： [Relationship]({{< relref "entities/relationship">}}) OAuth： 用户令牌 + write:follows 版本历史： 0.0.0 - 添加 3.5.0 - 弃用 follow 作用域。现在额外接受 write

请求

路径参数

:id: {{}} 字符串。数据库中账户的 ID。

标头

Authorization: {{}} 提供此标头并附带 Bearer <用户令牌> 以获得对此 API 方法的访问授权。

响应

200: OK

成功取消关注，或账户本未被关注。

{
  "id": "3",
  "following": false,
  "showing_reblogs": false,
  "notifying": false,
  "followed_by": false,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}

401: Unauthorized

Authorization 标头无效或缺失

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

422: Unprocessable entity

令牌没有已授权的用户

{
  "error": "This method requires an authenticated user"
}

屏蔽账户

POST /api/v1/accounts/:id/block HTTP/1.1

屏蔽指定的账户。客户端应过滤来自此账户的嘟文（例如，由于主页时间线上的转嘟而收到的嘟文）。

返回： [Relationship]({{< relref "entities/relationship">}})
OAuth： 用户令牌 + write:blocks
版本历史：
0.0.0 - 添加
3.5.0 - 弃用了 follow 作用域。现在额外接受 write

请求

路径参数

:id: {{}} 字符串。账户在数据库中的 ID。

标头

Authorization: {{}} 提供此标头，格式为 Bearer <user_token>，以获取对此 API 方法的访问授权。

响应

200: OK

成功屏蔽，或账户已被屏蔽

{
  "id": "3",
  "following": false,
  "showing_reblogs": false,
  "notifying": false,
  "followed_by": false,
  "blocking": true,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}

401: Unauthorized

Authorization 标头无效或缺失

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

422: Unprocessable entity

令牌没有已授权的用户

{
  "error": "This method requires an authenticated user"
}

解除屏蔽账户

POST /api/v1/accounts/:id/unblock HTTP/1.1

解除对指定账户的屏蔽。

请求

路径参数

:id: {{}} 字符串。账户在数据库中的 ID。

标头

Authorization: {{}} 提供此标头，格式为 Bearer <user_token>，以获取对此 API 方法的访问授权。

响应

200: OK

成功解除屏蔽，或账户本就未被屏蔽

{
  "id": "3",
  "following": false,
  "showing_reblogs": false,
  "notifying": false,
  "followed_by": false,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}

401: Unauthorized

Authorization 标头无效或缺失

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

422: Unprocessable entity

令牌没有已授权的用户

{
  "error": "This method requires an authenticated user"
}

隐藏账户

POST /api/v1/accounts/:id/mute HTTP/1.1

隐藏指定的账户。客户端应过滤来自此账户的嘟文和通知（例如，由于主页时间线上的转嘟而收到的嘟文）。

返回： [Relationship]({{< relref "entities/relationship">}})
OAuth： 用户令牌 + write:mutes
版本历史：
0.0.0 - 添加
3.3.0 - 添加了 duration
3.5.0 - 弃用了 follow 作用域。现在额外接受 write

请求

路径参数

:id: {{}} 字符串。账户在数据库中的 ID。

标头

Authorization: {{}} 提供此标头，格式为 Bearer <user_token>，以获取对此 API 方法的访问授权。

表单数据参数

notifications: 布尔值。除了嘟文之外是否也隐藏通知？默认为 true。
duration: 数字。隐藏应持续多长时间（秒）。默认为 0（无限期）。

响应

200: OK

成功隐藏，或账户已被隐藏。请注意，你可以再次调用此 API 方法并设置 notifications=false 来更新关系，以便仅隐藏嘟文。

{
  "id": "3",
  "following": false,
  "showing_reblogs": false,
  "notifying": false,
  "followed_by": false,
  "blocking": false,
  "blocked_by": false,
  "muting": true,
  "muting_notifications": true,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}

401: Unauthorized

Authorization 标头无效或缺失

{
  "error": "访问令牌无效"
}

422: Unprocessable entity

令牌没有已授权的用户

{
  "error": "此方法需要已认证的用户"
}

解除隐藏账户

POST /api/v1/accounts/:id/unmute HTTP/1.1

解除对指定账户的隐藏。

返回： [Relationship]({{< relref "entities/relationship">}})
OAuth： 用户令牌 + write:mutes
版本历史：
0.0.0 - 添加
3.5.0 - 弃用了 follow 作用域。现在额外接受 write

请求

路径参数

:id: {{}} 字符串。账户在数据库中的 ID。

标头

Authorization: {{}} 提供此标头，格式为 Bearer <user_token>，以获取对此 API 方法的访问授权。

响应

200: OK

成功解除隐藏，或账户本就未被隐藏

{
  "id": "3",
  "following": false,
  "showing_reblogs": false,
  "notifying": false,
  "followed_by": false,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}

401: Unauthorized

Authorization 标头无效或缺失

{
  "error": "访问令牌无效"
}

422: Unprocessable entity

令牌没有已授权的用户

{
  "error": "此方法需要已认证的用户"
}

在你的账户页中推荐账户

POST /api/v1/accounts/:id/pin HTTP/1.1

将指定账户添加到用户的推荐账户中。（推荐的账户目前显示在用户自己的账户页上公开显示。）

返回： [Relationship]({{< relref "entities/relationship">}})
OAuth： 用户令牌 + write:accounts
版本历史：
2.5.0 - 添加
4.0.0 - 调用此方法现在是幂等的

请求

路径参数

:id: {{}} 字符串。账户在数据库中的 ID。

标头

Authorization: {{}} 提供此标头，格式为 Bearer <user_token>，以获取对此 API 方法的访问授权。

响应

200: OK

成功推荐，或目标账户已被推荐。

{
  "id": "1",
  "following": true,
  "showing_reblogs": true,
  "notifying": false,
  "followed_by": true,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": true
}

401: Unauthorized

Authorization 标头无效或缺失

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

403: 禁止访问

令牌缺少必要的范围

{
  "error": "This operation exceeds the authorization scope"
}

422: Unprocessable entity

你没有关注此账户

{
  "error": "Validation failed: You must be already following the person you want to endorse"
}

或者，令牌未获得用户授权

{
  "error": "This method requires an authenticated user"
}

或者（4.0 版本之前），该账户可能已被推荐

{
  "error": "Duplicate record"
}

500: 服务器错误

有时在账户已被推荐时会返回此错误。

在账户页中取消推荐账户

POST /api/v1/accounts/:id/unpin HTTP/1.1

将指定账户从用户的推荐账户中移除。

返回： [Relationship]({{< relref "entities/relationship">}})
OAuth： 用户 + write:accounts
版本历史：
2.5.0 - 添加

请求

路径参数

:id: {{}} 字符串。账户在数据库中的 ID。

标头

Authorization: {{}} 提供此标头，格式为 Bearer <user_token>，以获取对此 API 方法的访问授权。

响应

200: OK

成功取消推荐，或账户本就未被推荐

{
  "id": "1",
  "following": true,
  "showing_reblogs": true,
  "notifying": false,
  "followed_by": true,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false
}

401: Unauthorized

Authorization 标头无效或缺失

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

422: Unprocessable entity

令牌没有已授权的用户

{
  "error": "This method requires an authenticated user"
}

对指定账户设置私人备注

POST /api/v1/accounts/:id/note HTTP/1.1

对指定账户设置私人备注。

返回： [Relationship]({{< relref "entities/relationship">}})
OAuth： 用户 + write:accounts
版本历史：
3.2.0 - 添加

请求

路径参数

:id: {{}} 字符串。账户在数据库中的 ID。

标头

Authorization: {{}} 提供此标头，格式为 Bearer <user_token>，以获取对此 API 方法的访问授权。

表单数据参数

comment: 字符串。要对该账户设置的备注。提供空字符串或省略此参数以清除当前设置的备注。

响应

200: OK

成功更新账户备注

{
  "id": "1",
  "following": true,
  "showing_reblogs": true,
  "notifying": false,
  "followed_by": true,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false,
  "note": "这是一条备注"
}

成功移除账户备注

{
  "id": "1",
  "following": true,
  "showing_reblogs": true,
  "notifying": false,
  "followed_by": true,
  "blocking": false,
  "blocked_by": false,
  "muting": false,
  "muting_notifications": false,
  "requested": false,
  "domain_blocking": false,
  "endorsed": false,
  "note": ""
}

401: Unauthorized

Authorization 标头无效或缺失

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

422: Unprocessable entity

令牌没有已授权的用户

{
  "error": "This method requires an authenticated user"
}

检查与其他账户的关系

GET /api/v1/accounts/relationships HTTP/1.1

查明是否关注、屏蔽、隐藏了指定账户等。

返回： [Relationship]({{< relref "entities/Relationship">}}) 数组
OAuth： 用户令牌 + read:follows
版本历史：
0.0.0 - 添加
4.3.0 - 添加了 with_suspended 参数

请求

标头

Authorization: {{}} 提供此标头，格式为 Bearer <user_token>，以获取对此 API 方法的访问授权。

查询参数

id[]: 字符串数组。检查与所提供的所有账户 ID 的关系。
with_suspended: 布尔值。是否应返回已封禁用户的关系，默认为 false。

响应

200: OK

使用 id[]=1&id[]=2 的示例调用

[
  {
    "id": "1",
    "following": true,
    "showing_reblogs": true,
    "notifying": false,
    "followed_by": true,
    "blocking": false,
    "blocked_by": false,
    "muting": false,
    "muting_notifications": false,
    "requested": false,
    "domain_blocking": false,
    "endorsed": false
  },
  {
    "id": "2",
    "following": false,
    "showing_reblogs": false,
    "notifying": false,
    "followed_by": false,
    "blocking": false,
    "blocked_by": false,
    "muting": false,
    "muting_notifications": false,
    "requested": false,
    "domain_blocking": false,
    "endorsed": false
  }
]

401: Unauthorized

Authorization 标头无效或缺失

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

422: Unprocessable entity

令牌没有已授权的用户

{
  "error": "This method requires an authenticated user"
}

查找熟悉的关注者

GET /api/v1/accounts/familiar_followers HTTP/1.1

获取关注指定账户的所有账户列表，并从中筛选出你关注的账户。

返回： [FamiliarFollowers]({{< relref "entities/FamiliarFollowers">}}) 数组
OAuth： 用户令牌 + read:follows
版本历史：
3.5.0 - 添加

请求

标头

Authorization: {{}} 提供此标头，格式为 Bearer <user_token>，以获取对此 API 方法的访问授权。

查询参数

id[]: 字符串数组。查找所提供账户 ID 的熟悉关注者。

响应

200: OK

使用 id[]=1&id[]=2 的示例调用

[
  {
    "id":"1",
    "accounts":[
      {
        "id":"1087990",
        "username":"moss",
        "acct":"moss@goblin.camp",
        // ...
      },
      {
        "id":"1092723",
        "username":"vivianrose",
        "acct":"vivianrose",
        // ...
      },
      // ...
    ]
  },
  {
    "id":"2",
    "accounts":[]
  }
]

401: Unauthorized

Authorization 标头无效或缺失

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

422: Unprocessable entity

令牌没有已授权的用户

{
  "error": "This method requires an authenticated user"
}

搜索匹配的账户

GET /api/v1/accounts/search HTTP/1.1

通过用户名或昵称搜索匹配的账户。

返回： [A此count]({{< relref "entities/Account">}}) 数组 OAuth 认证： 用户令牌 + read:accounts 权限 版本历史： 0.0.0 - 添加 2.8.0 - 添加 limit、offset 和 following

请求

请求头

Authorization: {{}} （必填）提供此请求头，格式为 Bearer <user_token>，以获得对该 API 方法的授权访问权限。

查询参数

q: {{}} （必填）字符串。账户的搜索查询。
limit: 整数。最大结果数。默认为 40 个账户。最多 80 个账户。
offset: 整数。跳过前 n 个结果。
resolve: 布尔值。尝试 WebFinger 查询。默认为 false。当 q 是精确地址时使用此参数。
following: 布尔值。将搜索范围限制为你关注的用户。默认为 false。

响应

200: OK

匹配用户名或昵称中包含 "trwnh" 的账户

[
  {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    "display_name": "infinite love ⴳ",
    // ...
  },
  {
    "id": "418714",
    "username": "trwnh",
    "acct": "trwnh@pixelfed.social",
    "display_name": "Abdullah Tarawneh",
    // ...
  },
  {
    "id": "419674",
    "username": "trwnh",
    "acct": "trwnh@write.as",
    "display_name": "trwnh",
    // ...
  },
  // ...
]

503: Service Unavailable

当 resolve=true 时，若 user@domain 地址中的域名部分当前不是一个有效的网站，则返回该响应

{
  "error": "Remote data could not be fetched"
}

通过 Webfinger 地址查询账户 ID

GET /api/v1/accounts/lookup HTTP/1.1

快速查询用户名以查看其是否可用，跳过 WebFinger 解析。

返回： [Account]({{< relref "entities/Account">}}) OAuth 认证： 公开 版本历史： 3.4.0 - 添加

请求

查询参数

acct: {{}} （必填）字符串。要查询的用户名或 Webfinger 地址。

响应

200: OK

使用 ?acct=trwnh 的示例调用响应如下:

{
  "id": "14715",
  "username": "trwnh",
  "acct": "trwnh",
  "display_name": "infinite love ⴳ",
  "locked": false,
  // ...
}

使用 ?acct=trwnh@pixelfed.social 的示例调用响应如下:

{
  "id": "418714",
  "username": "trwnh",
  "acct": "trwnh@pixelfed.social",
  "display_name": "Abdullah Tarawneh",
  "locked": false,
  // ...
}

404: Not found

用户名或地址未映射到任何账户

{
  "error": "记录未找到"
}

身份证明 {{%deprecated%}}

GET /api/v1/accounts/:id/identity_proofs HTTP/1.1

返回： [IdentityProof]({{< relref "entities/identityproof">}}) 数组 OAuth 认证： 用户令牌 版本历史： 2.8.0 - 添加 3.5.0 - 弃用。现在返回一个空数组。

请求

路径参数

:id: {{}} （必填）字符串。数据库中账户的 ID。

响应

200: OK (成功)

[
  {
    "provider": "Keybase",
    "provider_username": "gargron",
    "updated_at": "2019-07-21T20:14:39.596Z",
    "proof_url": "https://keybase.io/gargron/sigchain#5cfc20c7018f2beefb42a68836da59a792e55daa4d118498c9b1898de7e845690f",
    "profile_url": "https://keybase.io/gargron"
  }
]

404: Not Found

账户不存在

{
  "error": "Record not found"
}

410: Gone

账户已被暂停（自 2.4.0 版本起，至 3.3.0 版本）

422: Unprocessable Entity

令牌没有对应的授权用户

{
  "error": "This method requires an authenticated user"
}

另请参阅

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts_controller.rb" caption="app/controllers/api/v1/accounts_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/credentials_controller.rb" caption="app/controllers/api/v1/accounts/credentials_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/familiar_followers_controller.rb" caption="app/controllers/api/v1/accounts/familiar_followers_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/featured_tags_controller.rb" caption="app/controllers/api/v1/accounts/featured_tags_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/follower_accounts_controller.rb" caption="app/controllers/api/v1/accounts/follower_accounts_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/following_accounts_controller.rb" caption="app/controllers/api/v1/accounts/following_accounts_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/identity_proofs_controller.rb" caption="app/controllers/api/v1/accounts/identity_proofs_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/lists_controller.rb" caption="app/controllers/api/v1/accounts/lists_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/lookup_controller.rb" caption="app/controllers/api/v1/accounts/lookup_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/notes_controller.rb" caption="app/controllers/api/v1/accounts/notes_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/pins_controller.rb" caption="app/controllers/api/v1/accounts/pins_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/relationships_controller.rb" caption="app/controllers/api/v1/accounts/relationships_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/search_controller.rb" caption="app/controllers/api/v1/accounts/search_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/accounts/statuses_controller.rb" caption="app/controllers/api/v1/accounts/statuses_controller.rb" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/models/account_statuses_filter.rb" caption="app/models/account_statuses_filter.rb" >}}

{{< translation-status-zh-cn raw_title="accounts API methods" raw_link="/methods/accounts/" last_translation_time="2025-04-21" raw_commit="6addd5cf525adec1859f48c52dafcfe1f96e558a">}}

59 KiB Raw Blame History Unescape Escape

注册账户

请求

标头

表单数据参数

响应

200: OK

401: Unauthorized

422: Unprocessable entity

429: Rate limited

验证账户凭据

请求

标头

响应

200: OK

401: Unauthorized

403: Forbidden

422: Unprocessable entity

更新账户凭据

请求

标头

表单数据参数

响应

200: OK

401: Unauthorized

422: Unprocessable entity

获取账户

请求

路径参数

标头

响应

200: OK

本站用户

外站用户

已封禁用户

401: Unauthorized

404: Not found

410: Gone

获取多个账户信息

请求

标头

查询参数

标头

响应

200: OK

401: Unauthorized

获取账户的嘟文

请求

路径参数

标头

查询参数

响应

200: OK

401: Unauthorized

404: Not found

410: Gone

获取账户的关注者

请求

路径参数

标头

查询参数

响应

200: OK

401: Unauthorized

404: Not found

410: Gone

获取账户正在关注的用户

请求

路径参数

标头

查询参数

响应

200: OK

401: Unauthorized

404: Not found

410: Gone

获取账户的精选话题标签

请求

路径参数

标头

59 KiB

Raw Blame History