API - Social Post Flow

Introduction

The Social Post Flow API provides functionality to:

Fetch a list of social media profiles connected to the authenticated Social Post Flow account,
Create, edit, delete and list social media posts created on the authenticated Social Post Flow account,
Publish content to social media account(s) connected to the authenticated Social Post Flow account.

This is a private API, not available to the general public. If you’re looking for an integration with Social Post Flow, check the integrations page.

Headers

All requests must include the following headers:

Header Name	Value
Accept	`application/json`

All authenticated API endpoints must include the following headers:

Header Name	Value
Authorization	Bearer `your-access-token`
Accept	`application/json`

Responses

Social Post Flow returns data in JSON format, within a data resource

{
    "data": [
        {
            "id": 2,
            "provider": "x",
            "profile_name": "socialpostflow"
        },
        {
            "id": 3,
            "provider": "facebook",
            "profile_name": "Social Post Flow"
        },
    ]
}

Pagination

GET requests that may return multiple resources (profiles, posts etc) support pagination parameters:

Parameter	Value	Required
page	`integer` The current page of the paginated resultset to return	No
per_page	`integer` The number of results to return	No

The response will include links and meta resources are also returned:

{
    "data": [
        ...
    ],
    "links": {
        "first": "https://socialpostflow.local/api/profiles?page=1",
        "last": "https://socialpostflow.local/api/profiles?page=6",
        "prev": "https://socialpostflow.local/api/profiles?page=1",
        "next": "https://socialpostflow.local/api/profiles?page=3"
    },
    "meta": {
        "current_page": 2,
        "from": 2,
        "last_page": 6,
        "links": [
            {
                "url": "https://socialpostflow.local/api/profiles?page=1",
                "label": "&laquo; Previous",
                "active": false
            },
            {
                "url": "https://socialpostflow.local/api/profiles?page=1",
                "label": "1",
                "active": false
            },
            {
                "url": "https://socialpostflow.local/api/profiles?page=2",
                "label": "2",
                "active": true
            },
            {
                "url": "https://socialpostflow.local/api/profiles?page=3",
                "label": "3",
                "active": false
            },
            {
                "url": "https://socialpostflow.local/api/profiles?page=4",
                "label": "4",
                "active": false
            },
            {
                "url": "https://socialpostflow.local/api/profiles?page=5",
                "label": "5",
                "active": false
            },
            {
                "url": "https://socialpostflow.local/api/profiles?page=6",
                "label": "6",
                "active": false
            },
            {
                "url": "https://socialpostflow.local/api/profiles?page=3",
                "label": "Next &raquo;",
                "active": false
            }
        ],
        "path": "https://socialpostflow.local/api/profiles",
        "per_page": 1,
        "to": 2,
        "total": 6
    }
}

Ordering

GET requests that may return multiple resources (profiles, posts etc) support order parameters:

Parameter	Value	Required	Default
order_by	`string` The column to order results on	No	Profiles: `id` Posts: `scheduled_at`
order	`asc`: Return results in ascending order (A-Z) `desc`: Return results in descending order (Z-A)	No	`asc`

Errors

When an error occurs, a non-2xx HTTP code will be returned, with a JSON response.

Key	Description	Always Returned?
message	`string` The error(s) that occurred. This can be presented to the end user.	Yes
errors	`array<string>` Where more verbose errors can be provided, they will be individually included in this key. This is not always returned.	No

401 Unauthorized

{
    "message": "Unauthenticated."
}

This error is returned if:

No access token was specified,
An invalid or expired access token was specified in the request,
The Social Post Flow account no longer has access, due to a lapsed trial, failed account payment, lapsed subscription payment etc.

404 Not Found

{
    "message": "The route api/foobar could not be found."
}

This error is returned if:

An invalid endpoint was specified,
The queried resource (such as a profile or post) does not exist

422 Unprocessable Content

{
    "message": "The selected post type is invalid.",
    "errors": {
        "post_type": [
            "The selected post type is invalid."
        ]
    }
}

This error is returned if:

A query parameter’s value is invalid.

429 Rate Limit

{
    "message": "Too Many Attempts."
}

Social Post Flow’s API has a request rate limit of 600 requests per minute. A 429 HTTP code is returned when this rate limit is exceeded.

500 Internal Server Error

