buffer-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Buffer GraphQL API

Schedule, create, and manage social media posts through Buffer's GraphQL API.

通过Buffer的GraphQL API计划、创建和管理社交媒体帖子。

Prerequisites

前提条件

A Buffer account (any plan) with verified email
An API key from Buffer API Settings
Store the key as
```
BUFFER_API_KEY
```
environment variable

Paid accounts can generate up to 5 API keys. Free accounts get 1. TikTok is not supported via the API at this time.

一个已验证邮箱的Buffer账户（任何套餐）
从Buffer API设置获取的API密钥
将密钥存储为
```
BUFFER_API_KEY
```
环境变量

付费账户最多可生成5个API密钥，免费账户可生成1个。目前API不支持TikTok。

Endpoint

端点

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

All requests are GraphQL POST requests to this single endpoint.

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

所有请求都是发送到此单个端点的GraphQL POST请求。

Authentication

身份验证

Every request needs the

Authorization: Bearer

header:

bash

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

每个请求都需要

Authorization: Bearer

头：

bash

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

Supported Operations

支持的操作

Operation	Type	Description
`account`	Query	Get authenticated user info
`channel`	Query	Fetch single channel by ID
`channels`	Query	Fetch all channels for an org
`post`	Query	Fetch single post by ID
`posts`	Query	Fetch posts with filters, sorting, pagination
`dailyPostingLimits`	Query	Check posting limits per channel per date
`createPost`	Mutation	Create and schedule a post
`deletePost`	Mutation	Delete a post by ID
`createIdea`	Mutation	Save an idea to the ideas board

操作	类型	描述
`account`	查询	获取已认证用户信息
`channel`	查询	通过ID获取单个频道
`channels`	查询	获取组织的所有频道
`post`	查询	通过ID获取单个帖子
`posts`	查询	通过筛选、排序、分页获取帖子
`dailyPostingLimits`	查询	检查每个频道每日的发布限制
`createPost`	变更	创建并计划帖子
`deletePost`	变更	通过ID删除帖子
`createIdea`	变更	将创意保存到创意板

Setup Flow

设置流程

Before creating posts, you need your organization ID and channel IDs. Run these queries in order:

创建帖子前，你需要组织ID和频道ID。按以下顺序运行这些查询：

1. Get Organizations

1. 获取组织

graphql

query GetOrganizations {
  account {
    organizations {
      id
    }
  }
}

graphql

query GetOrganizations {
  account {
    organizations {
      id
    }
  }
}

2. Get Channels

2. 获取频道

graphql

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

Filter by service type:

graphql

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

Service enum values:

facebook

twitter

instagram

linkedin

pinterest

googlebusiness

mastodon

tiktok

bluesky

youtube

threads

startpage

graphql

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

按服务类型筛选：

graphql

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. Get a Single Channel

3. 获取单个频道

graphql

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

graphql

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

Creating Posts

创建帖子

Text Post

文字帖子

graphql

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

graphql

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

Image Post

图片帖子

Same as text post, with

assets.images

graphql

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

与文字帖子类似，添加

assets.images

：

graphql

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

Scheduled Post (Specific Time)

定时帖子（特定时间）

Use

mode: customSchedule

with a

dueAt

ISO 8601 timestamp:

graphql

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: customSchedule

并传入

dueAt

ISO 8601时间戳：

graphql

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

Share Now

立即发布

Use

mode: shareNow

graphql

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: shareNow

：

graphql

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

Share Next

下一个发布

Use

mode: shareNext

to push the post to the front of the queue:

graphql

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

使用

mode: shareNext

将帖子推到队列前端：

graphql

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 Fields

CreatePostInput字段

Field	Type	Required	Description
`text`	String	Yes	Post content
`channelId`	ChannelId	Yes	Target channel
`schedulingType`	Enum	Yes	`automatic` or `notification`
`mode`	Enum	Yes	`addToQueue` , `shareNow` , `shareNext` , `customSchedule`
`dueAt`	DateTime	For customSchedule	ISO 8601 timestamp
`assets`	AssetsInput	No	Images, videos, documents, links

