PostFast API Documentation

Download n8n Integration

Welcome to the PostFast API! Integrate our social media scheduling power into your applications.

Table of Contents

Introduction

The PostFast REST API allows you to programmatically manage your social media content, including scheduling posts, uploading media, and retrieving information about your connected social accounts.

The base URL for all API requests is:

https://api.postfa.st/

The API rate limits are shared across all workspaces in a single PostFast account.

We apply rate limits to prevent abuse and ensure fair usage. We do not allow spamming or unfair use of the API. You can review thefair usage policy. We reserve the right to terminate any API keys or accounts that violate our fair use policies or terms of service.

I. Authentication

Overview

All API requests must be authenticated using an API key specific to your workspace. The API key must be included in the request headers as pf-api-key.

Generating an API Key

Users with an ADMIN role in a workspace can generate an API key from the Workspace Settings page within the PostFast web application. Each API key is uniquely tied to a single workspace and grants access only to the social media accounts connected within that specific workspace. This key is then used for authenticating your REST API requests.

Example Header:

pf-api-key: YOUR_WORKSPACE_API_KEY

II. API Endpoints

A. File Management

POST /file/get-signed-upload-urls

Generates pre-signed URLs for uploading media files (images or videos) directly to S3.

Rate Limit 60 requests per 24 hours.

Request Headers:
  • pf-api-key: string (Required) - Your workspace API key.
Request Body (application/json):
  • contentType: string (Required) - The MIME type of the file.
    • Supported image types: image/jpeg, image/png, image/gif, image/webp.
    • Supported video types: video/mp4, video/webm, video/mov, video/quicktime.
  • count: number (Required) - Number of signed URLs.
    • Min: 1.
    • Max: 4 for images.
    • Max: 1 for videos (must be 1 if contentType is video).
Successful Response (200 OK):

An array of objects, each containing:

  • key: string - The S3 object key for upload.
  • signedUrl: string - The pre-signed S3 URL for PUT request.

Important Note for Uploading to S3:

After obtaining the signedUrl and key, perform an HTTP PUT request to the signedUrl with the raw file data as the request body. The Content-Type header in this PUT request must match the contentType used to generate the signed URL.

Example Request (cURL):
curl -X POST "https://api.postfa.st/file/get-signed-upload-urls" \
  -H "pf-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "image/png",
    "count": 2
  }'
Example Response (JSON):
[
  {
    "key": "workspace_id/random_uuid_name.png",
    "signedUrl": "https://s3.your-region.amazonaws.com/your-bucket/workspace_id/random_uuid_name.png?AWSAccessKeyId=..."
  },
  {
    "key": "workspace_id/another_random_uuid_name.png",
    "signedUrl": "https://s3.your-region.amazonaws.com/your-bucket/workspace_id/another_random_uuid_name.png?AWSAccessKeyId=..."
  }
]

B. Social Media Account Management

GET /social-media/my-social-accounts

Retrieves a list of social media accounts connected to the workspace associated with the API key.

Social media account IDs are immutable and can be safely cached in your application's storage (e.g., Redis, constants) to optimize performance and reduce API calls.

Rate Limit 60 requests per 10 minutes.

Request Headers:
  • pf-api-key: string (Required) - Your workspace API key.
Successful Response (200 OK):

An array of objects, each representing a social media account:

  • id: string - Unique identifier for the account.
  • platform: string - E.g., "X", "FACEBOOK", "INSTAGRAM", "LINKEDIN", "TIKTOK", "YOUTUBE", "BLUESKY".
  • platformUsername: string (Optional) - Username on the platform.
  • displayName: string (Optional) - Display name.
Example Request (cURL):
curl -X GET "https://api.postfa.st/social-media/my-social-accounts" \
  -H "pf-api-key: YOUR_API_KEY"
Example Response (JSON):
[
  {
    "id": "acc_123xyz",
    "platform": "X",
    "platformUsername": "postfast_app",
    "displayName": "PostFast Official"
  },
  {
    "id": "acc_789abc",
    "platform": "FACEBOOK",
    "platformUsername": null,
    "displayName": "My FB Page"
  }
]

C. Social Post Management

POST /social-posts

Creates and schedules one or more social posts.

Rate Limit 30 requests per 24 hours.

Platform Rate LimitsX (Twitter) posts through the API per account per day: 5, and we highly recommend not to exceed it on a daily basis.

Request Headers:
  • pf-api-key: string (Required)