If the server is overloaded, or you encountered a bug, the API will return a 500 Internal Server Error. Try the request after a short amount of time, and if the issue persists, please open a support request.

Rate Limits

Social Post Flow’s API has a request rate limit of 600 requests per minute.

Authentication

Social Post Flow uses OAuth Proof Key for Code Exchange (PKCE).

This guide presumes knowledge of OAuth.

Authentication URL

To begin OAuth, send the user to https://app.socialpostflow.com/oauth/authorize with the following query parameters:

Parameter	Value
client_id	Your OAuth Client ID
response_type	code
redirect_uri	Your OAuth callback URL, which will exchange an authorization code for access and refresh tokens
state	Optional: a CSRF, nonce or other state value you require to be included when the user authenticates and is redirected to the redirect_uri
code_challenge	The code verifier is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long. This must be stored locally, and sent in this request as a base64-url encoded string of the SHA256 hash.
code_challenge_method	S256

Exchange Authorization Code for Access and Refresh Tokens

Once your user has approved your app, they are sent to the redirect_uri, which includes the following query parameters:

Parameter	Value
code	Authorization code
state	Optional: a CSRF, nonce or other state value specified in the state parameter in the Authentication step above.

Request

To exchange the Authorization Code for Access and Refresh Tokens, make a POST request to https://app.socialpostflow.com/oauth/token, with the following body:

Parameter	Value
client_id	Your OAuth Client ID
grant_type	authorization_code
code	The `code` parameter
redirect_uri	Your OAuth callback URL, which will exchange an authorization code for access and refresh tokens
code_verifier	The code verifier generated in the Authorization step. This should be the plain text version i.e. the non-base64 url encoded and non-SHA256 one.
code_challenge	The code verifier is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long. This must be stored locally, and sent in this request as a base64-url encoded string of the SHA256 hash.
code_challenge_method	S256

Response

HTTP Code	`200`
Response Schema	`application/json`

{
    "access_token": "YOUR_ACCESS_TOKEN_HERE",
    "token_type": "Bearer",
    "expires_in": 172800,
    "refresh_token": "YOUR_REFRESH_TOKEN_HERE",
    "scope": "public",
    "created_at": 1710270147
}

Refresh an expired Access Token

Request

To obtain a non-expired access token, make a POST request to https://app.socialpostflow.com/oauth/token, with the following body:

Parameter	Value
client_id	Your OAuth Client ID
grant_type	refresh_token
refresh_token	Your refresh token

Response

HTTP Code	`200`
Response Schema	`application/json`

{
    "access_token": "YOUR_ACCESS_TOKEN_HERE",
    "token_type": "Bearer",
    "expires_in": 172800,
    "refresh_token": "YOUR_REFRESH_TOKEN_HERE",
    "scope": "public",
    "created_at": 1710270147
}

Get User

GEThttps://app.socialpostflow.com/api/user

Authorization

Header Name	Value
Authorization	Bearer `your-access-token`
Accept	`application/json`

Query Parameters

None

Response

HTTP Code	`200`
Response Schema	`application/json`

{
    "data": {
        "name": "Social Post Flow",
        "email": "support@socialpostflow.com"
    }
}

List Profiles

GEThttps://app.socialpostflow.com/api/profiles

Query Parameters

Parameter	Value	Required	Default Value
post_type	`text`: Return profiles that support the text post type `link`: Return profiles that support the link preview post type `image`: Return profiles that support the image / images post type `story`: Return profiles that support the Instagram Story post type When not specified, all profiles will be returned	No	All Post Types
order_by	`id`: Order results by the profile’s ID `provider`: Order results by provider (`facebook`, `x`, `linkedin` etc) `profile_name`: Order results by the social media profile’s display name	No	`id`
order	`asc`: Return results in ascending order (A-Z) `desc`: Return results in descending order (Z-A)	No	`asc`
page	`integer` The current page of the paginated resultset to return	No	`1`
per_page	`integer` The number of results to return	No	`10`

Response

HTTP Code	`200`
Response Schema	`application/json`

