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.Â
- Host –
https://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 Settings > 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 create an 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 the following:
<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 service responds 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. You should 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 and 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 withpagesize=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 andmodified_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 updates the article accordingly 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 service can also size the images to fit your design specs. Include the fitting height and width parameters to not worry about resizing images client-side. If you need to change the height and the width, Optimizely has you covered. The image does not get skewed or lose the integrity of its aspect ratio. Instead, the service crops the image or letterbox it to ensure it looks like the original.Â
You can attach the following parameters to the end of the URL:
height
– Change the height of the image.width
– Change the width of the image.center_height
– Define the center height position for cropping.center_width
– Define the center width position for cropping.
When your system parses the feed, you can programmatically add the URLs:Â
large
–https://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
Updated 2 months ago