The Content Publishing API is in closed beta with Facebook Marketing Partners and Instagram Partners only. We are not accepting new applicants at this time.

Content Publishing API

The Content Publishing API is a subset of Instagram Graph API endpoints that allow you to publish media objects. Publishing media objects with this API is a two step process — you first create a media object container, then publish the container on your Business Account.

Currently, the API can only be used to publish photos.

Endpoints

The API consists of the following endpoints:

Refer to each endpoint's reference documentation for parameter and permission requirements.

Common Uses

Publishing Photos

Publishing photos is a two-step process:

  1. Use the /user/media edge to create a media object container, then
  2. Use the /user/media_publish edge to publish that container

For example, let's say you have a photo at...

https://www.example.com/images/bronz-fonz.jpg

... that you want to publish with the hashtag "#BronzFonz" as its caption. You could use the /user/media edge to create the container like this:

Sample Request

POST graph.facebook.com/17841400008460056/media
  ?image_url=https//www.example.com/images/bronz-fonz.jpg
  &caption=#BronzFonz

This would return a container ID (let's say 17889455560051444), which you would then publish using the /user/media_publish edge, like this:

Sample Request

POST graph.facebook.com/17841405822304914/media_publish
  ?creation_id=17889455560051444

Publishing Photos w/ Tagged Users

You can tag public Instagram Users in a photo and they will receive a notification when you publish the media container.

To do this, follow the Publishing Photos steps above, but when creating the media container, include the user_tags parameter and an array of objects indicating the Users in the photo as well as their x/y coordinates within the photo itself.

For example, let's say you want to publish a photo that depicts two of your Instagram friends who you want to tag. You could use the /user/media edge to create the container like this:

Sample Request

POST graph.facebook.com/17841400008460056/media
  ?image_url=https://www.example.com/images/bronzed-fonzes.jpg
  &caption=#BronzedFonzes!
  &user_tags=
   [
     {
       username:'kevinhart4real',
       x: 0.5,
       y: 0.8
     },
     {
       username:'therock',
       x: 0.3,
       y: 0.2
     }
   ]

This would return a container ID which you would then publish using the /user/media_publish edge.

Notes

  • The user_tags value must be an array of objects formatted with JSON.
  • You can only tag Users with public Instagram accounts.
  • The object must contain all three properties (username, x, and y) for each user.
  • x and y values must be float numbers that originate from the top-left of the image, with a range of 0.01.0.

Publishing Photos w/ Locations

You can use our Places Search API to get an ID for any Place that has been entered into our Places Graph. If you include the ID when publishing a photo, the photo will be tagged with the Place's location.

To do this, first query the Places Graph API to get the Place's ID. For example, let's say you took your photo just outside New York City's Guggenheim Museum. You could get the Guggenheim's Places Graph object ID like this:

GET https://graph.facebook.com/search?
  type=place
  &q=guggenheim

This would return an array of objects with "guggenheim" in their name, and their IDs, one of which is for the Guggenheim in New Your City:

{
  "name": "Solomon R. Guggenheim Museum",
  "id": "7640348500"
}

There are different ways to query the Places Graph. We won't cover that here, so please refer to the Places Search API developer documents to learn the various ways to use it.

Once you have the Place's ID, follow the Publishing Photos steps above and use the location_id parameter to pass us the id when creating your media object container.

Sample Request

POST graph.facebook.com/17841400008460056/media
  ?image_url=https://www.example.com/images/gugges.jpg
  &caption=Exhibitioning!
  &location_id=7640348500

This would return a container ID which you would then publish using the /user/media_publish edge.

Requirements & Limitations

Requirements:

  • We will cURL your image using the passed in URL so it must be on a public image server
  • Maximum file size: 8MB
  • Must be within a 4:5 to 1.91:1 aspect ratio range
  • Minimum resolution: 150x150 (lower resolutions will be scaled up to the minimum)
  • Maximum resolution: 1920x1080 (higher resolutions will be scaled down to the maximum)

Supported formats:

  • JPEG, PNG, BMP, and non-animated GIFs

We do not support:

  • Extended JPEG formats such as MPO and JPS
  • Stories
  • Videos
  • Shopping tags
  • Branded content tags
  • Filters
  • Multi-image posts

Errors

  • If you run into errors generating a container, it's safe to retry until you successfully receive a container ID.
  • If you run into errors publishing a container, retry with the same container ID until you succeed. To prevent duplicate posts, avoid creating and publishing a new container ID.