/api/v1/post

Overview

Create a post immediately or schedule it to run later, targeting one or more of your connected social profiles. You can attach media files (images/videos) via URLs.

Authentication

To authenticate, include the following headers in your request:

x-api-key: Your API key (found in PostFaster.io > Profile > Settings)
user-id: Your unique user ID (found in PostFaster.io > Profile > Settings)

Notes:

Requests may be subject to your account’s IP/User-Agent restrictions if enabled in Settings.
Internal scheduling uses additional headers; you do not need to set them manually.

Request

Method: `POST`

URL

https://postfaster.io/api/v1/post

Headers


{
  "Content-Type": "application/json",
  "x-api-key": "your-api-key",
  "user-id": "your-user-id"
}

Body Parameters

Parameter	Type	Required	Description
title	string	No	The title of the post.
description	string	No	The post body/caption.
profileIds	string[]	Yes	One or more social profile IDs owned by the user to publish to.
files	File[]	No	List of media files to attach (see File schema).
schedule	boolean	No	When true, schedules the post for later.
scheduleDate	string (ISO 8601)	Cond.	Required if `schedule` is true. The UTC datetime to publish.

File schema (when sending files):


{
  "url": "https://example.com/image.png",   // required, public URL
  "name": "image.png",                      // required
  "type": "image/png",                      // required, MIME type
  "size": 123456,                             // required, file size in bytes
  "key": "ut-optional-storage-key"          // optional, internal key for cleanup
}

Request Examples

Publish now to multiple profiles


{
  "title": "Launch day 🚀",
  "description": "We just shipped!",
  "profileIds": [
    "sp_12345_fb",
    "sp_67890_ig"
  ],
  "files": [
    {
      "url": "https://cdn.example.com/launch.png",
      "name": "launch.png",
      "type": "image/png",
      "size": 204800
    }
  ]
}

Schedule for later


{
  "title": "Webinar tomorrow",
  "description": "Join us at 4pm UTC",
  "profileIds": ["sp_12345_fb", "sp_67890_ig"],
  "files": [],
  "schedule": true,
  "scheduleDate": "2025-03-02T16:38:30Z"
}

Responses

Success Response

When posted immediately


{
  "status": "OK",
  "data": {
    "postId": "post_abc123",
    "targets": {
      "sp_12345_fb": {
        "status": "posted",
        "link": "https://facebook.com/posts/123"
      },
      "sp_67890_ig": {
        "status": "failed",
        "error": "Media not supported"
      }
    }
  }
}

When scheduled successfully


{
  "message": "Post scheduled for 2025-03-02T16:38:30Z across 2 profiles"
}

Error Responses

Missing API Key


{
  "error": "No api key found"
}

Invalid API Key


{
  "error": "API key is not correct"
}

Missing User ID


{
  "error": "No user ID found"
}

Invalid User ID


{
  "error": "Invalid user ID"
}

One or more profiles invalid


{
  "error": "One or more profiles invalid"
}


{
  "error": "Please authorize Facebook before posting it, you can do this on www.postfaster.io"
}

File Download Error


{
  "status": "ERROR",
  "errorMessages": [
    "Unable to download file image.png from: https://example.com/image.png"
  ]
}

Additional Notes

Ensure that your API key is valid and linked to your account.
If your API key is missing, generate one from PostFaster.io > Profile > Settings.
You must pass valid profileIds that belong to your account and are authorized for posting. Posts to profiles you don’t own will be rejected.
Scheduled posts are enqueued per profile and executed at the specified time. You’ll see them in your Scheduled Jobs list.
For support, contact our helpdesk at support@postfaster.io.