{
    "data": [
        {
            "id": 1,
            "provider": "facebook",
            "profile_name": "Social Post Flow"
        },
        {
            "id": 2,
            "provider": "x",
            "profile_name": "socialpostflow"
        },
        {
            "id": 3,
            "provider": "instagram",
            "profile_name": "socialpostflow"
        },
        {
            "id": 4,
            "provider": "threads",
            "profile_name": "socialpostflow"
        },
        {
            "id": 5,
            "provider": "linkedin",
            "profile_name": "Social Post Flow"
        }
    ],
    "links": {
        "first": "https://app.socialpostflow.com/api/profiles?page=1",
        "last": "https://app.socialpostflow.com/api/profiles?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "active": false
            },
            {
                "url": "https://app.socialpostflow.com/api/profiles?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next &raquo;",
                "active": false
            }
        ],
        "path": "https://app.socialpostflow.com/api/profiles",
        "per_page": 10,
        "to": 5,
        "total": 5
    }
}

List Posts

GEThttps://app.socialpostflow.com/api/posts

Query Parameters

Parameter	Value	Required	Default Value
social_profile_id	`integer` The social profile ID to list posts for. This can be found using the List Profiles endpoint. When not specified, posts for all connected social profiles will be returned	No	All Social Profiles
status	`scheduled`: Return posts that have not yet been published i.e. are scheduled for publication `posted`: Return posts that posted successfully to social media `failed`: Return posts that failed to publish to social media When not specified, all posts will be returned	No	All Statuses
order_by	`scheduled_at`: Order results by the Post’s scheduled date and time `posted_at`: Order results by the Post’s published date and time `created_at`: Order results by the Post’s created date and time. Created refers to when the Post was added to Social Post Flow `updated_at`: Order results by the Post’s last modified date and time. Updated refers to when the Post was updated by an API call or Social Post Flow (for example, when the Post was published, its `status` will change, therefore updating the `updated_at` value.	No	`scheduled_at`
order	`asc`: Return results in ascending order (A-Z) `desc`: Return results in descending order (Z-A)	No	`asc`
page	`integer` The current page of the paginated resultset to return	No	`1`
per_page	`integer` The number of results to return	No	`10`

Response

HTTP Code	`200`
Response Schema	`application/json`

{
    "data": [
        {
            "id": 1,
            "social_profile_id": 1,
            "provider": "facebook",
            "profile_name": "Social Post Flow",
            "post_type": "text",
            "text": "Text Post",
            "first_comment": "First Comment",
            "url": null,
            "media_urls": [],
            "schedule_type": "immediate",
            "status": "scheduled",
            "failure_reason": null,
            "post_url": "",
            "scheduled_at": "2025-07-18T01:26:02.000000Z",
            "posted_at": null,
            "created_at": "2025-07-18T01:26:02.000000Z",
            "updated_at": "2025-07-18T01:26:02.000000Z"
        },
        {
            "id": 2,
            "social_profile_id": 2,
            "provider": "x",
            "profile_name": "socialpostflow",
            "post_type": "text",
            "text": "Text Post",
            "first_comment": "First Comment",
            "url": null,
            "media_urls": [],
            "schedule_type": "immediate",
            "status": "scheduled",
            "failure_reason": null,
            "post_url": "",
            "scheduled_at": "2025-07-18T01:26:02.000000Z",
            "posted_at": null,
            "created_at": "2025-07-18T01:26:02.000000Z",
            "updated_at": "2025-07-18T01:26:02.000000Z"
        },
    ],
    "links": {
        "first": "https://socialpostflow.local/api/posts?page=1",
        "last": "https://socialpostflow.local/api/posts?page=2",
        "prev": null,
        "next": "https://socialpostflow.local/api/posts?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "active": false
            },
            {
                "url": "https://socialpostflow.local/api/posts?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": "https://socialpostflow.local/api/posts?page=2",
                "label": "2",
                "active": false
            },
            {
                "url": "https://socialpostflow.local/api/posts?page=2",
                "label": "Next &raquo;",
                "active": false
            }
        ],
        "path": "https://socialpostflow.local/api/posts",
        "per_page": 10,
        "to": 10,
        "total": 18
    }
}

Create Text Post

Creates a text only post, with no link preview and no images, for the specified connect profiles.

POSThttps://app.socialpostflow.com/api/posts

Authorization

Header Name	Value
Authorization	Bearer `your-access-token`
Accept	`application/json`

Query Parameters