字段	类型	必填	描述
`text`	String	是	帖子内容
`channelId`	ChannelId	是	目标频道
`schedulingType`	Enum	是	`automatic` 或 `notification`
`mode`	Enum	是	`addToQueue` , `shareNow` , `shareNext` , `customSchedule`
`dueAt`	DateTime	自定义计划时必填	ISO 8601时间戳
`assets`	AssetsInput	否	图片、视频、文档、链接

AssetsInput

graphql

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

graphql

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

Creating Ideas

创建创意

Save content ideas to the Buffer ideas board:

graphql

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

将内容创意保存到Buffer创意板：

graphql

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

Retrieving Posts

检索帖子

Get Scheduled Posts

获取已计划帖子

graphql

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

graphql

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

Get Sent Posts for a Channel

获取频道已发布帖子

graphql

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

graphql

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

Get Posts with Assets

获取带资源的帖子

graphql

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

graphql

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

Paginated Posts

分页帖子

Use

first

and

after

for cursor-based pagination:

graphql

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

使用

first

和

after

实现基于游标分页：

graphql

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 Enum Values

PostStatus枚举值

draft

scheduled

sent

error

deleted

approval_pending

approval_rejected

draft

scheduled

sent

error

deleted

approval_pending

approval_rejected

PostSortableKey Enum Values

PostSortableKey枚举值

dueAt

createdAt

dueAt

createdAt

Deleting Posts

删除帖子

graphql

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

graphql

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

curl Recipes

curl示例

Quick post to queue

快速添加帖子到队列

bash

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

bash

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

List scheduled posts

列出已计划帖子

bash

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

bash

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

Agentic Workflow & Vibe Coding

智能工作流与氛围编码

Iterative Scheduling: Do not expect complex GraphQL payloads to perfectly schedule multi-asset posts on the first try. Draft the payload, test it as a draft or send it to the ideas board, isolate any specific schema or media attachment errors, refine ONE field at a time, and re-test until the post format is correct.
Vibe Coding: Commit your working GraphQL queries or scheduling scripts locally before attempting destructive operations or bulk queue modifications.

迭代调度： 不要期望复杂的GraphQL负载能一次完美调度多资源帖子。先草拟负载，作为草稿测试或发送到创意板，隔离任何特定的模式或媒体附件错误，每次只优化一个字段，重新测试直到帖子格式正确。
氛围编码： 在尝试破坏性操作或批量队列修改前，先在本地提交有效的GraphQL查询或调度脚本。

Error Handling

错误处理

Mutation Errors (Recoverable)

变更错误（可恢复）

Returned as typed union members. Always include

... on MutationError { message }

in mutations:

graphql

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

Specific error types:

QueueLimitError

PostAlreadyExistsError

ValidationError

LimitReachedError

InvalidInputError

UnauthorizedError

VoidMutationError

作为类型联合成员返回。在变更中始终包含

... on MutationError { message }

：

graphql

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

特定错误类型：

QueueLimitError

PostAlreadyExistsError

ValidationError

LimitReachedError

InvalidInputError

UnauthorizedError

VoidMutationError

Query Errors (Non-recoverable)

查询错误（不可恢复）

Returned in the standard GraphQL

errors

array with extension codes:

Code	Meaning
`NOT_FOUND`	Resource does not exist
`FORBIDDEN`	No permission
`UNAUTHORIZED`	Auth required or invalid
`UNEXPECTED`	Server error
`RATE_LIMIT_EXCEEDED`	Too many requests

在标准GraphQL

errors

数组中返回，包含扩展代码：

代码	含义
`NOT_FOUND`	资源不存在
`FORBIDDEN`	无权限
`UNAUTHORIZED`	需要身份验证或验证无效
`UNEXPECTED`	服务器错误
`RATE_LIMIT_EXCEEDED`	请求过多

