mastodon

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Call the Mastodon REST API with

curl + jq

. Two connector credentials are injected:

$MASTODON_BASE_URL

(the instance, e.g.

https://mastodon.social

) and

$MASTODON_ACCESS_TOKEN

. Every request sends the header

Authorization: Bearer $MASTODON_ACCESS_TOKEN

Errors come back as JSON

{"error":"<message>"}

— show it verbatim.

(

"The access token is invalid"

) means the token is wrong/revoked → the user must re-connect the Mastodon connector. Posting needs the token to have the

write

(or

write:statuses

) scope.

Always confirm the token + account first (also gives the account

id

you need to list your own toots):

bash

curl -sS "$MASTODON_BASE_URL/api/v1/accounts/verify_credentials" \
  -H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" \
  | jq '{id, username, acct, display_name, followers: .followers_count, statuses: .statuses_count}'

使用

curl + jq

调用Mastodon REST API。会注入两个连接器凭据：

$MASTODON_BASE_URL

（实例地址，例如

https://mastodon.social

）和

$MASTODON_ACCESS_TOKEN

。每个请求都会发送请求头

Authorization: Bearer $MASTODON_ACCESS_TOKEN

。

错误信息会以JSON格式

{"error":"<message>"}

返回——请直接展示该信息。

错误（

"The access token is invalid"

）表示令牌错误/已撤销→用户必须重新连接Mastodon连接器。发布内容需要令牌拥有

write

（或

write:statuses

）权限范围。

请先确认令牌和账户信息（这同时会返回你列出自己toot所需的账户

id

）：

bash

curl -sS "$MASTODON_BASE_URL/api/v1/accounts/verify_credentials" \
  -H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" \
  | jq '{id, username, acct, display_name, followers: .followers_count, statuses: .statuses_count}'

Post a toot

发布toot

Confirm with the user before posting publicly. Default

visibility

unlisted

unless they say post publicly; use

public

only on request.

bash

STATUS_TEXT="Hello fediverse 👋 #introductions"
curl -sS -X POST "$MASTODON_BASE_URL/api/v1/statuses" \
  -H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-urlencode "status=$STATUS_TEXT" \
  --data-urlencode "visibility=unlisted" \
  --data-urlencode "language=en" \
  | jq '{id, url, visibility, created_at}'

```
visibility
```
is one of
```
public
```
,
```
unlisted
```
,
```
private
```
,
```
direct
```
.
Optional params:
```
spoiler_text
```
(content warning),
```
in_reply_to_id
```
(reply),
```
sensitive=true
```
,
```
language
```
(ISO 639-1).
```
Idempotency-Key
```
(any unique string;
```
uuidgen
```
here) prevents duplicate posts if the request is retried within ~1h. Use
```
--data-urlencode
```
so hashtags, emoji and newlines in the text are encoded correctly.
Default post length is 500 chars (instance-configurable); longer text →
```
422 {"error":"Validation failed: Text ..."}
```
.

公开发布前请与用户确认。默认

visibility

为

unlisted

（未列出），除非用户明确要求公开发布；仅在用户请求时使用

public

（公开）。

bash

STATUS_TEXT="Hello fediverse 👋 #introductions"
curl -sS -X POST "$MASTODON_BASE_URL/api/v1/statuses" \
  -H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-urlencode "status=$STATUS_TEXT" \
  --data-urlencode "visibility=unlisted" \
  --data-urlencode "language=en" \
  | jq '{id, url, visibility, created_at}'

```
visibility
```
可选值为
```
public
```
、
```
unlisted
```
、
```
private
```
、
```
direct
```
。
可选参数：
```
spoiler_text
```
（内容警告）、
```
in_reply_to_id
```
（回复目标ID）、
```
sensitive=true
```
（标记为敏感内容）、
```
language
```
（ISO 639-1格式语言代码）。
```
Idempotency-Key
```
（任意唯一字符串；此处使用
```
uuidgen
```
生成）可防止请求在约1小时内重试时重复发布。使用
```
--data-urlencode
```
确保文本中的话题标签、表情符号和换行符被正确编码。
默认帖子长度为500字符（可由实例配置）；文本过长会返回
```
422 {"error":"Validation failed: Text ..."}
```
错误。

List my recent toots + engagement

列出我最近的toot及互动数据

Use the

id

from

verify_credentials

bash

ACCT_ID="14715"   # from verify_credentials
curl -sS "$MASTODON_BASE_URL/api/v1/accounts/$ACCT_ID/statuses?limit=20&exclude_replies=true&exclude_reblogs=true" \
  -H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" \
  | jq '.[] | {id, url, boosts: .reblogs_count, favs: .favourites_count, replies: .replies_count, created_at}'

