Version: 1.0.0


A status is a small publication created by an user. It could be either a piece of text, one or more pictures, or even an embed reference to an external content like a news article or a Youtube video.

It has also the possibility of mentionning an user by an @ and the user nickname (if you are using nicknames for your users).

Create a basic text status

The first mandatory element for status creation is to create or retrieve an UserAPI ID. With that id, the status you will build will be linked to that user.

Now you can make a HTTP POST request with parameters in JSON form (including a user's unique id as an owner_id parameter, the "User" string as owner_type and a text value as the message parameter). And that's all for our basic status.

Notice that Status, can also be created with the Page entity with owner_type value as "Page" and the page id of your choice for owner_id field.

You also can pass these parameters as form-data instead of JSON.

Make sure to give your ApiTokenAPI and ApiSecretAPI as header in the HTTP request

curl -X POST \ \
-H 'Api-Key: YOUR_API_KEY' \
-H 'Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-d '{
"message": "Hello Worlds !",
"owner_type": "User",
"owner_id": "YOUR_USER_ID",
"user_id": "YOUR_USER_ID"

As a result, you will get a JSON representation of your new status. Note that it's unique id is important if you wish to retrieve that status later on.

Gather all created statuses

Once some statuses were created, you will most of the time need to display them somewhere. You can gather them with an HTTP GET request.

Some filtering parameters are available, like limiting results to what an user has the right to display or only statuses with selected tags.

curl -X GET \ \
-H 'Api-Key: YOUR_API_KEY' \
-H 'Api-Secret: YOUR_API_SECRET' \
-H 'Content-Type: application/json' \

By default, you will get the 20 latest created statuses. You can tweak your query by accessing a different page to view more statuses. You can also configure the number of elements per page with the per_page parameter

Enhance statuses

As explained in the introduction of this section, statuses could be more than just a piece of text. Here is all available types of content you could push in addition or replacement for that text.


There is two ways to add images to a status.

You can pass some files to your HTTP request in an array as the media parameter. Or you can also give some links to pictures in an array with the media_url parameter (Potion will download those images).

In both cases, these files will be processed and optimized by Potion and you will get an URL for each of them in the JSON representation of your freshly created status.

You can see how our images can be manipulated in this section.


An embed is a representation of a distant url. You can give a link to a web page in the embed_url parameter and that page will be parsed by Potion. The result of that processing depends of the page content you submit.

If your page is a news article, you will get a data breakdown of what we found on that article (like it's title, description, thumbnail picture, etc), allowing you to properly display that content.

If you give a link to a compatible content like a Youtube video, a Spotify song or a Twitter tweet, you can also get html code (in the html response parameter of the embed) allowing you to directly insert the content on your page.

You can find the embed JSON representation details in the create statuses sectionAPI of Potion API Reference