Rate Limits

速率限制

Client Type	Limit
Third-party clients	100 requests / 15 min
Unknown/unauthenticated	50 requests / 15 min
Account overall (all clients)	2,000 requests / 15 min

Response headers:

RateLimit-Limit

RateLimit-Remaining

RateLimit-Reset

On 429, use the

retryAfter

value (seconds) from the error response.

客户端类型	限制
第三方客户端	100次请求/15分钟
未知/未认证客户端	50次请求/15分钟
账户总体（所有客户端）	2000次请求/15分钟

响应头：

RateLimit-Limit

RateLimit-Remaining

RateLimit-Reset

收到429错误时，使用错误响应中的

retryAfter

值（秒数）进行重试。

Query Limits

查询限制

Limit	Value
Max query complexity	175,000 points
Max query depth	25 levels
Max aliases	30
Max directives	50
Max tokens	15,000

限制	数值
最大查询复杂度	175,000点
最大查询深度	25层
最大别名数量	30
最大指令数量	50
最大令牌数量	15,000

Supported Channels

支持的频道

Facebook, Twitter/X, Instagram, LinkedIn, Pinterest, Google Business, Mastodon, TikTok (not via API), Bluesky, YouTube, Threads, Start Page

Facebook、Twitter/X、Instagram、LinkedIn、Pinterest、Google Business、Mastodon、TikTok（API不支持）、Bluesky、YouTube、Threads、Start Page

Agentic OS Integration

智能操作系统集成

If the current project root contains an

.agent/

directory, this skill MUST participate in the Agentic OS shared-memory model.

At the end of your execution, check for

.agent/state/last-run.json

. If it exists, append or update the file using its required schema to log your run. Ensure you capture your runtime (

agent_runtime

skill_executed

, a concise

summary

decisions

, and

next_steps

如果当前项目根目录包含

.agent/

目录，此技能必须参与智能操作系统共享内存模型。

执行结束时，检查

.agent/state/last-run.json

是否存在。如果存在，使用其要求的模式追加或更新文件以记录运行情况。确保捕获运行时(

agent_runtime

)、

skill_executed

、简洁的

summary

、

decisions

和

next_steps

。

buffer-api

Original

Translation

Buffer GraphQL API

Buffer GraphQL API

Prerequisites

前提条件

Endpoint

端点

Authentication

身份验证

Supported Operations

支持的操作

Setup Flow

设置流程

1. Get Organizations

1. 获取组织

2. Get Channels

2. 获取频道

3. Get a Single Channel

3. 获取单个频道

Creating Posts

创建帖子

Text Post

文字帖子

Image Post

图片帖子

Scheduled Post (Specific Time)

定时帖子（特定时间）

Share Now

立即发布

Share Next

下一个发布

CreatePostInput Fields

CreatePostInput字段

AssetsInput

AssetsInput

Creating Ideas

创建创意

Retrieving Posts

检索帖子

Get Scheduled Posts

获取已计划帖子

Get Sent Posts for a Channel

获取频道已发布帖子

Get Posts with Assets

获取带资源的帖子

Paginated Posts

分页帖子

PostStatus Enum Values

PostStatus枚举值

PostSortableKey Enum Values

PostSortableKey枚举值

Deleting Posts

删除帖子

curl Recipes

curl示例

Quick post to queue

快速添加帖子到队列

List scheduled posts

列出已计划帖子

Agentic Workflow & Vibe Coding

智能工作流与氛围编码

Error Handling

错误处理

Mutation Errors (Recoverable)

变更错误（可恢复）

Query Errors (Non-recoverable)

查询错误（不可恢复）

Rate Limits

速率限制

Query Limits

查询限制

Supported Channels

支持的频道

Agentic OS Integration

智能操作系统集成

Reference

参考资料