Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Feed API v2

This topic describes Version 2 of the Feed API and the use of feeds and parameters.

The Feed API V2 is the way you retrieve article content from system feeds. It has examples of how to interact with the feed, and how to parse published URLs back for uninterrupted posting of social posts that promote article content. 

  • Hosthttps://api.optimizely.com
  • Path/v2/feed/{id} 

Your Implementation Consultant will give you the ID of the feed or feeds you will interact with, during onboarding. These may also be found in the settings menu, under Website, CMS & Feeds, and are accessible to Administrator accounts only. 

Call the feed

The Optimizely Content Marketing Platform (CMP) lets you create an arbitrary amount of feeds you can retrieve through HTTPS GET requests. You can publish articles to the top of one or more of these feeds using CMP workflows. Then, by calling your feed endpoints regularly, you can check for new content, and where it exists, create a new article in your CMS database by mapping fields (article headline, body, author, source, metadata, and so on) to their respective elements in your CMS. You are given your feed in a structure similar to below

<https://api.optimizely.com/v2/feed/0569f69ed223720c699936eddbc7tyxP8d3>

By default, accessing the URL returns up to 200 records in Atom format. To work with the feed, you can use the provided parameter options.

Feed parameters

You can use the following parameters when you call the feed.

Parameter

Type

Values

Default

Explanation

Format

string

json,

atom

atom

The Feed API supports both Atom and JSON. Based on how you plan to integrate, choose your preferred format.

pagesize

integer

 

200

This parameter tells our API how many pieces of content you want to retrieve

offset

integer

 

0

An offset can be applied in order to call articles in batches, when used in conjunction with pagesize and determines where you want to start. To retrieve the second page of content, increment the offset by the page size.

sort_by

string

Position,

modified_at

Position (no value passed) or modified_at (other value passed) 

Sorting of articles within the feed

Update and delete content

  • You should set a batch task that paginate through full feeds. 
  • You should use a Deleted Feed so the user can move an article to the Deleted Feed in the Optimizely Platform. Your integration can then be set up to recognize when an article is moved and trigger the delete action when the feed is called from your CMS.
  • You can also delete the content in the CMS, but you should not let inconsistencies develop between the feed and the CMS to avoid unexpected behavior. 

