buffer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Buffer Social Media Scheduling

Buffer社交媒体调度

Setup

配置

Requires a

BUFFER_API_TOKEN

environment variable. Generate one at: https://publish.buffer.com/settings/api

Verify the token is set before making any API calls:

bash

if [ -z "$BUFFER_API_TOKEN" ]; then
  echo "Error: BUFFER_API_TOKEN is not set. Get your token at https://publish.buffer.com/settings/api"
  exit 1
fi

需要设置

BUFFER_API_TOKEN

环境变量。可在以下地址生成： https://publish.buffer.com/settings/api

在发起任何API调用前，请验证该令牌已设置：

bash

if [ -z "$BUFFER_API_TOKEN" ]; then
  echo "Error: BUFFER_API_TOKEN is not set. Get your token at https://publish.buffer.com/settings/api"
  exit 1
fi

API Configuration

API配置

Endpoint:
```
https://api.buffer.com
```
Method: POST (all requests are GraphQL)
Content-Type:
```
application/json
```
Auth:
```
Authorization: Bearer $BUFFER_API_TOKEN
```
User-Agent:
```
Mozilla/5.0
```
— required to avoid Cloudflare 403 blocks

端点:
```
https://api.buffer.com
```
请求方法: POST（所有请求均为GraphQL）
内容类型:
```
application/json
```
认证:
```
Authorization: Bearer $BUFFER_API_TOKEN
```
用户代理:
```
Mozilla/5.0
```
— 必须添加以避免Cloudflare 403拦截

Curl Template

Curl模板

All API calls follow this pattern:

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "<GRAPHQL_QUERY>", "variables": <VARIABLES_JSON>}'

Always pipe through

jq

for readable output. Use

jq -e

to detect errors.

Important: For queries with GraphQL variables (e.g.

$input

), the shell may expand

$input

even inside single quotes. Use a temp file with

-d @file

to avoid this:

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "<GRAPHQL_QUERY>", "variables": <VARIABLES_JSON>}
EOF

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

Simple queries without variables can use inline

-d

directly.

所有API调用遵循以下格式：

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "<GRAPHQL_QUERY>", "variables": <VARIABLES_JSON>}'

建议始终通过

jq

处理输出以提升可读性。使用

jq -e

来检测错误。

重要提示: 对于包含GraphQL变量（如

$input

）的查询，即使在单引号内，shell也可能会展开

$input

。建议使用临时文件并通过

-d @file

参数来避免此问题：

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "<GRAPHQL_QUERY>", "variables": <VARIABLES_JSON>}
EOF

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

无变量的简单查询可直接使用内联

-d

参数。

Mode Detection

模式检测

Parse the user's intent to determine which operation to perform:

Intent	Mode	Example
List organizations	`organizations`	"Show my Buffer organizations"
List channels	`channels`	"What channels do I have?"
View posts	`posts`	"Show my scheduled posts"
Create a text post	`create-post`	"Schedule a tweet saying..."
Create a Twitter/X thread	`create-thread`	"Post a thread on X..."
Create an image post	`create-post`	"Post this image to Instagram"
Save an idea	`create-idea`	"Save an idea about..."
Account info	`account`	"Show my Buffer account"

Most operations require an

organizationId

. If the user hasn't specified one, fetch organizations first. If only one org exists, use it automatically.

解析用户意图以确定要执行的操作：

意图	模式	示例
列出组织	`organizations`	"显示我的Buffer组织"
列出频道	`channels`	"我有哪些频道？"
查看帖子	`posts`	"显示我已调度的帖子"
创建文字帖子	`create-post`	"调度一条推文，内容为..."
创建Twitter/X线程帖	`create-thread`	"在X平台发布一条线程帖..."
创建图片帖子	`create-post`	"将这张图片发布到Instagram"
保存创意	`create-idea`	"保存一个关于...的创意"
账户信息	`account`	"显示我的Buffer账户"

大多数操作需要

