buffer

Troubleshooting

If requests fail, run

zero doctor check-connector --env-name BUFFER_TOKEN

zero doctor check-connector --url https://api.buffer.com --method POST

Beta API. Buffer's public API is currently in beta. Personal API keys replace the legacy OAuth v1 API. Only organization owners can create keys (paid accounts: up to 5 keys, free accounts: 1 key). The legacy REST API at
api.bufferapp.com/1/*
still exists but is not accepting new developer applications and requires OAuth — it is not used by this connector.

How It Works

Buffer is a social media scheduling platform. The beta API is GraphQL-only, served from a single endpoint. Every request is a

POST

with a JSON

{"query": "...", "variables": {...}}

body.

Account
└── Organizations
    └── Channels (Twitter, LinkedIn, Instagram, Facebook, TikTok, Threads, Mastodon, Bluesky, Pinterest, YouTube, Google Business)
        └── Posts (draft | scheduled | sent)

Base URL:

https://api.buffer.com

Authentication

All requests require a personal API key passed as a Bearer token:

Authorization: Bearer $BUFFER_TOKEN
Content-Type: application/json

Requests without a valid key return

401 Unauthorized

Environment Variables

Variable	Description
`BUFFER_TOKEN`	Buffer personal API key (from Developer Dashboard)

Key Operations

All calls hit the same endpoint:

POST https://api.buffer.com

. Change only the GraphQL document.

1. List Organizations

Write

/tmp/buffer_orgs.json

json

{
  "query": "query GetOrganizations { account { organizations { id name } } }"
}

bash

curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_orgs.json

2. List Channels (Connected Social Accounts)

Write

/tmp/buffer_channels.json

— replace

<organization-id>

with an id from step 1:

json

{
  "query": "query GetChannels($organizationId: String!) { channels(input: { organizationId: $organizationId }) { id name service serviceId serviceType timezone } }",
  "variables": { "organizationId": "<organization-id>" }
}

bash

curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_channels.json

3. Create a Scheduled Post

Buffer publishes the same text to one or more channels. Write

/tmp/buffer_create_post.json

— replace

<channel-id>

with a channel id from step 2.

scheduledAt

is an ISO-8601 timestamp; omit it to add to the end of the queue.

json

{
  "query": "mutation CreatePost($input: PostCreateInput!) { createPost(input: $input) { id status scheduledAt text } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "channelIds": ["<channel-id>"],
      "text": "Launching today: our new onboarding flow. Read more at https://example.com",
      "scheduledAt": "2026-05-01T15:00:00Z",
      "status": "scheduled"
    }
  }
}

bash

curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_create_post.json

Valid

status

values:

```
draft
```
— saved as a draft, not queued
```
scheduled
```
— queued at
```
scheduledAt
```
```
needsApproval
```
— posted to the approval queue

4. Create a Post with Media

Attach images or a video by passing a

media

object. Write

/tmp/buffer_create_image_post.json

json

{
  "query": "mutation CreatePost($input: PostCreateInput!) { createPost(input: $input) { id status } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "channelIds": ["<channel-id>"],
      "text": "Ship log: weekly changelog is live.",
      "media": {
        "photos": [
          { "url": "https://example.com/screenshot.png", "altText": "Changelog screenshot" }
        ]
      },
      "status": "scheduled",
      "scheduledAt": "2026-05-01T15:00:00Z"
    }
  }
}

bash

curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_create_image_post.json

For video, swap

photos

for

video: { url: "<url>", thumbnailUrl: "<url>" }

5. List Pending/Scheduled Posts

Write

/tmp/buffer_posts.json

json

{
  "query": "query GetPosts($input: PostsInput!) { posts(input: $input) { edges { node { id status text scheduledAt channel { id service } } } pageInfo { hasNextPage endCursor } } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "status": ["scheduled"],
      "first": 25
    }
  }
}

bash

curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_posts.json | jq '.data.posts.edges[].node'

Change

status

["sent"]

for history,

["draft"]

for drafts, or

["needsApproval"]

for the approval queue.

6. Update a Post

Write

/tmp/buffer_update_post.json

— replace

<post-id>

json

{
  "query": "mutation UpdatePost($input: PostUpdateInput!) { updatePost(input: $input) { id text scheduledAt } }",
  "variables": {
    "input": {
      "postId": "<post-id>",
      "text": "Updated copy.",
      "scheduledAt": "2026-05-02T15:00:00Z"
    }
  }
}

bash

curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_update_post.json

7. Delete a Post

Write

/tmp/buffer_delete_post.json

json

{
  "query": "mutation DeletePost($input: PostDeleteInput!) { deletePost(input: $input) { id } }",
  "variables": { "input": { "postId": "<post-id>" } }
}

bash

curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_delete_post.json

8. Publish Immediately (Share Now)

Set

status: "scheduled"

and

scheduledAt

to a timestamp a few seconds in the past, or use the dedicated share mutation when available. For queue-top placement, omit

scheduledAt

and set

shareNext: true

in the input.

Common Workflows

Cross-Post to Multiple Channels

Put all target channel IDs in the same

channelIds

array. Buffer fans out one post per channel and returns a single parent post id.

json

{
  "query": "mutation CreatePost($input: PostCreateInput!) { createPost(input: $input) { id } }",
  "variables": {
    "input": {
      "organizationId": "<organization-id>",
      "channelIds": ["<twitter-channel-id>", "<linkedin-channel-id>", "<bluesky-channel-id>"],
      "text": "Launching today.",
      "status": "scheduled",
      "scheduledAt": "2026-05-01T15:00:00Z"
    }
  }
}

Paginate Sent Posts

bash

# First page
curl -s -X POST "https://api.buffer.com" --header "Authorization: Bearer $BUFFER_TOKEN" --header "Content-Type: application/json" -d @/tmp/buffer_posts.json | jq '{next: .data.posts.pageInfo.endCursor, nodes: [.data.posts.edges[].node | {id, text, scheduledAt}]}'

Replace the

"first"

field in

input

with

"after": "<endCursor>"

to continue.

Guidelines

Send payloads as JSON files with
```
-d @/tmp/filename.json
```
— do not inline complex GraphQL documents.
Query introspection is the fastest way to discover unfamiliar fields:
```
{"query": "{ __schema { queryType { fields { name } } } }"}
```
.
Rate limits are per-client and rolling — personal API keys share one bucket; if you have multiple keys, create a distinct key per integration.
Analytics data is not exposed in the beta API yet. For post-level stats, use Buffer's web dashboard.
Do not edit posts that have already been sent — Buffer's API currently rejects
```
updatePost
```
once
```
status: "sent"
```
.
Organization IDs are stable; cache them instead of re-querying on every request.

buffer

NPX Install

Tags

SKILL.md Content

Troubleshooting

How It Works

Authentication

Environment Variables

Key Operations

1. List Organizations

2. List Channels (Connected Social Accounts)

3. Create a Scheduled Post

4. Create a Post with Media

5. List Pending/Scheduled Posts

6. Update a Post

7. Delete a Post

8. Publish Immediately (Share Now)

Common Workflows

Cross-Post to Multiple Channels

Paginate Sent Posts

Guidelines