buffer-api

Buffer GraphQL API

Buffer の GraphQL API を使用して、ソーシャルメディアの投稿を予約、作成、管理します。

前提条件

• メールアドレスの認証が完了している Buffer アカウント（いずれのプランでも可）
• Buffer API Settings の API キー
• キーを環境変数 BUFFER_API_KEY として保存します

有料アカウントでは最大 5 個の API キーを生成できます。無料アカウントでは 1 個です。現時点では、API を介した TikTok はサポートされていません。

エンドポイント

POST https://api.buffer.com
Content-Type: application/json
Authorization: Bearer $BUFFER_API_KEY

すべてのリクエストは、単一のエンドポイントへの GraphQL POST リクエストです。

認証

すべてのリクエストに Authorization: Bearer ヘッダーが必要です。

curl -X POST 'https://api.buffer.com' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $BUFFER_API_KEY" \
  -d '{"query": "{ account { organizations { id } } }"}'

サポートされている操作

操作	種類	説明
account	クエリ	認証済みユーザーの情報を取得します
channel	クエリ	ID で単一のチャンネルを取得します
channels	クエリ	組織のすべてのチャンネルを取得します
post	クエリ	ID で単一の投稿を取得します
posts	クエリ	フィルター、並べ替え、ページネーションを指定して投稿を取得します
dailyPostingLimits	クエリ	チャンネルごと、日付ごとの投稿上限を確認します
createPost	ミューテーション	投稿を作成して予約します
deletePost	ミューテーション	ID で投稿を削除します
createIdea	ミューテーション	アイデアボードにアイデアを保存します

セットアップの流れ

投稿を作成する前に、組織 ID とチャンネル ID が必要です。次のクエリを順番に実行してください。

1. 組織を取得する

query GetOrganizations {
  account {
    organizations {
      id
    }
  }
}

2. チャンネルを取得する

query GetChannels {
  channels(input: { organizationId: "YOUR_ORG_ID" }) {
    id
    name
    service
    type
  }
}

サービスの種類で絞り込みます。

query GetFilteredChannels {
  channels(
    input: {
      organizationId: "YOUR_ORG_ID"
      filter: { services: [linkedin] }
    }
  ) {
    id
    name
    service
    type
  }
}

サービスの列挙値： facebook、twitter、instagram、linkedin、pinterest、googlebusiness、mastodon、tiktok、bluesky、youtube、threads、startpage

3. 単一のチャンネルを取得する

query GetChannel {
  channel(input: { channelId: "YOUR_CHANNEL_ID" }) {
    id
    name
    service
    type
    metadata {
      ... on LinkedInMetadata { handle }
      ... on TwitterMetadata { handle }
      ... on FacebookMetadata { facebookPageName }
      ... on InstagramMetadata { handle }
    }
  }
}

投稿の作成

テキスト投稿

mutation CreatePost {
  createPost(input: {
    text: "Hello from the Buffer API!",
    channelId: "YOUR_CHANNEL_ID",
    schedulingType: automatic,
    mode: addToQueue
  }) {
    ... on PostActionSuccess {
      post {
        id
        text
        status
      }
    }
    ... on MutationError {
      message
    }
  }
}

画像投稿

テキスト投稿と同じですが、assets.images を使用します。

mutation CreateImagePost {
  createPost(input: {
    text: "Check out this image!",
    channelId: "YOUR_CHANNEL_ID",
    schedulingType: automatic,
    mode: addToQueue,
    assets: {
      images: [
        { url: "https://example.com/image.jpg" }
      ]
    }
  }) {
    ... on PostActionSuccess {
      post {
        id
        text
        assets { id mimeType }
      }
    }
    ... on MutationError {
      message
    }
  }
}

投稿を予約する（指定時刻）

mode: customSchedule と dueAt の ISO 8601 タイムスタンプを使用します。

mutation CreateScheduledPost {
  createPost(input: {
    text: "Posting at a specific time",
    channelId: "YOUR_CHANNEL_ID",
    schedulingType: automatic,
    mode: customSchedule,
    dueAt: "2026-04-01T14:00:00.000Z"
  }) {
    ... on PostActionSuccess {
      post { id text status }
    }
    ... on MutationError { message }
  }
}

今すぐシェアする

mode: shareNow を使用します。

mutation ShareNow {
  createPost(input: {
    text: "Publishing immediately!",
    channelId: "YOUR_CHANNEL_ID",
    schedulingType: automatic,
    mode: shareNow
  }) {
    ... on PostActionSuccess {
      post { id text status }
    }
    ... on MutationError { message }
  }
}

次にシェアする

mode: shareNext を使用すると、投稿をキューの先頭に移動できます。

mutation ShareNext {
  createPost(input: {
    text: "This goes next in the queue",
    channelId: "YOUR_CHANNEL_ID",
    schedulingType: automatic,
    mode: shareNext
  }) {
    ... on PostActionSuccess {
      post { id text status }
    }
    ... on MutationError { message }
  }
}

CreatePostInput のフィールド

フィールド	型	必須	説明
text	String	はい	投稿内容
channelId	ChannelId	はい	対象チャンネル
schedulingType	Enum	はい	automatic または notification
mode	Enum	はい	addToQueue、shareNow、shareNext、customSchedule
dueAt	DateTime	customSchedule の場合	ISO 8601 タイムスタンプ
assets	AssetsInput	いいえ	画像、動画、ドキュメント、リンク

AssetsInput

assets: {
  images: [{ url: "https://..." }]
  videos: [{ url: "https://...", title: "My Video" }]
  documents: [{ url: "https://..." }]
  link: { url: "https://..." }
}

アイデアの作成

コンテンツのアイデアを Buffer のアイデアボードに保存します。

