Flockler API v1 Documentation

The Flockler API provides programmatic access for you to consume all the content you have created with your Flockler Newsroom. With Flockler API you can continue creating content in Newsroom while being convinced that through Flockler API all your content is available whatever you need to do with it in the future. API content is divided in familiar sections and categories and is available in JSON.

This page will introduce you to the basic principles of the Flockler API and specific endpoint description pages will teach you more about the content that is available from this API.

The base endpoint for the API is https://api.flockler.com/v1/

Authentication

🔑 This is a public API so you don't need a key/token to access your data.

Information about an optional API key

If you want to hide your site, you can request API key from us (support). Enabling API key will disable API for your site unless the key is sent with every request

API key

Key should be used only between servers and not shown to enduser. Key must be included in every request as parameter or header.

Parameter: api_key

Example: https://...?api_key=d9ebff02cbc1cfb4122db7ce0f337c78


Header: Authorization

Example: Authorization: FL-API-KEY d9ebff02cbc1cfb4122db7ce0f337c78

Endpoints

Articles

Sections

Sites

Request

Parameters

Below are listed some of the more commonly used request parameters.


sideloading refactors the data and eliminates duplication. For example, if you requested for articles, you will get the articles' sections data in a separate block in the end of the response. Sideloading is true by default but you can switch to embedded mode by defining it to false

Example: ?sideloading=false


fields is useful when you know exactly what fields of the data you need. That decreases the payload of the response and makes it easier to handle when all the excessive stuff has been already cut off.

Example: ?fields=id,title,body,full_url


tags return articles including one or more of the listed tags

Example: ?tags=product_a,product_b

tag_filter_type should be used if you want to return articles that match ALL of the listed tags

Example: ?tags=product_a,product_b&tag_filter_type=all


count defines the number of items you get as a response. Count default for articles is 20 items per page but you can increase or decrease it as you like by defining the count-parameter in your request.

Example: ?count=40


max_id is for pagination. With max_id you can define the last processed item and request only items with a lower id (=older items). That way you can efficiently go through long lists of items and process them in smaller pieces.

Example: ?max_id=741275


since_id is for polling purposes. It defines the last id that has been processed and returns only items that have become available after that specific item. That way you can efficiently poll new items and exclude all the already processed ones from the responses.

Example: ?since_id=762681

Response

Currently Flockler API only responds via JSON. Most responses consist of a meta, pagination and data node. Sometimes you might also get some sideloadable data nodes. Below is an example of a typical response with the typical meta, pagination and data nodes:

{
  "meta": {
    "total_count": 214,
    "count": 20
  },
  "pagination": {
    "refresh": "https://api.flockler.com/v1/sites/609/sections/828/articles?since_id=239992",
    "base": "https://api.flockler.com/v1/sites/609/sections/828/articles?",
    "older": "https://api.flockler.com/v1/sites/609/sections/828/articles?max_id=239992"
  },
  "articles": []
}

Here we have a meta node, pagination node and lastly articles node, which in this case, is the data node.

Meta

total_count total number of available items.

count shows how many items are included in this response.

Pagination

base URL for fetching the basic resource.

refresh URL for fetching items that have been added after your last request. Good for polling for new items.

older URL for fetching next set of items (=older items). Is null when there are no more older items.

Data
The data is presented using an unique key for the request. If you requested for articles, the key will be called “articles”, if you requested a single article, the key will be called “article”. This is “the meat” of the response. It may be a list or dictionary, but either way this is where you'll find the data you requested.

Sideloading

Along with the actual data, you may receive some sideloadable data. For example, if you requested for articles, you will get the articles' sections data in a separate block in the end of the response.

Flockler API sideloads all the sections by default. You may change the default with the "?sideloading=false" parameter.

Below is an example of a response with sideloaded section data:

"articles": [
  {
    "article_url": "3-examples-of-brands-creating-content-on-a-budget",
    "author_ids": [
      1422
    ],
    "body": "<p><p>Some of the best examples of content ...",
    "section_id": 3908,
  }
],
"sections": [
  {
    "id": 3908,
    "name": "Blog",
  }
]

HTTP Status Codes

200 OK Successful request.

400 Bad Request Most likely a missing or invalid parameter(s).

404 Not Found The requested item was not found.

500 Internal Server Error Something went wrong on our end.