Buffer Developers

Updates

An update represents a single post to a single social media account. An update can also include media attachments such as pictures and links.

GET /updates/:id

Returns a single social media update.

Example Request

GET https://api.bufferapp.com/1/updates/4eb8565e0acb04bb82000004.json

{ 
  "id" : "4eb8565e0acb04bb82000004",
  "created_at" : 1320703582,
  "day" : "Monday 7th November",
  "due_at" : 1320742680,
  "due_time" : "10:09 pm",
  "profile_id" : "4eb854340acb04e870000010",
  "profile_service" : "twitter",
  "sent_at" : 1320744001,
  "service_update_id" : "133667319959392256",
  "statistics" : { 
      "reach" : 2460,
      "clicks" : 56,
      "retweets": 20,
      "favorites": 1,
      "mentions": 1
  },
  "status" : "sent",
  "text" : "This is just the beginning, the very beginning, of the transfor...",
  "text_formatted" : "This is just the beginning, the very beginning, of th...",
  "user_id" : "4eb9276e0acb04bb81000067",
  "via" : "chrome"
}

GET /profiles/:id/updates/pending

Returns an array of updates that are currently in the buffer for an individual social media profile.

Parameters

page optional integer Specifies the page of status updates to receive. If not specified the first page of results will be returned.
count optional integer Specifies the number of status updates to receive. If provided, must be between 1 and 100.
since optional timestamp Specifies a unix timestamp which only status updates created after this time will be retrieved.
utc optional boolean If utc is set times will be returned relative to UTC rather than the users associated timezone.

Example Request

GET https://api.bufferapp.com/1/profiles/4eb854340acb04e870000010/updates/pending.json

{
  "total" : 8,
  "updates" : [ {
      "id" : "4ec93ae4512f7e6307000002",
      "created_at" : 1320703582,
      "day" : "Monday 7th November",
      "due_at" : 1320543480,
      "due_time" : "07:01 pm",
      "profile_id" : "4eb854340acb04e870000010",
      "profile_service" : "twitter",
      "status" : "buffer",
      "text" : "This is me in an alternate life where i can breakdance j.mp/w...",
      "text_formatted" : "This is me in an alternate life where i can breakda...",
      "user_id" : "4eb9276e0acb04bb81000067",
      "via" : "firefox"
  },
  {
      ...
  }]
}

GET /profiles/:id/updates/sent

Returns an array of updates that have been sent from the buffer for an individual social media profile.

Parameters

page optional integer Specifies the page of status updates to receive. If not specified the first page of results will be returned.
count optional integer Specifies the number of status updates to receive. If provided, must be between 1 and 100.
since optional timestamp Specifies a unix timestamp which only status updates sent after this time will be retrieved.
utc optional boolean If utc is set times will be returned relative to UTC rather than the users associated timezone.

Example Request

GET https://api.bufferapp.com/1/profiles/4eb854340acb04e870000010/updates/sent.json

{
  "total" : 97,
  "updates" : [ {
      "id" : "4ebc559d0acb04221b000008",
      "created_at" : 1320703582,
      "day" : "Monday 7th November",
      "due_at" : 1320742680,
      "due_time" : "10:09 pm",
      "profile_id" : "4eb854340acb04e870000010",
      "profile_service" : "twitter",
      "sent_at" : 1320744001,
      "service_update_id" : "133667319959392256",
      "statistics" : { 
          "reach" : 2460,
          "clicks" : 56,
          "retweets": 20,
          "favorites": 1,
          "mentions": 1
      },
      "status" : "sent",
      "text" : "This is just the beginning, the very beginning, of the tran...",
      "text_formatted" : "This is just the beginning, the very beginning, o...",
      "user_id" : "4eb9276e0acb04bb81000067",
      "via" : "chrome"
  },
  {
      ...
  }]
}

GET /updates/:id/interactions

Returns the detailed information on individual interactions with the social media update such as favorites, retweets and likes.

Parameters

page optional integer Specifies the page of interactions to receive. If not specified the first page of results will be returned.
count optional integer Specifies the number of interactions to receive. If provided, must be between 1 and 100.
event optional string Specifies a type of event to be retrieved, for example "retweet", "favorite", "like", "comment", "mention" or "share". They can also be plural (e.g., "shares"). Plurality has no effect other than visual semantics.

Example Request

GET https://api.bufferapp.com/1/updates/4ecda476542f7ee521000006/interactions.json

{
    "total":2,
    "interactions":[
        {
            "_id":"50f98310c5ac415d7f2e74fd",
            "created_at":1358509258,
            "event":"favorite",
            "id":"50f98310c5ac415d7f2e74fd",
            "interaction_id":"292235127847788544",
            "user":{
                "username":"Crispy Potatoes",
                "followers":160,
                "avatar":"http:\/\/si0.twimg.com\/profile_images\/...",
                "avatar_https":"https:\/\/si0.twimg.com\/profile_images\/...",
                "twitter_id":"70712344376"
            }
        },
        {
            "_id":"50f8623ac5ac415d7f1d4f77",
            "created_at":1358454592,
            "event":"retweet",
            "id":"50f8623ac5ac415d7f1d4f77",
            "interaction_id":"292005842654461953",
            "user":{
                "username":"Lucky Number 8",
                "followers":36079,
                "avatar":"http:\/\/si0.twimg.com\/profile_images\/2901468678\/...",
                "avatar_https":"https:\/\/si0.twimg.com\/profile_images\/2901468678\/...",
                "twitter_id":"1423444249"
            }
        }
    ]
}

POST /profiles/:id/updates/reorder

Edit the order at which statuses for the specified social media profile will be sent out of the buffer.

Parameters

