mastodon

curl + jq を使って Mastodon REST API を呼び出します。コネクターの認証情報が 2 つ注入されます。$MASTODON_BASE_URL（インスタンス。例：https://mastodon.social）と $MASTODON_ACCESS_TOKEN です。すべてのリクエストで、ヘッダー Authorization: Bearer $MASTODON_ACCESS_TOKEN を送信します。

エラーは JSON {"error":"<message>"} として返されます。内容をそのまま表示してください。401（"The access token is invalid"）は、トークンが間違っているか失効していることを意味します → ユーザーは Mastodon コネクターを再接続する必要があります。投稿には、トークンに write（または write:statuses）スコープが必要です。

まず必ずトークンとアカウントを確認してください（自分のトゥートを一覧表示するために必要なアカウントの id も取得できます）。

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}'

トゥートを投稿する

公開投稿の前に、ユーザーに確認してください。 公開投稿を希望しているとの指定がない限り、visibility は unlisted に設定してください。public を使うのは、ユーザーから希望があった場合のみです。

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（返信）、sensitive=true、language（ISO 639-1）。
• Idempotency-Key（任意の一意な文字列。ここでは uuidgen）を使うと、約 1 時間以内にリクエストが再試行された場合に重複投稿を防げます。テキスト内のハッシュタグ、絵文字、改行が正しくエンコードされるように、--data-urlencode を使ってください。
• 投稿のデフォルトの文字数上限は 500 文字（インスタンスで設定可能）です。これを超えるテキストを投稿すると、422 {"error":"Validation failed: Text ..."} が返されます。

最近の自分のトゥートとエンゲージメントを一覧表示する

verify_credentials の id を使います。

ACCT_ID="ACCOUNT_ID"   # 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 の最大値は 40 です。その他のフィルター：only_media、pinned、tagged=<hashtag>。

トゥートを削除する

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"} は、自分の投稿ではないか、すでに削除されていることを意味します。

メディアを添付する（任意）

各画像／動画を POST $MASTODON_BASE_URL/api/v2/media（multipart/form-data、フィールド file）でアップロードしてメディア ID を取得し、その ID をステータスの投稿時に media_ids[] として渡します。メディアの仕様全体については、ドキュメントを参照してください： https://docs.joinmastodon.org/methods/media/

注意事項

• 連合型： 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 オブジェクトにあります。

出力を記録する

公開に成功し、実際の結果 URL を取得したら、組み込みの publish_artifact ツールを 1 回呼び出し、ユーザーがこの成果物を My Outputs で追跡できるようにしてください。

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

実際に返された URL を使ってください。URL を捏造してはいけません。公開された項目ごとに、配信が確認できた後に 1 回だけ呼び出してください。公開に失敗した場合は呼び出さないか、status="failed" を使ってください。_shared/artifacts.md を参照してください。