limit

max 40. Other filters:

only_media

pinned

tagged=<hashtag>

使用

verify_credentials

返回的

id

：

bash

ACCT_ID="14715"   # 来自verify_credentials的结果
curl -sS "$MASTODON_BASE_URL/api/v1/accounts/$ACCT_ID/statuses?limit=20&exclude_replies=true&exclude_reblogs=true" \
  -H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" \
  | jq '.[] | {id, url, boosts: .reblogs_count, favs: .favourites_count, replies: .replies_count, created_at}'

limit

最大值为40。其他筛选参数：

only_media

（仅含媒体内容）、

pinned

（置顶帖子）、

tagged=<hashtag>

（含指定话题标签）。

Delete a toot

删除toot

bash

curl -sS -X DELETE "$MASTODON_BASE_URL/api/v1/statuses/STATUS_ID" \
  -H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" | jq '{id, deleted: true}'

Deleting returns the status with its source

text

so you can delete-and-redraft.

404 {"error":"Record not found"}

= not yours or already gone.

bash

curl -sS -X DELETE "$MASTODON_BASE_URL/api/v1/statuses/STATUS_ID" \
  -H "Authorization: Bearer $MASTODON_ACCESS_TOKEN" | jq '{id, deleted: true}'

删除操作会返回包含原始

text

的状态信息，方便你删除后重新编辑发布。

404 {"error":"Record not found"}

错误表示该toot不属于你或已被删除。

Attaching media (optional)

附加媒体（可选）

Upload each image/video via

POST $MASTODON_BASE_URL/api/v2/media

(

multipart/form-data

, field

file

) to get a media id, then pass the ids as

media_ids[]

when posting the status. See the docs for the full media contract: https://docs.joinmastodon.org/methods/media/

通过

POST $MASTODON_BASE_URL/api/v2/media

接口上传每张图片/视频（使用

multipart/form-data

格式，字段名为

file

）以获取媒体ID，然后在发布状态时将ID作为

media_ids[]

参数传入。完整的媒体接口说明请查看文档：https://docs.joinmastodon.org/methods/media/

Gotchas

注意事项

Federated: the API only ever targets
```
$MASTODON_BASE_URL
```
(the user's own instance). There is no global endpoint — a token from instance A won't work on instance B.

Scopes: reading needs

read

(or

read:accounts

read:statuses

); posting/deleting needs

write

(or

write:statuses

). A

(

"This action is outside the authorized scopes"

) means the token lacks a scope.

Rate limits: Mastodon rate-limits per token; space out bulk posts or you'll get
```
429
```
.
```
verify_credentials
```
returns HTML in fields like
```
note
```
; the plaintext source lives under the
```
source
```
object.

联邦特性：API仅针对
```
$MASTODON_BASE_URL
```
（用户自己的实例）。不存在全局端点——实例A的令牌无法在实例B上使用。
权限范围：读取操作需要
```
read
```
（或
```
read:accounts
```
/
```
read:statuses
```
）权限；发布/删除操作需要
```
write
```
（或
```
write:statuses
```
）权限。
```
403
```
错误（
```
"This action is outside the authorized scopes"
```
）表示令牌缺少对应权限。
速率限制：Mastodon针对每个令牌设置了速率限制；批量发布时请间隔发送请求，否则会收到
```
429
```
错误。
```
verify_credentials
```
返回的
```
note
```
等字段包含HTML内容；纯文本源数据位于
```
source
```
对象下。

Record the output

记录输出结果

After you successfully publish and obtain the live result URL, call the built-in

publish_artifact

tool ONCE so the user can track this deliverable in My Outputs:

publish_artifact(kind="message", channel="mastodon", title="<title>", url="<the REAL returned URL>", status="delivered")

Use the real returned URL — never fabricate one. Call it once per published item, only after delivery is confirmed; skip it (or use

status="failed"

) if publishing failed. See

_shared/artifacts.md

成功发布并获取到实际结果URL后，调用内置的

publish_artifact

工具一次，以便用户在我的输出中跟踪该交付成果：

publish_artifact(kind="message", channel="mastodon", title="<title>", url="<the REAL returned URL>", status="delivered")

请使用实际返回的URL——切勿伪造。每个发布项仅调用一次，且仅在确认交付成功后调用；若发布失败，请跳过调用（或使用

status="failed"

）。详情请查看

_shared/artifacts.md

。