Instant Articles API

Instant Articles support syndication using the Instant Articles API. This API allows you to create, publish, update and delete Instant Articles directly from your content management system. Automated publication in the Instant Articles format on Facebook also occurs in real time.

Publish new stories via the Instant Articles API only when they are also publicly available on your website. The Instant Articles system requires access to each article's standard web URL to render the content properly.

Introduction to Using the API

Here’s how to set up automated publishing using the Instant Articles API:

1. Create a Facebook App ID

You'll need an existing Facebook app ID, which is used to issue calls to the Instant Articles API. If you don't already have an app ID, create a new one.

2. Distribute New Articles Using the API

Use the Instant Articles API to distribute your articles to the Instant Articles library for your Facebook Page. Using the API, you can create, update and delete Instant Articles directly from your content management system. Detailed guidance on the Instant Articles API endpoints is provided in the Instant Articles API Reference.

The Graph API Explorer can be a useful way to get started with using the Instant Articles API before you begin integrating the API into your publishing system.

3. Verify that Your Articles Are Processed Correctly

Double check your articles to ensure they are error-free and render properly. See the Testing and Debugging section for instructions on how to troubleshoot and eliminate errors.

4. Update Published Articles

At times you may want to update the content of a previously published article, as in the case of a developing news story. To automatically specify an article to update and republish, its HTML must include the op-published and op-modified <time> elements, and the updated article must be redistributed through the API.

Media assets associated with an article will only update if the URL of the media asset has changed.

5. Ensure Facebook Crawler Can Reach Your Content

To properly distribute your content to Instant Articles, ensure your content is visible to our crawler. If you normally restrict access to your content, you'll need to whitelist our crawler. Please refer to our Facebook Crawler guide for advice on how to identify our crawler and preferred approaches to whitelisting.

6. Submit 5 Articles for Review

You will be able to begin publishing Instant Articles after a sample of 5 your articles has successfully passed the Article Review process. Until then, you won't be able to publish Instant Articles.

Requirements

Before you begin using the Instant Articles API, you must have:

  • An existing Facebook page, which is used to publish Instant Articles. If you don't already have an existing Page, create a new one.
  • An existing Facebook app ID, which is used to issue calls to the Instant Articles API. If you don't already have an app ID, create a new one.

Authentication

All Instant Articles requests must be signed with a page access token, by which you can make API requests on behalf of your Facebook page. Page access tokens can only be generated on behalf of a person that has an Admin role on your Facebook page.

The following steps outline the approach for generating a valid page access token which you can use to issue Instant Articles requests.

1. Generate a User Access Token

In order to generate a page access token, you must first create a user access token by authenticating a person with your app and requesting the pages_manage_instant_articles and pages_show_list extended permissions. User access tokens are generated through the Facebook Login dialog, which prompts the person to grant the pages_manage_instant_articles and pages_show_list permissions to your app. You may use Facebook's Javascript SDK to invoke the Login Dialog or manually build the login flow on your own.

Once you have successfully generated a valid user access token, you will need to transfer the token to your servers in order to extend the life of the token and retrieve the page access token.

For more information on how to generate a user access token, refer to our User Token documentation.

2. Exchange for a Long-Lived Token

The user access token generated by the authentication flow will only last for about an hour or two, so you will want to extend the life of the token in order to maintain the ability to issue requests to the Instant Articles API on an ongoing basis. Once you have generated a valid user access token, you can exchange this token for a long-lived user access token, which will provide you with the ability to then retrieve a page access token that does not expire.

From your server, issue the following call in order to exchange the short-lived user access token for a long-lived token:

GET /oauth/access_token?  
    grant_type=fb_exchange_token&amp;           
    client_id={app-id}&amp;
    client_secret={app-secret}&amp;
    fb_exchange_token={short-lived-token} 

You can find the App ID and App Secret for your app on your App Dashboard.

For more information on generating long-lived tokens, refer to our Access Token documentation.

3. Retrieve Page Access Token

Once you have generated a long-lived user access token, you can retrieve a page access token that never expires. Issue the following call, which will return a list of pages that the person has access to and will include the page access token for the page:

GET /{user-id}/accounts

If the person manages multiple pages, you will need to lookup the page token by the ID of the page:

