How to retrieve posts using Flowbox's API - v1 (legacy)

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/v1/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.
`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"`.

Optional Parameters

Parameter	Type	Location	Description
`postsPerPage`	integer	query	Number of posts to retrieve per request. Defaults to `29`. Maximum is `58`.
`productId`*	string	query	Product ID to filter posts by. When provided, returns matching posts from all Flows in the account. If omitted, returns posts from the Approved folder of the Flow matching the `flowKey`.
`similarProduct`	boolean	query	This is a premium feature, contact your CSM for more information. 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).
`tags`*	string	query	Comma-separated list of tags to filter posts by.
`operator`	string	query	Logical operator for tag filtering. `"AND"` returns posts matching all specified tags. `"OR"` returns posts matching any specified tag.
`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/v1/flow/INSERT_FLOW_KEY_HERE/posts?locale=es-es&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 structure:

Root:

Field	Type	Description
`status`	string	Request status. One of: `"success"`, `"error"`.
`data.posts`	array	List of post objects. See Post object 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)`.
`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.

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"`.