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，并提供 ISO 8601 时间戳 dueAt：

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" }] } }
  }')"

Agent 工作流与氛围编程

• 迭代安排： 不要指望复杂的 GraphQL 负载第一次就能完美安排包含多个资源的帖子。先起草负载，将其作为草稿进行测试或发送到创意板；找出具体的架构或媒体附件错误；每次只优化一个字段，然后重新测试，直到帖子格式正确。
• 氛围编程： 在尝试破坏性操作或批量修改队列之前，先在本地提交可用的 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