{
  "data": [
    {
      "category": "Product/service",
      "name": "Sample Page",
      "access_token": "{access-token}",
      "id": "1234567890",
      "perms": [
        "ADMINISTER",
        "EDIT_PROFILE",
        "CREATE_CONTENT",
        "MODERATE_CONTENT",
        "CREATE_ADS",
        "BASIC_ADMIN"
      ]
    }, 
}

Retrieve the page access token from the access_token field for the desired page and store this token on your servers in order to issue requests to the Instant Articles API on behalf of this person.

List All Articles

To get the full list of article IDs that have been created for a specific Facebook Page, issue a GET request to:

https://graph.facebook.com/{page-id}/instant_articles

Fields

Name Description Type

access_token [required]

A valid page access token.

string

after

Returns articles after this provided cursor, for paging purposes.

int

before

Returns articles before this provided cursor, for paging purposes.

int

development_mode

Returns articles from the development mode.

boolean

Example Request

GET https://graph.facebook.com/{page-id}/instant_articles?access_token={access-token}

Example Response

{
  "data": [
    {
      "id": "1234",
      "html_source": "<!doctype html>...",
      "canonical_url": "http://..."
    },
    {
      "id": "1235",
      "html_source": "<!doctype html>...",
      "canonical_url": "http://..."
    },
    {
      "id": "1236",
      "html_source": "<!doctype html>...",
      "canonical_url": "http://..."
    },
    ...
  },
  "paging": {
    "cursors": {
      "before": "1a2B3c4D5e6F7g8H9i0J",
      "after": "1A2b3C4d5E6f7G8h9I0j"
    },
    "next": "https://graph.facebook.com/{page-id}/instant_articles?access_token=...&amp;pretty=1&amp;limit=25&amp;after=1A2b3C4d5E6f7G8h9I0j"
  }
}

Look Up Article ID

To lookup the article ID of an Instant Article based on its canonical URL, issue a GET request to:

https://graph.facebook.com?id={canonical-url}&amp;fields=instant_article

Fields

Name Description Type

access_token [required]

A valid page access token.

string

id [required]

The canonical URL of the Instant Article.

url

fields [required]

Used to specify the source of the article: production or development. For the version of the article in production, the value of this parameter must include instant_article. For the version of the article in development, this parameter must include development_instant_article.

string

Example Request

GET https://graph.facebook.com?id={canonical-url}&amp;fields=instant_article&amp;access_token={access-token}

Example Response

{
  "instant_article": {
    "id": "1234"
  },
  "id": "http://www.mysite.com/myarticle"
}

Get Article Details

To get the details for an individual Instant Article based on its article ID, issue a GET request to:

https://graph.facebook.com/{article-id}

Fields

Name Description Type

access_token [required]

A valid page access token.

string

Example Request

GET https://graph.facebook.com/{article-id}?access_token={access-token}

Example Response

{
  "id": "1234",
  "html_source": "<!doctype html>...",
  "canonical_url": "http://..."
}

Create a New Article

To create a new Instant Article, issue a POST request to:

POST /{page-id}/instant_articles

Fields

Name Description Type

access_token [required]

A valid page access token.

string

html_source [required]

Full HTML markup of article.

string

published

Specifies whether this article should be taken live or not. This field is optional and defaults to false.

boolean

development_mode

Specifies if this article should be published in development mode or not. This field is optional and defaults to false.

boolean

Example Request

curl \
    -F 'access_token={access-token}' \
    -F 'html_source=<!doctype html>...' \
    -F 'published=true' \
    -F 'development_mode=false' \
    https://graph.facebook.com/{page-id}/instant_articles

Example Response

{
  "id": {import-status-id}
}

Once article has been posted through this endpoint, Facebook will begin processing the article's markup and importing the media assets contained with the article content asynchronously. This endpoint returns an import status ID, which can be used to determine the when the article has been successfully imported or if any errors occurred during the import process.

The endpoint for monitoring the import status of an article is outlined below in this document.

Update an Existing Article

Updates to existing Instant Articles follow the same approach used to creating a new Instant Article. If the article being posted contains the same canonical URL if an existing Instant Article, the markup of the existing article will be updated with the new markup included in the POST.

Delete an Article

To delete an Instant Article, issue a DELETE request to:

DELETE /{article-id}

Fields

Name Description Type

access_token [required]

A valid page access token.

string

Example Request

DELETE https://graph.facebook.com/{article-id}?access_token={access-token}

Example Response

{
  "success": true
}

Get Article Import Status

To get the latest import status for an Instant Article, issue a GET request to:

https://graph.facebook.com/{import-status-id}

Fields

Name Description Type

access_token [required]

A valid page access token.

string

fields

A comma-delimited list of additional fields to be returned in the response:

  • errors: an array of any errors identified with this article
  • html_source: full HTML markup of this article
  • instant_article: resulting Instant Article object, if successful
  • status: specifies state of article import

string

Example Request

GET https://graph.facebook.com/{import-status-id}?access_token={access-token}

Example Request: Additional Fields

GET https://graph.facebook.com/{import-status-id}?fields=errors,html_source,instant_article,status&access_token={access-token}

Example Response: Success

{
  "id": "1234",
  "status": "SUCCESS"
}

Example Response: Success With Additional Fields

{
  "html_source": "<!doctype html>...",
  "instant_article": {
    "id": "1234",
    "html_source": "<!doctype html>...",
    "canonical_url": "http://..."
  },
  "status": "SUCCESS",
  "id": "5678"
}

Example Response: Errors

{
  "id": "1234",
  "status": "IN_PROGRESS",
  "errors": [
    {
      "level": "ERROR",
      "message": "Could not find the Canonical URL within the document: Specify a valid canonical URL using <link rel=\"canonical\" and href=\"canonical url\">"
    }
  ]
}