organizationId

。如果用户未指定，需先获取组织列表。若仅存在一个组织，则自动使用该组织。

Mode: Get Organizations

模式：获取组织

Fetch the user's organizations. This is typically the first call needed.

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ account { organizations { id name ownerEmail } } }"}' | jq .

Store the

organizationId

from the response for subsequent calls.

获取用户的组织列表。这通常是首次调用所需的操作。

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ account { organizations { id name ownerEmail } } }"}' | jq .

将响应中的

organizationId

存储起来，用于后续调用。

Mode: Get Channels

模式：获取频道

List channels (social media accounts) for an organization.

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "query GetChannels($input: ChannelsInput!) { channels(input: $input) { id name displayName service avatar isQueuePaused } }", "variables": {"input": {"organizationId": "<ORG_ID>"}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

Display results in a readable format showing channel name, service (e.g., twitter, instagram, linkedin), and queue status.

列出某一组织下的频道（社交媒体账户）。

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "query GetChannels($input: ChannelsInput!) { channels(input: $input) { id name displayName service avatar isQueuePaused } }", "variables": {"input": {"organizationId": "<ORG_ID>"}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

以可读格式展示结果，包括频道名称、服务类型（如twitter、instagram、linkedin）以及队列状态。

Mode: Get Posts

模式：获取帖子

Query posts with filtering, sorting, and pagination.

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "query GetPosts($input: PostsInput!) { posts(input: $input) { edges { node { id text status dueAt sentAt createdAt channelService externalLink } cursor } pageInfo { hasNextPage endCursor } totalCount } }", "variables": {"input": {"organizationId": "<ORG_ID>", "filter": {"status": "scheduled"}, "sort": {"field": "dueAt", "direction": "desc"}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

For available filter fields (status, channelIds, date range), sort options, and pagination details, refer to

references/api-reference.md

通过过滤、排序和分页查询帖子。

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "query GetPosts($input: PostsInput!) { posts(input: $input) { edges { node { id text status dueAt sentAt createdAt channelService externalLink } cursor } pageInfo { hasNextPage endCursor } totalCount } }", "variables": {"input": {"organizationId": "<ORG_ID>", "filter": {"status": "scheduled"}, "sort": {"field": "dueAt", "direction": "desc"}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

关于可用的过滤字段（状态、频道ID、日期范围）、排序选项和分页详情，请参考

references/api-reference.md

。

Mode: Create Text Post

模式：创建文字帖子

Create and schedule a text post.

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { ... on PostActionSuccess { post { id text status dueAt } } ... on MutationError { message } } }", "variables": {"input": {"channelId": "<CHANNEL_ID>", "text": "<POST_CONTENT>", "schedulingType": "automatic", "mode": "addToQueue"}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

创建并调度文字帖子。

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { ... on PostActionSuccess { post { id text status dueAt } } ... on MutationError { message } } }", "variables": {"input": {"channelId": "<CHANNEL_ID>", "text": "<POST_CONTENT>", "schedulingType": "automatic", "mode": "addToQueue"}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

Required Fields

必填字段

channelId (String!): The channel to post to
text (String!): The post content

channelId (String!): 帖子发布的目标频道
text (String!): 帖子内容

Scheduling Options

调度选项

schedulingType:
```
automatic
```
(Buffer picks time) or
```
notification
```
(sends reminder)

mode: Controls when the post is published (e.g.,

addToQueue

shareNow

shareNext

customSchedule

recommendedTime

)

dueAt (String): ISO 8601 datetime, required when mode is
```
customSchedule
```
. Example:
```
"2026-03-15T14:00:00Z"
```

For full field definitions and enum values, refer to

references/api-reference.md

schedulingType:
```
automatic
```
（由Buffer选择发布时间）或
```
notification
```
（发送提醒）

mode: 控制帖子发布时机（如

addToQueue

、

shareNow

、

shareNext

、

customSchedule

、

recommendedTime

）

dueAt (String): ISO 8601格式的日期时间，当mode为
```
customSchedule
```
时必填。示例：
```
"2026-03-15T14:00:00Z"
```

完整字段定义和枚举值请参考

references/api-reference.md

。

Response Handling

响应处理

The mutation returns a union type. Always check for both success and error:

bash

undefined

该突变返回联合类型。需同时检查成功和错误情况：

bash

undefined

Check if the response contains an error

检查响应是否包含错误

result=$(curl -s -X POST https://api.buffer.com -H "User-Agent: Mozilla/5.0" ...) echo "$result" | jq -e '.data.createPost.message' > /dev/null 2>&1 && { echo "Error: $(echo "$result" | jq -r '.data.createPost.message')" } || { echo "$result" | jq '.data.createPost.post' }

undefined

undefined

Mode: Create Twitter/X Thread

模式：创建Twitter/X线程帖

Twitter/X threads are created using the

metadata.twitter.thread

field on the

createPost

mutation. The thread is an array of

ThreadedPostInput

objects, each with a

text

field (and optional

assets

Important: The first tweet in the thread must be included in the

thread

array. The top-level

text

field is also required but Buffer uses the thread array to render all tweets in its UI. Include the same text in both places for the first tweet.

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { ... on PostActionSuccess { post { id text status dueAt } } ... on MutationError { message } } }", "variables": {"input": {"channelId": "<CHANNEL_ID>", "text": "<FIRST_TWEET_TEXT>", "schedulingType": "automatic", "mode": "addToQueue", "metadata": {"twitter": {"thread": [{"text": "<FIRST_TWEET_TEXT>"}, {"text": "<SECOND_TWEET_TEXT>"}, {"text": "<THIRD_TWEET_TEXT>"}]}}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

Twitter/X线程帖需通过

createPost

突变中的

metadata.twitter.thread

字段创建。线程帖是

ThreadedPostInput

对象的数组，每个对象包含

text

字段（可选包含

assets

）。

重要提示: 线程帖中的第一条推文必须包含在

thread

数组中。顶层

text

字段同样必填，但Buffer会使用线程数组在界面中渲染所有推文。建议第一条推文的内容在两处保持一致。

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { ... on PostActionSuccess { post { id text status dueAt } } ... on MutationError { message } } }", "variables": {"input": {"channelId": "<CHANNEL_ID>", "text": "<FIRST_TWEET_TEXT>", "schedulingType": "automatic", "mode": "addToQueue", "metadata": {"twitter": {"thread": [{"text": "<FIRST_TWEET_TEXT>"}, {"text": "<SECOND_TWEET_TEXT>"}, {"text": "<THIRD_TWEET_TEXT>"}]}}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

Thread Structure

线程帖结构

Top-level
text
: Required. Use the first tweet's text.
metadata.twitter.thread
: Array of
```
ThreadedPostInput
```
objects. Each has:
- text
  (String): The tweet content
- assets
  (AssetsInput, optional): Images for that specific tweet
The first entry in the
```
thread
```
array should match the top-level
```
text
```
(this is what Buffer displays as tweet 1).
All subsequent entries become reply tweets in the thread.

顶层
text
: 必填。使用第一条推文的内容。
metadata.twitter.thread
:
```
ThreadedPostInput
```
对象数组。每个对象包含：
- text
  (String): 推文内容
- assets
  (AssetsInput, 可选): 该条推文附带的图片
```
thread
```
数组的第一个条目应与顶层
```
text
```
内容一致（Buffer会将其显示为第一条推文）。
后续所有条目将成为线程帖中的回复推文。

Thread Tips

线程帖提示

Each tweet in the thread must respect Twitter's character limit (280 characters).
Threads are scheduled as a single unit and posted all at once.
Images can be attached to individual tweets via the
```
assets
```
field on each
```
ThreadedPostInput
```
.

线程帖中的每条推文必须遵守Twitter的字符限制（280字符）。
线程帖作为一个整体进行调度，将一次性全部发布。
可通过每个
```
ThreadedPostInput
```
的
```
assets
```
字段为单条推文添加图片。

Mode: Create Image Post

模式：创建图片帖子

Same as text post, but include an

assets

field with image URLs.

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { ... on PostActionSuccess { post { id text status dueAt } } ... on MutationError { message } } }", "variables": {"input": {"channelId": "<CHANNEL_ID>", "text": "<POST_CONTENT>", "schedulingType": "automatic", "mode": "addToQueue", "assets": {"images": [{"url": "<IMAGE_URL>"}]}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

Images must be publicly accessible URLs. Multiple images can be included in the

images

array.

与文字帖子创建流程一致，但需添加包含图片URL的

assets

字段。

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { ... on PostActionSuccess { post { id text status dueAt } } ... on MutationError { message } } }", "variables": {"input": {"channelId": "<CHANNEL_ID>", "text": "<POST_CONTENT>", "schedulingType": "automatic", "mode": "addToQueue", "assets": {"images": [{"url": "<IMAGE_URL>"}]}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

图片必须是可公开访问的URL。

images

数组中可包含多张图片。

Mode: Create Idea

模式：创建创意

Save an idea for later use.

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreateIdea($input: CreateIdeaInput!) { createIdea(input: $input) { ... on Idea { id content { title text services } } } }", "variables": {"input": {"organizationId": "<ORG_ID>", "content": {"title": "<IDEA_TITLE>", "text": "<IDEA_BODY>", "services": ["twitter", "linkedin"]}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

For

IdeaContentInput

field details (title, text, services, tags), refer to

references/api-reference.md

Note: Tags require existing tag objects with

id

and

color

fields — fetch existing tags first before using.

保存创意以供后续使用。

bash

cat > /tmp/buffer_payload.json << 'EOF'
{"query": "mutation CreateIdea($input: CreateIdeaInput!) { createIdea(input: $input) { ... on Idea { id content { title text services } } } }", "variables": {"input": {"organizationId": "<ORG_ID>", "content": {"title": "<IDEA_TITLE>", "text": "<IDEA_BODY>", "services": ["twitter", "linkedin"]}}}}
EOF
curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d @/tmp/buffer_payload.json | jq .

关于

IdeaContentInput

字段详情（标题、内容文本、服务类型、标签），请参考

references/api-reference.md

。

注意: 标签需要包含

id

和

color

字段的现有标签对象——使用前需先获取现有标签。

Mode: Get Account

模式：获取账户

Note: The full account query (
id
,
name
,
email
,
timezone
) fails with a standard API token scope. Use Get Organizations instead to confirm account identity.

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ account { organizations { id name ownerEmail } } }"}' | jq .

注意: 完整的账户查询（
id
、
name
、
email
、
timezone
）会因标准API令牌权限不足而失败。建议使用“获取组织”操作来确认账户身份。

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ account { organizations { id name ownerEmail } } }"}' | jq .

