AI agent skill · by @proflead

Buffer Api

Manage Buffer content via the GraphQL API. Use when creating, scheduling, editing, or deleting posts, saving ideas, reading scheduled queues, or pulling post analytics. Not for general API debugging.

Archived 2026-10-23 · Source updated 2026-07-29. Check the original repository for the latest version.

SKILL.md instructions

# Buffer API — Content Operations

## Purpose
Create, schedule, edit, and analyze social media content through Buffer's GraphQL API at `https://api.buffer.com`.

## Inputs to request
- What to do: create, schedule, draft, edit, delete, list, or analyze a post — or save/list ideas.
- Channel ID(s) to target (or ask the user to run the "get channels" query first).
- Post content: text, and optionally image/video URLs or thread structure.
- Scheduling intent: add to queue, schedule at a specific time, publish now, or save as draft.
- For analytics: which post ID(s) and which metrics matter (impressions, reactions, comments, etc.).

## Operations map

| Goal | API call |
|------|----------|
| Create / schedule a post | `createPost` mutation |
| Save a post as draft | `createPost` with `saveToDraft: true` |
| Edit an existing post | `editPost` mutation |
| Delete a post | `deletePost` mutation |
| List scheduled / sent posts | `posts` query with `filter: { status: [scheduled] }` |
| Get a single post | `post` query by ID |
| Read post metrics | `post { metrics }` or `aggregatedPostMetrics` query |
| Save a content idea | `createIdea` mutation |
| Find channel IDs | `channels` query by organization ID |
| Find organization ID | `account { organizations { id } }` query |

## Auth setup (one-time)
All requests need `Authorization: Bearer $BUFFER_API_KEY` and `Content-Type: application/json`.

For personal scripts and automations: use an API key from `https://publish.buffer.com/settings/api`.
For multi-user apps: use OAuth 2.0 with PKCE — authorize at `https://auth.buffer.com/auth`, exchange at `https://auth.buffer.com/token`. Refresh tokens are single-use; always save the new one immediately after refresh.

## Workflow

1. **Get your organization ID** (first time only):
   ```graphql
   query { account { organizations { id name } } }
   ```

2. **Get channel IDs** for your target platforms:
   ```graphql
   query GetChannels($orgId: String!) {
     channels(input: { organizationId: $orgId }) {
       id name service
     }
   }
   ```

3. **Create or schedule the post** using the relevant example below.

4. **Check the response** — the mutation returns a union type. `PostActionSuccess` means it worked; `MutationError` carries the reason it failed. GraphQL always responds with HTTP 200, so always inspect the response body.

5. **Edit or delete** if needed using the post `id` returned in step 3.

6. **Pull analytics** after the post publishes (metrics are refreshed daily; allow up to 24 hours after publish).

## Examples

### Create a text post (add to queue)
```graphql
mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    ... on PostActionSuccess {
      post { id text status dueAt }
    }
    ... on MutationError { message }
  }
}
```
```json
{
  "input": {
    "text": "Your post content here",
    "channelId": "$CHANNEL_ID",
    "schedulingType": "automatic",
    "mode": "addToQueue"
  }
}
```

### Schedule at a specific time
```json
{
  "input": {
    "text": "Your post content here",
    "channelId": "$CHANNEL_ID",
    "schedulingType": "automatic",
    "mode": "customScheduled",
    "dueAt": "2026-07-01T14:00:00.000Z"
  }
}
```

### Save as draft
```json
{
  "input": {
    "text": "Draft content here",
    "channelId": "$CHANNEL_ID",
    "schedulingType": "automatic",
    "mode": "addToQueue",
    "saveToDraft": true
  }
}
```

### Post with image
```json
{
  "input": {
    "text": "Your caption here",
    "channelId": "$CHANNEL_ID",
    "schedulingType": "automatic",
    "mode": "addToQueue",
    "assets": [{ "image": { "url": "https://your-public-image-url.jpg" } }]
  }
}
```
Image URL must be publicly accessible. Each asset entry specifies exactly one type: `image`, `video`, `document`, or `link`.

### Edit an existing post
```graphql
mutation EditPost($input: EditPostInput!) {
  editPost(input: $input) {
    ... on PostActionSuccess {
      post { id text status dueAt }
    }
    ... on MutationError { message }
  }
}
```
```json
{ "input": { "id": "$POST_ID", "text": "Updated content here" } }
```

### Delete a post
```graphql
mutation DeletePost {
  deletePost(input: { id: "$POST_ID" }) {
    ... on PostActionSuccess { post { id } }
    ... on MutationError { message }
  }
}
```

### List scheduled posts
```graphql
query GetScheduledPosts($orgId: String!) {
  posts(input: {
    organizationId: $orgId,
    filter: { status: [scheduled] },
    sort: [{ field: dueAt, direction: asc }]
  }) {
    edges {
      node { id text dueAt channelId }
    }
    pageInfo { hasNextPage endCursor }
  }
}
```
For more pages, add `after: "$endCursor"` to `input`. Page size: 20–50 items.

### Get post analytics
```graphql
query GetPostMetrics {
  post(input: { id: "$POST_ID" }) {
    id text metricsUpdatedAt
    metrics { type name value unit }
  }
}
```
Available metric types (varies by network): `reactions`, `reposts`, `comments`, `shares`, `impressions`, `reach`, `views`, `saves`, `follows`, `likes`. Metrics appear up to ~24 hours after publish.

### Save an idea
```graphql
mutation CreateIdea($input: CreateIdeaInput!) {
  createIdea(input: $input) {
    ... on MutationError { message }
  }
}
```
```json
{
  "input": {
    "organizationId": "$ORG_ID",
    "content": { "title": "Optional title", "text": "Idea content here" }
  }
}
```
Ideas are org-level (not tied to a channel). Promote to a post by using the idea's text in `createPost`.

## Rate limits
Buffer enforces three time windows. On HTTP 429, read `retryAfter` (seconds) from the response body.

| Plan | 15-min | 24-hr | 30-day |
|------|--------|-------|--------|
| Free | 100 | 100 | 3,000 |
| Essentials | 100 | 250 | 7,500 |
| Team | 100 | 500 | 15,000 |

## Troubleshooting
- **No `post` field in mutation response** → `MutationError` fired; log `data.<mutationName>.message`.
- **`UNAUTHORIZED`** → check `Authorization: Bearer $BUFFER_API_KEY` header is present and token is valid.
- **`FORBIDDEN`** → token lacks the right scope (e.g., `posts:write` needed for create/edit/delete).
- **Metrics missing** → post published less than 24 hours ago; check `metricsUpdatedAt`.
- **Image not attaching** → URL must be publicly accessible; see the Hosting Media guide.

## Quality bar
- Always use GraphQL variables — never interpolate user content into query strings.
- Include `... on MutationError { message }` in every mutation.
- Never expose real tokens or channel IDs in examples.
- Metrics API is preview-only and available for personal API keys only (not OAuth apps).