Content API v2

Build a custom experience from scratch by using our API

Looking for the API v1 documentation? View legacy documentation here →

Table of contents

Getting started#

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#

request

get/posts

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();

response

get/posts

{
  "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": "2024-10-24T15:04:52.376Z",
      "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;