Request Body (application/json):
  • posts: array (Required) - Array of post objects:
    • content: string (Required) - Text content.
    • mediaItems: array (Optional) - Array of media item objects:
      • key: string (Required) - S3 object key from /file/get-signed-upload-urls.
      • type: string (Required) - 'IMAGE' or 'VIDEO'.
      • sortOrder: number (Required) - Sort order for the media items.
      • coverTimestamp: number (Optional) - Timestamp in seconds to use as the cover image, if social media platform supports it.
    • scheduledAt: string (Optional for draft posts, otherwise required) - ISO 8601 date-time (e.g., YYYY-MM-DDTHH:mm:ss.sssZ). UTC.
    • socialMediaId: string (Required) - ID from /social-media/my-social-accounts.
  • status: string (Optional) - DRAFT or SCHEDULED. (default: SCHEDULED)
  • approvalStatus: string (Optional) - APPROVED or PENDING_APPROVAL. (default: APPROVED)
  • controls: object (Optional) - Platform-specific controls:
    • xCommunityId: string (Optional) - For X (Twitter) community ID.
    • instagramPublishType: string (Optional) - For Instagram "TIMELINE", "STORY".
Successful Response (201 Created):

An object containing:

  • postIds: string[] - Array of unique IDs for the created posts.
Example Request (cURL):
curl -X POST "https://api.postfa.st/social-posts" \
  -H "pf-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [
      {
        "content": "Hello from the API! Check out this image.",
        "mediaItems": [
          {
            "key": "<prefix>/random_uuid_name.png",
            "type": "IMAGE",
            "sortOrder": 0,
            "coverTimestamp": 10
          }
        ],
        "scheduledAt": "2024-12-31T10:00:00.000Z",
        "socialMediaId": "<uuid>"
      }
    ],
    "controls": {
      "instagramPublishType": "FEED"
    }
  }'
Example Response (JSON):
{
  "postIds": ["<uuid1>", "<uuid2>"]
}

DELETE /social-post/{id}

Deletes a scheduled or failed social post.

Rate Limit 120 requests per 1 hour.

Request Headers:
  • pf-api-key: string (Required)
Path Parameters:
  • id: string (Required) - The ID of the social post to delete.
Successful Response (200 OK):

A JSON object indicating success:

{
  "deleted": true 
}

(Returns { "deleted": false } or an error if deletion fails or post not found).

Example Request (cURL):
curl -X DELETE "https://api.postfa.st/social-post/post_abc123def456" \
  -H "pf-api-key: YOUR_API_KEY"
Example Response (JSON):
{
  "deleted": true
}

Error Responses

Common HTTP status codes you might encounter:

  • 400 Bad Request - The request was malformed (e.g., missing required fields, invalid JSON). Check the response body for specific error messages.
  • 401 Unauthorized - The API key is missing, invalid, or not authorized for the workspace.
  • 403 Forbidden - The API key is valid, but does not have permissions for the requested action (e.g., trying to access resources of another workspace).
  • 404 Not Found - The requested resource (e.g., a specific social post for deletion) could not be found.
  • 429 Too Many Requests - You have exceeded the rate limit for the endpoint.
  • 500 Internal Server Error - An unexpected error occurred on our server.

III. Typical Workflow: Scheduling Posts with Media

  1. Authentication: Ensure you have a valid pf-api-key for your workspace.
  2. (Optional) Identify Target Account: Call GET /social-media/my-social-accounts to list available social media accounts and retrieve the id of the account you want to post to. Store these IDs as they are generally stable.
  3. Request Signed URLs for Media: If your posts include media:
    • Call POST /file/get-signed-upload-urls with the contentType (e.g., image/png) and count.
    • Receive a response containing an array of { key, signedUrl } objects.
  4. Upload Media to S3: For each media item:
    • Perform an HTTP PUT request to the signedUrl.
    • The request body must be the raw file data.
    • The Content-Type header of this PUT request must match the contentType used in the previous step.
    const response = await fetch(url, {
      method: 'PUT',
      body: file,
      headers: {
        'Content-Type': file.type
      }
    });
  5. Create the Social Posts:
    • Call POST /social-posts.
    • In the request body, include an array of posts in the posts field, each containing content, scheduledAt, and socialMediaId.
    • If media was uploaded, populate the mediaItems array for each post using the key(s) from step 3 (for successfully uploaded files). Ensure the type in mediaItems ('IMAGE' or 'VIDEO') corresponds to the uploaded file.
    • Optionally include controls for platform-specific settings.
Download n8n Integration Workflow