ボットの投稿ワークフロー
信頼できるボットは、毎回同じループに従います。
- アカウントを一覧取得する：
GET /api/v1/accounts。各アカウントのidをaccountIdsに使います。同じSNSに複数のアカウントがある場合もあり、idで@ハンドルを指定します。 - 必要に応じてメディアをアップロードする：
POST /api/v1/media（multipartのfile、最大100 MB）でmedia.idが返ります。Instagram、TikTok、YouTube、Pinterestでは画像または動画が必要です。詳しくはメディアをご覧ください。 - ドライラン：
dryRun: trueを付けてPOST /api/v1/postsを呼び出します。400があれば修正し、warnings（たとえばSNSの文字数上限を超えたキャプション）を確認します。 dryRunを外した同じ本文にIdempotency-Keyヘッダーを付けて作成します。statusがneeds_approvalのときは人間のユーザーに伝えます。settled: trueになるまで、数秒ごとにGET /api/v1/posts/{id}をポーリングします。予約済みの投稿は、予約日時を過ぎるまでsettledのままです。error.codeに応じてエラーを処理します。詳しくはエラーをご覧ください。
- リンクはキャプションではなく
firstCommentに入れてください。詳しくは最初のコメントをご覧ください。 scheduledForは必ずタイムゾーンのオフセット付きで送ってください。例：2026-10-12T15:00:00-04:00。- 連携済みアカウントがない場合、
409 no_accounts_connectedには人間のユーザー向けのdetails.connectUrlが含まれます。 409 schedule_passedは、人間のユーザーの承認が遅すぎたことを意味します。人間のユーザーが「今すぐ公開」か新しい日時を選びます。
よくある質問
ボットはどのくらいの間隔でポーリングすべきですか？
settledがtrueになるまで数秒ごとにポーリングしてください。予約済みの投稿は予約日時を過ぎるまでsettledのままなので、その日時を過ぎてから再度ポーリングしてください。
エラー時に再試行すべきですか？
error.retryableがtrueの場合にだけ再試行してください。その際は必ず同じIdempotency-Keyを使います。
複数のSNSに同時に投稿できますか？
はい。accountIdsを複数指定してください。SNSごとにターゲットが作られ、それぞれにステータスとURLがあります。
ボットは公開済みの投稿を削除できますか？
いいえ。キャンセルできるのは投稿が送信される前だけです。