A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Buffer API is how an app or AI agent works with a Buffer account: listing connected social profiles, queuing and editing posts, sharing a queued post immediately, and reordering or deleting items in the queue. Access is granted through a single OAuth 2.0 access token that carries the whole account's access, because the classic API has no granular per-endpoint permissions to narrow what a call can touch. It does not push events, so an agent learns about queue and posting activity by reading the pending and sent updates rather than receiving a callback.
How an app or AI agent connects to Buffer determines what it can reach. The classic API uses a single OAuth 2.0 access token that carries the account's own access, and Buffer's modern platform adds a hosted server that exposes Buffer to agents.
The classic REST API answers at https://api.bufferapp.com under a /1 path prefix and returns JSON. A call authenticates with an OAuth 2.0 access token, sent in the Authorization header or as an access_token parameter. It is in maintenance, and new app registrations against it are restricted.
Buffer hosts an official Model Context Protocol server at https://mcp.buffer.com/mcp, part of its modern API platform rather than the classic REST API. An MCP-compatible AI client connects with the endpoint URL and an API key sent in the Authorization header, to query posts, schedules, and engagement and to create posts.
Buffer's modern platform exposes a GraphQL API documented at developers.buffer.com, which supersedes the classic REST API for new builds. It covers accounts, organizations, channels, posts, and ideas, and is the route Buffer directs new integrations to.
The classic API uses the OAuth 2.0 authorization-code flow: an app sends the user to bufferapp.com/oauth2/authorize, then exchanges the returned code for an access token at the token endpoint. The token is sent on each call in the Authorization header or as an access_token parameter, and carries the account's own access with no per-endpoint scopes.
Buffer's modern platform, including its hosted MCP server, authenticates with an API key sent in the Authorization header. This is separate from the classic API's OAuth token.
The Buffer API is built around social media profiles and the updates queued against them, with methods for reading profiles and their schedules, queuing and editing updates, sharing or deleting them, and reordering the queue. Writes here change what gets published to a connected social account.
Read the account behind the access token.
List the connected social media profiles and read a single profile's details.
Read a profile's posting schedule and set the days and times it posts.
List pending and sent updates, read a single update and its interactions, create and edit updates, share immediately, delete, move to top, reorder, and shuffle the queue.
Read how many times a link has been shared through Buffer.
Read Buffer's current configuration, including supported services and their limits.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
UserRead the account behind the access token.1 | ||||||
| GET | /1/user.json | Return the single user behind the access token. | read | — | Current | |
The classic API has no per-endpoint scopes; the access token carries the account's own access. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProfilesList the connected social media profiles and read a single profile's details.2 | ||||||
| GET | /1/profiles.json | Return an array of social media profiles connected to the account. | read | — | Current | |
Each profile is one connected social account (the service, avatar, timezone, and schedule). No per-endpoint scope. Acts onprofile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/profiles/{id}.json | Return the details of a single specified social media profile. | read | — | Current | |
Returns 403 with code 1011 if the token has no access to the profile. No per-endpoint scope. Acts onprofile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SchedulesRead a profile's posting schedule and set the days and times it posts.2 | ||||||
| GET | /1/profiles/{id}/schedules.json | Return the posting schedules associated with a social media profile. | read | — | Current | |
A schedule is the set of days and times the profile posts at. No per-endpoint scope. Acts onschedule Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/profiles/{id}/schedules/update.json | Set the posting schedules for the specified social media profile. | write | — | Current | |
Changes when queued updates go out. Returns code 1013 if a profile's schedule limit is reached. No per-endpoint scope. Acts onschedule Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UpdatesList pending and sent updates, read a single update and its interactions, create and edit updates, share immediately, delete, move to top, reorder, and shuffle the queue.11 | ||||||
| GET | /1/profiles/{id}/updates/pending.json | Return the updates currently in the buffer (queued) for an individual social media profile. | read | — | Current | |
Paged through page and count parameters, where count is 1 to 100. No per-endpoint scope. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/profiles/{id}/updates/sent.json | Return the updates that have been sent from the buffer for an individual social media profile. | read | — | Current | |
Paged through page and count parameters, where count is 1 to 100. No per-endpoint scope. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/updates/{id}.json | Return a single social media update. | read | — | Current | |
Returns code 1020 if the update is not found, 1021 if the token has no access. No per-endpoint scope. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1/updates/{id}/interactions.json | Return detailed information on interactions with the update, such as favorites, retweets, and likes. | read | — | Current | |
Read-only; interaction data depends on what the underlying social network exposes. No per-endpoint scope. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/updates/create.json | Create one or more new status updates, queued to one or more profiles. | write | — | Current | |
Takes profile_ids and the text or media. Returns code 1023 or 1028 when a profile's update limit is reached, 1025 for duplicate content. No per-endpoint scope. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/updates/{id}/update.json | Edit an existing, individual status update. | write | — | Current | |
Edits the text, media, or scheduled time of a queued update. No per-endpoint scope. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/updates/{id}/share.json | Immediately share a single pending update and recalculate times for the updates remaining in the queue. | write | — | Current | |
Publishes now rather than at the scheduled time. No per-endpoint scope. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/updates/{id}/destroy.json | Permanently delete an existing status update. | write | — | Current | |
Irreversible; removes the update from the queue. No per-endpoint scope. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/updates/{id}/move_to_top.json | Move an existing status update to the top of the queue and recalculate the queue's times. | write | — | Current | |
Returns code 1027 when the update is custom-scheduled rather than in the buffer. No per-endpoint scope. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/profiles/{id}/updates/reorder.json | Edit the order in which queued updates will be sent out of the buffer. | write | — | Current | |
Takes an ordered list of update ids for the profile's queue. No per-endpoint scope. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1/profiles/{id}/updates/shuffle.json | Randomize the order in which queued updates will be sent out of the buffer. | write | — | Current | |
Reshuffles the pending queue for the profile. No per-endpoint scope. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
LinksRead how many times a link has been shared through Buffer.1 | ||||||
| GET | /1/links/shares.json | Return the number of shares a link has had through Buffer. | read | — | Current | |
Takes a url query parameter and returns its Buffer share count. No per-endpoint scope. Acts onlink Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InfoRead Buffer's current configuration, including supported services and their limits.1 | ||||||
| GET | /1/info/configuration.json | Return Buffer's current configuration, including supported services, their icons, and the character and schedule limits. | read | — | Current | |
Read-only metadata about supported services and their limits. No per-endpoint scope. Acts onconfiguration Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
The classic Buffer API does not push events. An app or AI agent learns about queue and posting activity by calling the API, such as listing the pending and sent updates for a profile, rather than receiving a callback.
| Event | What it signals | Triggered by |
|---|
Buffer limits how fast an app or AI agent can call the classic API through a per-token request rate, and separately caps how many updates a single profile can hold in its queue.
Buffer's classic API is rate limited per access token, with the documented limit being 60 authenticated requests per token per minute; exceeding it returns HTTP 429 Too Many Requests. Buffer no longer publishes the classic rate-limit page, so the exact header names and any newer thresholds are not verifiable from a current first-party source. Buffer's modern platform applies its own per-client limits over rolling windows and reports them in RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset response headers.
List endpoints for pending and sent updates page through the page and count query parameters, where count sets the page size between 1 and 100. There is no cursor model in the classic API.
Per-profile limits cap how many updates a queue can hold and how long the text of an update can be; the exact values vary by social service and are returned by the info/configuration endpoint rather than fixed across the API. Creating beyond a profile's update limit returns code 1023 or 1028.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 403 | 1001 | An access token is required, or the token is missing or invalid. | Send a valid OAuth 2.0 access token in the Authorization header or as an access_token parameter. |
| 403 | 1011 | No authorization to access the requested profile. | Confirm the token's account has the profile connected and accessible. |
| 400 | 1004 | A required parameter is missing from the request. | Read the error message, add the missing parameter, and resend. |
| 400 | 1023 | The update limit for the profile has been reached, so no more updates can be queued. | Wait for queued updates to send, or remove some, before creating more. |
| 400 | 1025 | The update was recently posted, so duplicate content cannot be posted again. | Change the content, or target a different profile, before resending. |
| 400 | 1027 | An update must be in the buffer and not custom-scheduled in order to move it to the top. | Confirm the update is a queued buffer item before calling move_to_top. |
| 404 | 1020 | The requested update could not be found. | Confirm the update id is correct and belongs to a profile the token can reach. |
The classic Buffer API is a single, unversioned interface served under a /1 path prefix, with no dated version string to pin. Buffer has since built a separate modern API platform that supersedes it.
The classic Buffer API is served under a /1 path prefix at api.bufferapp.com and has no dated version string. It exposes user, profiles, schedules, updates, links, and info methods, authenticated by a single OAuth 2.0 access token. It is in maintenance, restricts new app registrations, and its public reference pages now redirect to Buffer's modern developer platform.
Buffer built a separate modern API platform, documented at developers.buffer.com, that supersedes the classic REST API for new builds. It adds a GraphQL API covering accounts, organizations, channels, posts, and ideas, plus an official hosted MCP server, and is where Buffer directs new integrations.
The classic API is in maintenance and new app registrations against it are restricted; new builds use Buffer's modern platform.
Buffer developer docs ↗Bollard AI sits between a team's AI agents and Buffer. Grant each agent exactly the access it needs, read or write, profile by profile, and every call is checked and logged.