Common Workflows

常见工作流

Schedule a Post

调度帖子

Multi-step workflow when the user wants to schedule a post:

Get organizations → extract
```
organizationId
```
Get channels → show available channels, let user pick (or match by service name)
Create post → use selected
```
channelId
```
with the post content

If the user specifies a service (e.g., "post to Twitter"), match it against the channel's

service

field.

当用户需要调度帖子时的多步骤工作流：

获取组织 → 提取
```
organizationId
```
获取频道 → 展示可用频道，让用户选择（或按服务名称匹配）
创建帖子 → 使用选中的
```
channelId
```
和帖子内容

如果用户指定了服务类型（如“发布到Twitter”），则将其与频道的

service

字段进行匹配。

Check the Queue

查看队列

Get organizations → extract
```
organizationId
```

Get posts with

filter: { status: "scheduled" }

and

sort: { field: "dueAt", direction: "asc" }

Display posts grouped by date with channel info

获取组织 → 提取
```
organizationId
```

获取帖子，设置

filter: { status: "scheduled" }

和

sort: { field: "dueAt", direction: "asc" }

按日期分组展示帖子，并附带频道信息

Brainstorm and Save Ideas

头脑风暴并保存创意

Get organizations → extract
```
organizationId
```
Help the user draft idea content
Create idea with title, text, tags, and target services

