Content API v2
Build a custom experience from scratch by using our API
Getting started#
The Content API is only available for customers on our Premium and Agency plans.
Before starting to build a solution using our API, we highly recommend utilizing our pre-designed embed layouts to kickstart your project promptly. These layouts are readily available and can be easily customized using CSS. As an added benefit, we are responsible for keeping these layouts updated to support various content types utilized by different social channels.
If you are looking to build a custom solution from scratch, you can use our Content API to fetch content that you've got collected to Flockler. The API does not provide any content that is hidden or waiting for moderation but only content that you've set to published state.
Authentication#
Even though the content provided by our API is considered to be public content, we require that you create an API key in your Flockler settings. This is so that we have a better understanding on who's using our API and a way to notify API users about updates and breaking changes.
Authenticating requests#
There are to ways to authenticate your requests:
- Use a HTTP header:
X-FL-API-Key: c1348c8843eca56ba620025acd31af81c8778ca0
- Use a query parameter:
?api_key=c1348c8843eca56ba620025acd31af81c8778ca0
Endpoints#
This is the base URL for all API requests where the :siteUuid
is the UUID of your Flockler:https://api.flockler.app/v2/:siteUuid
Posts#
Request parameters#
Parameter | Description |
---|---|
count integer | Max number of items returned in the response. Value between 1–100. ?count=20 |
filterByChannels[] facebook flickr flockler google_review instagram link linkedin pinterest review rss tiktok twitter youtube | Filter posts by channels. ?filterByChannels[]=twitter&filterByChannels[]=instagram |
filterBySectionIds[] integer | List of section IDs to limit the results to. ?filterBySectionIds[]=1&filterBySectionIds[]=2 |
filterByTags[] string | List of tags to limit the results to. ?filterByTags[]=foo&filterByTags[]=bar |
tagFilterType all any | Whether returned posts should have all of the tags mentioned or any of them. The default value is "all". ?tagFilterType=any |
order random | Used to return posts in a random order. ?order=random |
Examples#
const SITE_UUID = '01h3cqe975srrvf1zwp96xs29x';
const API_KEY = 'c1348c8843eca56ba620025acd31af81c8778ca0';
const response = await fetch(
`https://api.flockler.app/v2/${SITE_UUID}/posts`,
{
headers: {
'X-FL-API-Key': API_KEY
}
}
);
const data = await response.json();
{
"meta": {
"statsApiEndpoint": "https://stats-api.flockler.app/v1/stats/01h3cqe975srrvf1zwp96xs29x?campaignId=…"
},
"pagination": {
"newer": "https://api.flockler.app/v2/01h3cqe975srrvf1zwp96xs29x/posts?count=12&newerThanCursor=1234567890",
"older": null
},
"posts": [
{
"attachments": [],
"flocklerId": 1234567890,
"from": {
"name": "Flockler",
"username": "getflockler",
"profileUrl": "https://example.org/getflockler",
"profileImageUrl": "https://example.org/getflockler.jpg"
},
"channel": "flockler",
"ctaLink": null,
"images": [
{
"altText": null,
"url": "https://example.org/example.jpg"
}
],
"postType": "image",
"publishedAt": "2025-05-22T11:51:41.240Z",
"sourceId": "2dxsk8fx",
"sourceUrl": "https://example.org/2dxsk8fx",
"tags": [
"HashtagA",
"HashtagB",
],
"textPlain": "Example text
#HashtagA #HashtagB",
"textRich": "<p>Example text</p><p>#HashtagA #HashtagB</p>",
"title": null,
"videos": [],
"pinnedIndex": null,
}
]
}
Typescript definition for the posts#
type FlocklerPost = {
attachments: PostAttachment[];
flocklerId: number;
from: {
name: string | null;
username: string | null;
profileUrl: string | null;
profileImageUrl: string | null;
};
channel:
| 'facebook'
| 'flickr'
| 'flockler'
| 'google_review'
| 'instagram'
| 'link'
| 'linkedin'
| 'pinterest'
| 'review'
| 'rss'
| 'tiktok'
| 'twitter'
| 'vimeo'
| 'youtube';
ctaLink: {
url: string;
title: string | null;
} | null;
images: {
altText: string | null;
url: string;
}[];
pinnedIndex: number | null;
postType: string;
publishedAt: string;
sourceId: string | null;
sourceUrl: string;
tags: string[];
textRich: string | null;
textPlain: string | null;
title: string | null;
videos: {
type: 'file' | 'iframe' | 'link';
url: string;
}[];
};
type FacebookReviewAttachment = {
pageName: string;
pageUrl: string;
recommendationType: 'positive' | 'negative';
type: 'review';
};
type FlocklerRatingAttachment = {
rating: number;
type: 'rating';
};
interface InstagramStoryAttachment {
type: 'storyItem';
publishedAt: string;
videoUrl: string;
imageUrl: string;
};
type LinkAttachment = {
type: 'link';
snippet: string;
title: string;
url: string;
};
type PostAttachment = FacebookReviewAttachment | FlocklerRatingAttachment | InstagramStoryAttachment | LinkAttachment;
Feeds#
The Feeds API allows you to manage your social media feeds and pull posts automatically to make them available in a section. You can then use the posts endpoint (described above) to retrieve the content.
List Feeds#
Retrieve a list of all active feeds in your Flockler account.
Request parameters#
Parameter | Description |
---|---|
order asc desc | Sort feeds by creation date. Default value is "desc". ?order=asc |
services[] twitter_v2 instagram_graph_api instagram_basic_display facebook pinterest youtube rss tiktok google_review linkedin bluesky | Filter feeds by service type. You can specify multiple services. ?services[]=twitter_v2&services[]=instagram_graph_api |
const SITE_UUID = '01h3cqe975srrvf1zwp96xs29x';
const API_KEY = 'c1348c8843eca56ba620025acd31af81c8778ca0';
const response = await fetch(
`https://api.flockler.app/v2/${SITE_UUID}/feeds?order=desc&services[]=twitter_v2&services[]=instagram_graph_api`,
{
headers: {
'X-FL-API-Key': API_KEY
}
}
);
const data = await response.json();
{
"result": {
"success": true,
"data": {
"feeds": [
{
"feed": {
"id": 123,
"uuid": "196ae3487ee06b38b2b911f722ce3d0c",
"name": "BBC News",
"service": "rss",
"created_at": "2025-05-08T04:43:21Z",
"status": {
"is_healthy": true,
"error_message": ""
},
"configuration": {
"moderation": "auto_publish",
"enabled": true
}
},
"section": {
"id": 456,
"uuid": "196ae335a5d0871ceaa3db7eac6a4007",
"name": "Posts"
}
},
{
"feed": {
"id": 124,
"uuid": "196ae35a41a0102a883740a2ce44a041",
"name": "",
"service": "instagram_graph_api",
"created_at": "2025-05-08T04:44:33Z",
"status": {
"is_healthy": true,
"error_message": ""
},
"configuration": {
"moderation": "auto_publish",
"enabled": true
}
},
"section": {
"id": 456,
"uuid": "196ae335a5d0871ceaa3db7eac6a4007",
"name": "Posts"
}
}
]
}
}
}
Typescript definition for the feeds list#
type FeedService =
| 'twitter_v2'
| 'instagram_graph_api'
| 'instagram_basic_display'
| 'facebook'
| 'pinterest'
| 'youtube'
| 'rss'
| 'tiktok'
| 'google_review'
| 'linkedin'
| 'bluesky';
type FeedStatus = {
is_healthy: boolean;
error_message: string;
};
type FeedConfiguration = {
moderation: 'saved_to_inbox' | 'ai_moderation' | 'auto_publish';
enabled: boolean;
};
type Feed = {
id: number;
uuid: string;
name: string;
service: FeedService;
created_at: string;
status: FeedStatus;
configuration: FeedConfiguration;
};
type Section = {
id: number;
uuid: string;
name: string;
};
type FeedWithSection = {
feed: Feed;
section: Section;
};
type ListFeedsResponse = {
result: {
success: boolean;
data: {
feeds: FeedWithSection[];
};
};
};
Create Feed#
Request parameters#
Parameter | Description |
---|---|
feed object | An object containing details about the feed to create. |
feed[name] string | What to name the feed. This should be unique, as it's what you'll see in the Flockler dashboard on your list of active feeds. |
feed[feed_type] rss twitter_v2 | Which type of social media feed to create; i.e. which service to pull content from. Right now, limited to rss and twitter feed types. |
feed[moderation_type] saved_to_inbox ai_moderation auto_publish | Defines how the feed content is moderated. Options are saved_to_inbox, ai_moderation, or auto_publish. |
feed[feed_attributes] object | Contains additional parameters specific to the feed type, such as the URL for RSS feeds. |
section object | An object containing details about the section to create or reference. |
section[id] number | The ID of the section where the feed will be added. If you want to use an existing section, provide only the ID. |
section[uuid] string | The UUID of the section where the feed will be added. If you want to use an existing section, provide only the UUID. |
section[name] string | The name of the section to create a new section. Use this only if you want to create a new section instead of using an existing one. |
Examples#
RSS Feed Example#
Feed Attribute | Description |
---|---|
url | The URL of the RSS feed to pull content from. |
const SITE_UUID = '01h3cqe975srrvf1zwp96xs29x';
const API_KEY = 'c1348c8843eca56ba620025acd31af81c8778ca0';
const postData = {
feed: {
name: "BBC",
feed_type: "rss",
moderation_type: "auto_publish",
feed_attributes: {
url: "https://feeds.bbci.co.uk/news/world/rss.xml"
}
},
section: {
uuid: "uuid"
}
};
const response = await fetch(
`https://api.flockler.app/v2/${SITE_UUID}/feeds`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-FL-API-Key': API_KEY
},
body: JSON.stringify(postData)
}
);
const data = await response.json();
{
"result": {
"success": true,
"data": {
"feed": {
"id": 123,
"uuid": "uuid",
"name": "BBC",
"service": "rss"
},
"section": {
"id": 456,
"uuid": "uuid",
"name": "wow"
}
}
}
}
Typescript definition for this request#
type FeedAttributes = {
url: string;
// ...other params for other feed types...
};
type Feed = {
id: number;
name: string;
feed_type: 'rss'
moderation_type: 'saved_to_inbox' | 'ai_moderation' | 'auto_publish';
feed_attributes: FeedAttributes;
};
type Section = {
id: number;
uuid: string;
};
type CreateFeedRequest = {
feed: Feed;
section: Section;
};
Twitter Feed Example#
Feed Attribute | Description |
---|---|
author | The username of the Twitter account to pull tweets from. |
hashtag_or_keyword | Hashtags or keywords to filter tweets. |
include_replies | Boolean flag to include replies in the feed. |
videos_required | Boolean flag to include only tweets with videos. |
pictures_required | Boolean flag to include only tweets with pictures. |
const SITE_UUID = '01h3cqe975srrvf1zwp96xs29x';
const API_KEY = 'c1348c8843eca56ba620025acd31af81c8778ca0';
const postData = {
feed: {
name: "Twitter feed",
feed_type: "twitter_v2",
moderation_type: "auto_publish",
feed_attributes: {
author: "author",
hashtag_or_keyword: "#hashtag",
include_replies: true,
videos_required: true,
pictures_required: true
}
},
section: {
uuid: "uuid"
}
};
const response = await fetch(
`https://api.flockler.app/v2/${SITE_UUID}/feeds`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-FL-API-Key': API_KEY
},
body: JSON.stringify(postData)
}
);
const data = await response.json();
{
"result": {
"success": true,
"data": {
"feed": {
"id": 124,
"uuid": "uuid",
"name": "twitter_v2",
"service": "twitter_v2"
},
"section": {
"id": 456,
"uuid": "uuid",
"name": "test"
}
}
}
}
Typescript definition for this request#
type FeedAttributes = {
url: string;
author?: string;
hashtag_or_keyword?: string;
include_replies?: boolean;
videos_required?: boolean;
pictures_required?: boolean;
};
type Feed = {
name: string;
feed_type: 'rss'
moderation_type: 'saved_to_inbox' | 'ai_moderation' | 'auto_publish';
feed_attributes: FeedAttributes;
};
type Section = {
uuid: string;
};
type CreateFeedRequest = {
feed: Feed;
section: Section;
};
Pinterest Feed Example#
Feed Attribute | Description |
---|---|
url | Add Pinterest user or board URL, e.g., https://www.pinterest.com/user/board . |
const SITE_UUID = '01h3cqe975srrvf1zwp96xs29x';
const API_KEY = 'c1348c8843eca56ba620025acd31af81c8778ca0';
const postData = {
feed: {
name: "Pinterest feed",
feed_type: "pinterest",
moderation_type: "auto_publish",
feed_attributes: {
url: "https://www.pinterest.com/user/board"
}
},
section: {
uuid: "uuid"
}
};
const response = await fetch(
`https://api.flockler.app/v2/${SITE_UUID}/feeds`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-FL-API-Key': API_KEY
},
body: JSON.stringify(postData)
}
);
const data = await response.json();
{
"result": {
"success": true,
"data": {
"feed": {
"id": 125,
"uuid": "uuid",
"name": "Pinterest feed",
"service": "pinterest"
},
"section": {
"id": 456,
"uuid": "uuid",
"name": "example_section"
}
}
}
}