Parameter	Value	Required
post_type	`text`	Yes
text	`string` The content of the social media post	Yes
first_comment	`string` The content of the first comment to post when the social media post is published. Links may be included.	No
profile_ids	`array<integer>` An array of one or more Profile IDs to schedule/publish the social media post to. These can be found using the List Profiles endpoint.	Yes
schedule_type	`immediate`: Publish the post on social media as soon as possible (usually within 1 – 2 minutes) `queue_start`: Add the post ahead of any other post(s) scheduled, scheduling it up to 1 hour before. `queue_end`: Add the post after any other scheduled post(s), scheduling it to publish 1 hour after the last scheduled post. `scheduled`: Add the post, and schedule it to publish to social media on the given `scheduled_at` value below.	Yes
scheduled_at	`date`: For example, `2025-07-01 01:00:00`	Yes, if schedule_type = scheduled.

Response

HTTP Code	`201`: Post created successfully
Response Schema	`application/json`

{
    "data": [
        {
            "id": 16,
            "social_profile_id": "1",
            "provider": "facebook",
            "profile_name": "Social Post Flow",
            "post_type": "text",
            "text": "Post Content",
            "first_comment": "First Comment",
            "url": null,
            "media_urls": [],
            "schedule_type": "immediate",
            "status": "scheduled",
            "failure_reason": null,
            "post_url": "",
            "scheduled_at": "2025-07-28T02:38:06.000000Z",
            "posted_at": null,
            "created_at": "2025-07-28T02:38:06.000000Z",
            "updated_at": "2025-07-28T02:38:06.000000Z"
        }
    ]
}

Error Response

HTTP Code	A non-2xx HTTP code
Response Schema	`application/json`

{
    "message": "The text field is required.",
    "errors": {
        "text": [
            "The text field is required."
        ]
    }
}

Create Link Post

Creates a text post with a link preview, for the specified connect profiles.

POSThttps://app.socialpostflow.com/api/posts

Authorization

Header Name	Value
Authorization	Bearer `your-access-token`
Accept	`application/json`

Query Parameters

Parameter	Value	Required
post_type	`link`	Yes
text	`string` The content of the social media post	Yes
first_comment	`string` The content of the first comment to post when the social media post is published. Links may be included.	No
url	`string` The URL to include as a link in the post. Not all networks will present this as a link preview / social card.	Yes
profile_ids	`array<integer>` An array of one or more Profile IDs to schedule/publish the social media post to. These can be found using the List Profiles endpoint.	Yes
schedule_type	`immediate`: Publish the post on social media as soon as possible (usually within 1 – 2 minutes) `queue_start`: Add the post ahead of any other post(s) scheduled, scheduling it up to 1 hour before. `queue_end`: Add the post after any other scheduled post(s), scheduling it to publish 1 hour after the last scheduled post. `scheduled`: Add the post, and schedule it to publish to social media on the given `scheduled_at` value below.	Yes
scheduled_at	`date`: For example, `2025-07-01 01:00:00`	Yes, if schedule_type = scheduled.

Response

HTTP Code	`201`: Post created successfully
Response Schema	`application/json`

{
    "data": [
        {
            "id": 17,
            "social_profile_id": "1",
            "provider": "facebook",
            "profile_name": "Social Post Flow",
            "post_type": "link",
            "text": "Post Content!",
            "first_comment": "First Comment",
            "url": "https://www.socialpostflow.com",
            "media_urls": [],
            "schedule_type": "immediate",
            "status": "scheduled",
            "failure_reason": null,
            "post_url": "",
            "scheduled_at": "2025-07-28T02:42:28.000000Z",
            "posted_at": null,
            "created_at": "2025-07-28T02:42:28.000000Z",
            "updated_at": "2025-07-28T02:42:28.000000Z"
        }
    ]
}

Error Response

HTTP Code	A non-2xx HTTP code
Response Schema	`application/json`

{
    "message": "The url field is required.",
    "errors": {
        "url": [
            "The url field is required."
        ]
    }
}

Create Image Post

Creates an image or carousel post, for the specified connect profiles.

POSThttps://app.socialpostflow.com/api/posts

Authorization

Header Name	Value
Authorization	Bearer `your-access-token`
Accept	`application/json`

Query Parameters