获取组织 → 提取
```
organizationId
```
协助用户草拟创意内容
创建创意，包含标题、内容文本、标签和目标服务类型

Schema Introspection

架构自省

Before attempting a mutation or querying a field you're unsure about, introspect the schema first. Don't guess — the API surface is limited.

List all available mutations:

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ __schema { mutationType { fields { name } } } }"}' | jq '[.data.__schema.mutationType.fields[].name]'

List all available queries:

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ __schema { queryType { fields { name } } } }"}' | jq '[.data.__schema.queryType.fields[].name]'

Inspect fields on a specific type:

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ __type(name: \"<TYPE_NAME>\") { fields { name type { name kind } } } }"}' | jq '.data.__type.fields[]'

在尝试执行突变或查询不确定的字段前，请先自省架构。不要猜测——API的可用范围是有限的。

列出所有可用的突变：

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ __schema { mutationType { fields { name } } } }"}' | jq '[.data.__schema.mutationType.fields[].name]'

列出所有可用的查询：

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ __schema { queryType { fields { name } } } }"}' | jq '[.data.__schema.queryType.fields[].name]'

检查特定类型的字段：

bash

curl -s -X POST https://api.buffer.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BUFFER_API_TOKEN" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{"query": "{ __type(name: \"<TYPE_NAME>\") { fields { name type { name kind } } } }"}' | jq '.data.__type.fields[]'