order required integer An ordered array of status update id’s. This can be a partial array in combination with the offset parameter or a full array of every update in the profiles Buffer.
offset optional integer Specifies the number of status updates to receive. If provided, must be between 1 and 100.
utc optional boolean If utc is set times will be returned relative to UTC rather than the users associated timezone.

Example Request

POST https://api.bufferapp.com/1/profiles/4eb854340acb04e870000010/updates/reorder.json

POST Data
    offset=10&
    order[]=4eb854340acb04e870000010&
    order[]=4eb9276e0acb04bb81000067&
    order[]=4eb2567e0ade04ba51000001

{
    "success" : true,
    "updates" : [{
        "id" : "4eb854340acb04e870000010",
        "created_at" : 1320703582,
        "day" : "Saturday 5th November",
        "due_at" : 1320742680,
        "due_time" : "08:01 am",
        "profile_id" : "4eb854340acb04e870000010",
        "profile_service" : "twitter",
        "status" : "buffer",
        "text" : "3 Incredible Stories Made Possible Through Twitter j.mp/u...",
        "text_formatted" : "3 Incredible Stories Made Possible Through Twit...",
        "user_id" : "4eb9276e0acb04bb81000067",
        "via" : "safari"
    },
    {
    	...
    }]
}

POST /profiles/:id/updates/shuffle

Randomize the order at which statuses for the specified social media profile will be sent out of the buffer.

Parameters

count optional integer Specifies the number of status updates returned. These will correspond to the first status updates that will be posted.
utc optional boolean If utc is set times will be returned relative to UTC rather than the users associated timezone.

Example Request

POST https://api.bufferapp.com/1/profiles/4eb854340acb04e870000010/updates/shuffle.json

POST Data
    count=10

{
    "success" : true,
    "updates" : [{
        "id" : "4eb854340acb04e870000010",
        "created_at" : 1320703582,
        "day" : "Saturday 5th November",
        "due_at" : 1320742680,
        "due_time" : "08:01 am",
        "profile_id" : "4eb854340acb04e870000010",
        "profile_service" : "twitter",
        "status" : "buffer",
        "text" : "3 Incredible Stories Made Possible Through Twitter j.mp/u...",
        "text_formatted" : "3 Incredible Stories Made Possible Through Twit...",
        "user_id" : "4eb9276e0acb04bb81000067",
        "via" : "safari"
    },
    {
    	...
    }]
}

POST /updates/create

Create one or more new status updates.

Parameters

text required string The status update text
profile_ids required array An array of profile id’s that the status update should be sent to. Invalid profile_id’s will be silently ignored.
shorten optional boolean If shorten is false links within the text will not be automatically shortened, otherwise they will.
now optional boolean If now is set, this update will be sent immediately to all profiles instead of being added to the buffer.
top optional boolean If top is set, this update will be added to the top of the buffer and will become the next update sent.
media optional boolean An associative array of media to be attached to the update, currently accepts link, description and picture parameters.

Example Request

POST https://api.bufferapp.com/1/updates/create.json

POST Data
    text=This%20is%20an%20example%20update&
    profile_ids[]=4eb854340acb04e870000010&
    profile_ids[]=4eb9276e0acb04bb81000067&
    media[link]=http%3A%2F%2Fgoogle.com&
    media[description]=The%20google%20homepage

{
    "success" : true,
    "buffer_count" : 10,
    "buffer_percentage" : 20,
    "updates" : [{
        "id" : "4ecda256512f7ee521000004",
        "created_at" : 1320703582,
        "day" : "Saturday 26th November",
        "due_at" : 1320742680,
        "due_time" : "11:05 am",
        "media" : {
            "link" : "http://google.com",
            "title" : "Google",
            "description" : "The google homepage"
        },
        "profile_id" : "4eb854340acb04e870000010",
        "profile_service" : "twitter",
        "status" : "buffer",
        "text" : "This is an example update",
        "text_formatted" : "This is an example update",
        "user_id" : "4eb9276e0acb04bb81000067",
        "via" : "api"
    },
    {
    	...
    }]
}

POST /updates/:id/update

Edit an existing, individual status update.

Parameters

text required string The status update text
now optional boolean If now is set, this update will be sent immediately to all profiles instead of being added to the buffer.
media optional boolean An associative array of media to be attached to the update, currently accepts link, description and picture parameters.
utc optional boolean If utc is set times will be returned relative to UTC rather than the users associated timezone.

Example Request

POST https://api.bufferapp.com/1/updates/4ecda256512f7ee521000004/update.json

POST Data
    text=This%20is%20an%20edited%20update

{
    "success" : true,
    "buffer_count" : 10,
    "buffer_percentage" : 20,
    "update" : {
        "id" : "4ecda256512f7ee521000004",
        "client_id" : "4f850cc93733aa9301000002",
        "created_at" : 1320703582,
        "day" : "Saturday 26th November",
        "due_at" : 1320742680,
        "due_time" : "11:05 am",
        "media" : {
            "link" : "http://google.com",
            "title" : "Google",
            "description" : "The google homepage"
        },
        "profile_id" : "4eb854340acb04e870000010",
        "profile_service" : "twitter",
        "status" : "buffer",
        "text" : "This is an edited update",
        "text_formatted" : "This is an edited update",
        "user_id" : "4eb9276e0acb04bb81000067",
        "via" : "api"
    }
}

POST /updates/:id/share

Immediately shares a single pending update and recalculates times for updates remaining in the queue.

Example Request

POST https://api.bufferapp.com/1/updates/4ecda256512f7ee521000001/share.json

{
    "success" : true
}

POST /updates/:id/destroy

Permanently delete an existing status update.

Example Request

POST https://api.bufferapp.com/1/updates/4ecda256512f7ee521000004/destroy.json

{
    "success" : true
}
Get in Touch Submit an Idea