How to retrieve posts using Flowbox's API - v2

This guide will walk you through the process of retrieving posts from a specific Flow using Flowbox's API.

Prerequisites

Before you start, ensure you have the following:

API key: Your unique API authentication key. If you don't have it yet, please contact your CSM and they'll provide it to you.

Flow key: The unique key identifying the Flow from which you want to retrieve posts. The easiest way to find this is copying it from the "Copy Flow Key" option in the three dot menu, in the Flows section in Flowbox:

API Endpoint

To retrieve posts from a specific Flow, you need to send a GET request to the following endpoint:

https://external-api.getflowbox.com/v2/flow/{flowKey}/posts

You can find more information and make test calls in our Swaggerhub page.

Required Parameters

Parameter	Type	Location	Description
`api-key`	string	header	Your API authentication key. Must be included in every request.
`flowKey`	string	path	Key of the Flow to retrieve posts from.
`type`	string	query	Type of the Flow. Must be one of: `"static"`, `"product"`, `"tag"`. Use`"product"`when filtering by `productIds`, and`"tag"`when filtering by `tags`. The Flow type can be verified in the Flows panel.

Optional Parameters

Parameter	Type	Location	Description
`locale`	string	query	Locale of the products to be returned. Must match the locale of one of your catalogs. Use lowercase format, e.g. `"en-gb"`.
`postsPerPage`	integer	query	Number of posts to retrieve per request. Defaults to `30` (maximum).
`productIds`*	string	query	Comma-separated list of product IDs to filter posts by. When provided, returns matching posts from all Flows in the account. Required when `type=product` (unless `productCategories` is provided). Cannot be used when `type=tag` or `type=static`.
`productCategories` *	string	query	Comma-separated list of product categories to filter posts by. Required when `type=product` (unless `productIds` is provided). Cannot be used when `type=tag` or `type=static`.
`tags`*	string	query	Comma-separated list of tags to filter posts by. Required when `type=tag`. Cannot be used when `type=product` or `type=static`.
`operator`	string	query	Logical operator for tag filtering. `"AND"` returns posts matching all specified tags. `"OR"` returns posts matching any specified tag.
`similarProduct`	boolean	query	Filters by product tagging type. `true` : posts where the product is tagged as similar. `false` : posts where the product is tagged as exact. Omitted : returns all posts (both exact and similar). Premium feature : contact your CSM for access.
`hotspotsEnabled`	boolean	query	Whether to include hotspot data in the response. Defaults to `false`.
`inclusive_feeds`	string	query	Comma-separated list of feed keys to include. `type=tag` and`type=product` calls will only retrieve content from these feeds. Cannot overlap with `exclusive_feeds`.
`exclusive_feeds`	string	query	Comma-separated list of feed keys to exclude. `type=tag` and `type=product` calls will not retrieve content from these feeds. Cannot overlap with `inclusive_feeds`.
`fields`	string	query	Comma-separated list of additional post fields to include beyond the default set. Accepted values: `userRealName`, `socialCommerceUrl`, `socialCommerceLabel`, `socialCommerceTagline`, `socialCommerceEnabled`, `altText`.
`cursor`	string	query	Cursor string from the previous response, used for pagination. Pass the full `cursor` object returned by the prior request.

*Required depending on type provided.

Example API Request

Here is an example request with both required and optional parameters:

curl -X 'GET' \  
'https://external-api.getflowbox.com/v2/flow/INSERT_FLOW_KEY_HERE/posts?type=static&locale=en-eu&postsPerPage=5' \   
-H 'accept: application/json' \   
-H 'api-key: INSERT_API_KEY_HERE'

Response:

The response will be a JSON containing the posts retrieved based on the parameters you provided. Each post will contain data such as product information, associated tags, and other relevant metadata.

JSON returned:

Root

Field	Type	Description
`status`	string	Request status. One of:`"success"`,`"error"`.
`data.posts`	array	List of post objects. See Post table below.
`data.cursor`	object	Cursor for fetching the next page. Pass to the`cursor` query parameter to paginate. See Cursor table below.

Post (object):

Field	Type	Description
`postKey`	string	Unique identifier for the post.
`flowKey`	string	Key of the Flow the post belongs to.
`postPermalink`	string	URL to the post in the Flowbox app.
`sourceName`	string	Source platform of the post, e.g. `"instagram"`, `"facebook"`, `"custom"` (uploaded media).
`media`	array	List of media objects attached to the post. See Media object table below.
`publishedAt`	string	ISO 8601 timestamp of when the post was published, e.g. `"2026-02-26T10:27:36.131667+0000"`.
`userPermalink`	string	URL to the author's profile on the source platform. `null` for custom posts.
`thumbnail.url`	string	URL of the primary thumbnail (`cdn.flbx.io`).
`thumbnail.fallbackUrl`	string	Direct S3 URL used if the primary `url` is unavailable.
`text`	string	Caption or body text of the post. `null` if no caption was provided.
`userName`	string	Handle or username of the post author.
`productKeys`	string	JSON-encoded array of exact-matched product keys tagged on the post. Parse before use: `JSON.parse(post.productKeys)`.
`similarProductKeys`	array	List of similar-matched product keys tagged on the post.
`comments`	integer	Number of comments on the post.
`likes`	integer	Number of likes on the post.
`interactions`	integer	Total number of interactions tracked by Flowbox.
`userRealName`	string	Author's full name. Only present when `fields=userRealName` is requested.
`socialCommerceUrl`	string	CTA URL for social commerce. Only present when `fields=socialCommerceUrl` is requested.
`socialCommerceLabel`	string	CTA button label. Only present when `fields=socialCommerceLabel` is requested.
`socialCommerceTagline`	string	Tagline displayed alongside the CTA. Only present when `fields=socialCommerceTagline` is requested.
`socialCommerceEnabled`	boolean	Whether social commerce is enabled for this post. Only present when `fields=socialCommerceEnabled` is requested.
`altText`	object	Alt text for the post's media items, keyed by media index (string). Each value is a locale map, e.g. `{"0": {"en": "A red bicycle."}}`. Single-image posts contain only key `"0"`; carousels include additional keys `"1"`, `"2"`, etc. Only present when `fields=altText` is requested.

Media (object):

Field	Type	Description
`type`	string	Media type. One of: `"image"`, `"video"`.
`url`	string	URL of the media asset (`cdn.flbx.io`).
`fallbackUrl`	string	Direct S3 URL used if the primary `url`is unavailable.
`thumbnail`	boolean	Whether this media item is the designated thumbnail for the post.

Cursor (object):

Field	Type	Description
`feedKey`	string	Key of the feed the cursor is scoped to. Matches the `flowKey`of the returned posts.
`key`	string	`postKey`of the last retrieved post.
`publishedAt`	string	ISO 8601 timestamp of the last retrieved post. Used for pagination.
`tableName`	string	Internal identifier for the data source, e.g.`"approved_posts"`.