Sample API request (JSON)

  • cURL – https://api.optimizely.com/v2/feed/0569f69ed223720c699936eddbc7tyxP8d3

    Sample output (JSON)

    {
    "title": "NM Feed Sample",
    "modified_at": "2025-07-24T12:01:44Z",
    "entries": [
     {
       "content": {
         "guid": "151a3f3ccda517geab6db0aF5f9be72d9",
         "group_id": "151a3f3ccdaxe751Bu91eab6db0ad4f9be72d9",
         "meta_title": "Feed Article Sample",
         "meta_description": "Lorem ipsum dolor sit amet, consectetur adipiscing...",
         "meta_url": "/",
         "meta_keywords": [],
         "images": [
           {
             "caption": "mango.png",
             "attribution_text": "",
             "description": "",
             "height": "512",
             "width": "369",
             "thumbnail": "https://img.optimizely.com/Zz0yNWU2MzMzNWNkfgYTUxMWV5hOD7QzYzBhMDY3NTYwZjM5Nw==?width=75&height=75",
             "url": "https://img.optimizely.com/Zz0yNWU2MzMzNgfWNkYTUxMWV5hOD7QzYzBhMDY3NTYwZjM5Nw==/mango.png",
             "mimetype": "image/png",
             "source": {
               "name": "Martin's Test Group"
             }
           }
         ],
         "videos": [],
         "authors": null,
         "topics": [],
         "title": "Feed Article Sample",
         "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing ...</p>\n<p>...sed do eiusmod tempor incididunt...</p>\n<img src=\"https://pixel.optimizely.com/px.gif?key=YXJ0aWNsZT0xNTFhM2YzY2NkYTUxMWVhYjZkYjBhZDRmOWJlNzJkOQ==\" alt=\"\" height=\"1\" width=\"1\" class=\"nc_pixel\"/>",
         "created_at": "2025-07-24T11:59:10Z",
         "modified_at": "2025-07-24T12:01:43Z",
         "published_at": "2025-07-24T12:01:43Z",
         "link": null,
         "pixel_key": "YXJ0aWNsZThg0xNTFhM2YzY2NkYTUYZxMWVhYjZkYjBhZDRmOWJlNzJkOQ==",
         "customer_canonical_link": null,
         "source": {
           "guid": "5bc5e258e9cb54e3f865b6g2fa98dc4324",
           "name": "Instance"
         },
         "lang_code": "en",
         "custom_fields": [
           {
             "label": "Ad Date",
             "values": [
               "2025-07-24T11:00:00.000Z"
             ]
           },
         "content_pillar": [
           {
             "label": "BLOG:Social Impact"
           }
         ],
         "content_format": [],
         "custom_label_set": [
           {
             "label": "Short",
             "type": "Article Length"
           }
         ],
         "target_audience": [
           {
             "label": "Parents"
           }
         ],
         "journey_stage": [
           {
             "label": "Top of the Funnel"
           }
         ]
       }
     }
    ]
    }
    

Sample API response (JSON) with sort parameter 

  • cURL – https://api.optimizely.com/v2/feed/f29434f4ad757c32b966019d956c0e4c?format=json&sort_by=modified_at

    Sample output (JSON)

    Top 3 results, other fields stripped (sort by = modified_at)

    {
     "title": "Analytics Related Picks",
     "modified_at": "2025-11-06T09:48:36Z",
     "entries": [
     {
          "content": {
            "created_at": "2025-01-24T18:56:05Z",
            "modified_at": "2025-11-06T09:48:36Z"
          },
          "created_at": "2013-12-09T15:47:29Z",
          "modified_at": "2025-11-06T09:12:57Z"
     },
        "created_at": "2025-02-10T14:00:17Z",
        "modified_at": "2025-11-06T08:37:55Z"
     ]
    }
    
  • cURL – https://api.optimizely.com/v2/feed/f29434f4ad757c32b966019d956c0e4c?format=json&sort_by=position

    Sample output (JSON)

    Top 3 results, all other fields stripped (sort by = position)

    {
     "title": "Analytics Related Picks",
     "modified_at": "2025-11-06T09:48:36Z",
     "entries": [
     {
          "content": {
            "created_at": "2025-08-21T15:44:22Z",
            "modified_at": "2025-08-21T15:56:03Z"
          },
          "created_at": "2025-04-17T19:56:41Z",
          "modified_at": "2025-11-05T09:00:28Z"
        },
        "created_at": "2025-02-10T14:00:17Z",
        "modified_at": "2025-11-06T08:37:55Z"
      ]
    }
    

Invalid feed GUID

With a feed GUID that does not exist, the server will respond with HTTPS status code.404

  • cURL – https://api.optimizely.com/v2/feed/

  • HTTPS/1.1 404 NOT FOUND

  • Content-Length: 121

  • X-Request-ID:c384254ec33011e58a070242ac110002

    {
      "error": {
        "code": "404",
        "message": "Collection with guid 0569f69ed223720c699936eddbc5b123 not found"
      }
    }
    

Integrate with a third-party CMS

By attaching custom fields or labels to your CMP workflow, you can send additional structured data to your CMS. The CMP can be populated with a dropdown, radio button, check box, free text, or date interface and retrieved from the custom_fields node in the feed. A best practice is to create custom fields for meta tags such as Meta Title and Meta Descriptions to enhance on-page SEO. Ensure that the custom fields are mapped onto the CMS during ingestion accurately.

Ensuring that the content delivered from the CMP is consistent with the website’s style.

Licensed content and, by default, custom content are delivered in purely semantic HTML. This means that while you still can take advantage of h tags (for example), they are interpreted by your website’s global style. The text editor allows inline styles through raw HTML editing in cases where needed, but the standard interface is designed to prioritize using semantic HTML only.

Update and delete content

  • Using the fields parameter, you can retrieve only the GUID and modified_at elements of the feed. By calling the feeds with pagesize=999 and these fields only to minimize response size, you can determine if an article was deleted (GUID of an existing article is no longer present) or updated (GUID matches and modified_at was updated since the last poll time).
  • You should set a batch task to paginate through full feeds that an editorial user can instigate. 
  • You should use a Deleted Feed so the user can move an article to the Deleted Feed in the Optimizely Platform. Your integration can then be set up to recognize when an article is moved and trigger the delete action when the feed is called from your CMS.
  • You can also delete the content in the CMS, but you should not allow inconsistencies to develop between the feed and the CMS to avoid unexpected behavior.

Feed and social publishing

To post article content to a social channel, you need to have the canonical link of that article in the content body. Clients who rely on feed publishing must be able to publish to a feed and any social channel from the CMP within a single task. For the social post to be sent without error, the published URL must be sent back to the platform once published.

This API that receives the tracking pixel and the canonical link of the article, finds out which article it points to and accordingly updates the article with the canonical link to let a social post be sent.

After the article is updated, the CMP is notified of this change, and if there are pending social publishes dependent on the article post, it proceeds with the publishing at that point or by the user-determined schedule.

A CMS-specific plugin calls the API service with the required data whenever an article is published in the hub. Feed clients need to handle this in their integration app, as below

Update canonical link endpoint

The following API endpoint registers the article URL to Optimizely assets.

  • GET https://js-snippets.optimizely.com/customer_canonical_link

Property

Format

Description

Example

canonical_link

String

The URL encoded link to the article page

https://cmc-wp-test.optimizely.com/index.php/2017/11/22/puretech-health-to-present-at-piper-jaffray-2017-healthcare-conference/

tracking_pixel_key

String

This is the Optimizely unique ID for the article. Usually found in the feed through the pixel_key property.

YXJ0aWNsZT0xNjcxOGNiNmZlZWEyNTM2OWZmMzZlZDBmZmJiZTJkOA==

Dynamically resize images from the Optimizely CMP API

The Optimizely CMP API passes raw images that can be rendered onto your site, iOS app, newsletter, or wherever you display the content. 

Optimizely's server can also size the images to fit your design specs. You won't worry about resizing images client-side if you include the fitting height and width parameters. If you need to change the height and the width, Optimizely has you covered. The image will not get skewed or lose the integrity of its aspect ratio. Instead, the server will crop the image or letterbox it to ensure it looks like the original. 

The following parameters can be attached to the end of the URL:

  • height – Change the height of the image
  • width – Change the width of the image
  • center\_height – Define center height position for cropping
  • center\_width – Define center width position for cropping

When your system parses the feed, you can programmatically add the URLs: 

  • largehttps://images-cdn.optimizely.com/Zz01ZTIzZmM5OGNkYzg4OTdkMjRiZDc1ZGIwODQ3MDFhMw==

You can take that image URL and append it with this: ?width=600&height=600

For example, the following image is set to a width and height of 500:

https://images-cdn.optimizely.com/Zz01ZTIzZmM5OGNkYzg4OTdkMjRiZDc1ZGIwODQ3MDFhMw==?width=500&height=500