Error Handling

错误处理

GraphQL Errors

GraphQL错误

Check for the top-level

errors

array in every response:

bash

result=$(curl -s -X POST https://api.buffer.com ...)
errors=$(echo "$result" | jq -r '.errors // empty')
if [ -n "$errors" ]; then
  echo "GraphQL Error:"
  echo "$result" | jq '.errors[].message'
  exit 1
fi

检查每个响应中的顶层

errors

数组：

bash

result=$(curl -s -X POST https://api.buffer.com ...)
errors=$(echo "$result" | jq -r '.errors // empty')
if [ -n "$errors" ]; then
  echo "GraphQL Error:"
  echo "$result" | jq '.errors[].message'
  exit 1
fi

Mutation Errors

突变错误

Mutations return union types. Always handle the

MutationError

variant:

json

{
  "data": {
    "createPost": {
      "message": "Validation failed: text is required"
    }
  }
}

突变返回联合类型。需始终处理

MutationError

变体：

json

{
  "data": {
    "createPost": {
      "message": "Validation failed: text is required"
    }
  }
}

Common Issues

常见问题

403 Forbidden (error code 1010): Cloudflare is blocking the request. Always include
```
-H "User-Agent: Mozilla/5.0"
```
in every curl call.
401 Unauthorized: Token is invalid or expired. Regenerate at https://publish.buffer.com/settings/api
Missing organizationId: Most queries require an org ID. Fetch organizations first.
Invalid channelId: Verify the channel exists and belongs to the current organization.
Past dueAt: When using
```
customSchedule
```
, the
```
dueAt
```
must be in the future.

403 Forbidden（错误码1010）: Cloudflare拦截了请求。请确保在每个curl调用中都包含
```
-H "User-Agent: Mozilla/5.0"
```
。
401 Unauthorized: 令牌无效或已过期。请在https://publish.buffer.com/settings/api重新生成。
缺少organizationId: 大多数查询需要组织ID。请先获取组织列表。
无效channelId: 请验证该频道存在且属于当前组织。
dueAt为过去时间: 使用
```
customSchedule
```
时，
```
dueAt
```
必须设置为未来时间。