Parameter	Value	Required
post_type	`image`	Yes
text	`string` The content of the social media post	Yes
first_comment	`string` The content of the first comment to post when the social media post is published. Links may be included.	No
media_urls	`array<string>` One or more image URLs to include in the post. These must be accessible to the Social Post Flow API, with no firewall rules, authentication or other strategies limiting access. The API will copy these images, cropping them to the social network’s required dimensions. If you need to delete the media specified in your included media_urls, you may safely do after a successful API request.	Yes
profile_ids	`array<integer>` An array of one or more Profile IDs to schedule/publish the social media post to. These can be found using the List Profiles endpoint.	Yes
schedule_type	`immediate`: Publish the post on social media as soon as possible (usually within 1 – 2 minutes) `queue_start`: Add the post ahead of any other post(s) scheduled, scheduling it up to 1 hour before. `queue_end`: Add the post after any other scheduled post(s), scheduling it to publish 1 hour after the last scheduled post. `scheduled`: Add the post, and schedule it to publish to social media on the given `scheduled_at` value below.	Yes
scheduled_at	`date`: For example, `2025-07-01 01:00:00`	Yes, if schedule_type = scheduled.

Response

HTTP Code	`201`: Post created successfully
Response Schema	`application/json`

{
    "data": [
        {
            "id": 18,
            "social_profile_id": "1",
            "provider": "facebook",
            "profile_name": "Social Post Flow",
            "post_type": "image",
            "text": "Some text with an image",
            "first_comment": "First Comment",
            "url": null,
            "media_urls": [
                "http://socialpostflow.local/storage/posts/1-6886e61ad62a2.jpg"
            ],
            "schedule_type": "immediate",
            "status": "scheduled",
            "failure_reason": null,
            "post_url": "",
            "scheduled_at": "2025-07-28T02:53:15.000000Z",
            "posted_at": null,
            "created_at": "2025-07-28T02:53:15.000000Z",
            "updated_at": "2025-07-28T02:53:15.000000Z"
        }
    ]
}

Error Response

HTTP Code	A non-2xx HTTP code
Response Schema	`application/json`

{
    "message": "The media urls field is required when post type is image.",
    "errors": {
        "media_urls": [
            "The media urls field is required when post type is image."
        ]
    }
}

Create Story Post

Creates an Instagram Story post, for the specified connect profiles.

POSThttps://app.socialpostflow.com/api/posts

Authorization

Header Name	Value
Authorization	Bearer `your-access-token`
Accept	`application/json`

Query Parameters

Parameter	Value	Required
post_type	`story`	Yes
media_urls	`array<string>` One or more image URLs to include in the post. These must be accessible to the Social Post Flow API, with no firewall rules, authentication or other strategies limiting access. The API will copy these images, cropping them to the social network’s required dimensions. If you need to delete the media specified in your included media_urls, you may safely do after a successful API request.	Yes
profile_ids	`array<integer>` An array of one or more Profile IDs to schedule/publish the social media post to. These can be found using the List Profiles endpoint.	Yes
schedule_type	`immediate`: Publish the post on social media as soon as possible (usually within 1 – 2 minutes) `queue_start`: Add the post ahead of any other post(s) scheduled, scheduling it up to 1 hour before. `queue_end`: Add the post after any other scheduled post(s), scheduling it to publish 1 hour after the last scheduled post. `scheduled`: Add the post, and schedule it to publish to social media on the given `scheduled_at` value below.	Yes
scheduled_at	`date`: For example, `2025-07-01 01:00:00`	Yes, if schedule_type = scheduled.

Response

HTTP Code	`201`: Post created successfully
Response Schema	`application/json`

{
    "data": [
        {
            "id": 19,
            "social_profile_id": "3",
            "provider": "instagram",
            "profile_name": "socialpostflow",
            "post_type": "story",
            "text": "Instagram Story Post",
            "first_comment": null,
            "url": null,
            "media_urls": [
                "http://socialpostflow.local/storage/posts/3-6886e7156278d.jpg"
            ],
            "schedule_type": "immediate",
            "status": "scheduled",
            "failure_reason": null,
            "post_url": "",
            "scheduled_at": "2025-07-28T02:57:25.000000Z",
            "posted_at": null,
            "created_at": "2025-07-28T02:57:25.000000Z",
            "updated_at": "2025-07-28T02:57:25.000000Z"
        }
    ]
}

Error Response

HTTP Code	A non-2xx HTTP code
Response Schema	`application/json`

{
    "message": "Story posts can only be created for Instagram profiles.",
    "errors": {
        "post_type": [
            "Story posts can only be created for Instagram profiles."
        ]
    }
}