mutation CreateIdea {
  createIdea(input: {
    organizationId: "YOUR_ORG_ID",
    content: {
      title: "Blog post idea"
      text: "Write about the new GraphQL API features"
    }
  }) {
    ... on Idea {
      id
      content { title text }
    }
  }
}

投稿の取得

予約済みの投稿を取得する

query GetScheduledPosts {
  posts(
    input: {
      organizationId: "YOUR_ORG_ID",
      filter: { status: [scheduled] },
      sort: [{ field: dueAt, direction: asc }]
    }
  ) {
    totalCount
    edges {
      node {
        id
        text
        status
        createdAt
        dueAt
        channelId
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

チャンネルの送信済み投稿を取得する

query GetSentPosts {
  posts(
    input: {
      organizationId: "YOUR_ORG_ID",
      filter: {
        status: [sent],
        channelIds: ["YOUR_CHANNEL_ID"]
      }
    }
  ) {
    edges {
      node {
        id
        text
        createdAt
        channelId
      }
    }
  }
}

アセット付きの投稿を取得する

query GetPostsWithAssets {
  posts(
    input: {
      organizationId: "YOUR_ORG_ID",
      filter: { status: [sent], channelIds: ["YOUR_CHANNEL_ID"] }
    }
  ) {
    edges {
      node {
        id
        text
        assets {
          thumbnail
          mimeType
          source
          ... on ImageAsset {
            image { altText width height }
          }
        }
      }
    }
  }
}

ページネーション付きの投稿

カーソルベースのページネーションには first と after を使用します。

query GetPaginatedPosts {
  posts(
    input: { organizationId: "YOUR_ORG_ID" },
    first: 10,
    after: "CURSOR_FROM_PREVIOUS_PAGE"
  ) {
    edges {
      node { id text status }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

PostStatus の列挙値

draft、scheduled、sent、error、deleted、approval_pending、approval_rejected

PostSortableKey の列挙値

dueAt、createdAt

投稿の削除

mutation DeletePost {
  deletePost(input: { postId: "POST_ID" }) {
    ... on DeletePostSuccess {
      post { id status }
    }
    ... on MutationError { message }
  }
}

curl の例

キューにすばやく投稿する

curl -X POST 'https://api.buffer.com' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $BUFFER_API_KEY" \
  -d "$(jq -n --arg text "Hello from the API" --arg ch "$BUFFER_CHANNEL_ID" '{
    query: "mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { ... on PostActionSuccess { post { id text } } ... on MutationError { message } } }",
    variables: { input: { text: $text, channelId: $ch, schedulingType: "automatic", mode: "addToQueue" } }
  }')"

予約済みの投稿を一覧表示する

curl -X POST 'https://api.buffer.com' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $BUFFER_API_KEY" \
  -d "$(jq -n --arg org "$BUFFER_ORG_ID" '{
    query: "query($input: PostsInput!) { posts(input: $input, first: 20) { edges { node { id text dueAt channelId } } } }",
    variables: { input: { organizationId: $org, filter: { status: ["scheduled"] }, sort: [{ field: "dueAt", direction: "asc" }] } }
  }')"

エージェント型ワークフローとバイブコーディング

• 反復的な予約： 複数のアセットを含む投稿が、複雑な GraphQL ペイロードで最初から正しく予約できるとは限りません。ペイロードを下書きし、下書きとしてテストするかアイデアボードに送信して、スキーマやメディア添付に関するエラーを特定し、フィールドを 1 つずつ修正して、投稿形式が正しくなるまで再テストしてください。
• バイブコーディング： 破壊的な操作やキューの一括変更を行う前に、動作する GraphQL クエリや予約スクリプトをローカルでコミットしてください。

エラー処理

ミューテーションのエラー（回復可能）

型付きユニオンのメンバーとして返されます。ミューテーションには必ず ... on MutationError { message } を含めてください。

... on PostActionSuccess { post { id } }
... on MutationError { message }

固有のエラー型：QueueLimitError、PostAlreadyExistsError、ValidationError、LimitReachedError、InvalidInputError、UnauthorizedError、VoidMutationError

クエリエラー（回復不能）

標準の GraphQL errors 配列で、拡張コードとともに返されます。

コード	意味
NOT_FOUND	リソースが存在しません
FORBIDDEN	権限がありません
UNAUTHORIZED	認証が必要、または無効です
UNEXPECTED	サーバーエラー
RATE_LIMIT_EXCEEDED	リクエストが多すぎます

レート制限

クライアントの種類	上限
サードパーティ製クライアント	100 リクエスト / 15 分
不明／未認証	50 リクエスト / 15 分
アカウント全体（すべてのクライアント）	2,000 リクエスト / 15 分

レスポンスヘッダー：RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset

429 の場合は、エラーレスポンスの retryAfter の値（秒）を使用してください。

クエリ制限

上限	値
クエリの最大複雑度	175,000 ポイント
クエリの最大深度	25 レベル
エイリアスの最大数	30
ディレクティブの最大数	50
トークンの最大数	15,000

対応チャンネル

Facebook、Twitter/X、Instagram、LinkedIn、Pinterest、Google Business、Mastodon、TikTok（API 経由では利用不可）、Bluesky、YouTube、Threads、Start Page

Agentic OS との統合

現在のプロジェクトのルートに .agent/ ディレクトリがある場合、このスキルは Agentic OS の共有メモリモデルに必ず参加する必要があります。

実行の最後に、.agent/state/last-run.json が存在するか確認してください。存在する場合は、必須スキーマに従ってファイルに追記または更新し、実行内容を記録してください。agent_runtime、skill_executed、簡潔な summary、decisions、next_steps を必ず記録してください。

参考資料

• 開発者向けドキュメント
• API リファレンス
• GraphQL エクスプローラー
• API 変更履歴
• API ステータス
• Discord