PostFast API

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

Rate Limiting

Rate limits are counted per endpoint, per workspace API key. Calls to one endpoint never use another endpoint's budget, so reaching the limit on one endpoint does not slow down the others.

Every endpoint has four windows: 1 minute, 5 minutes, 1 hour, and 24 hours. Exceeding any of them returns a 429. Each endpoint page lists the windows that endpoint sets itself; any window it does not set uses the default below.

Default Limits (Per Endpoint)

• 72 requests per minute
• 180 requests per 5 minutes
• 360 requests per hour
• 2,400 requests per day

For example, DELETE /social-posts/:id sets 200 requests per hour, so it allows 2,400 requests per day, 200 per hour, 180 per 5 minutes, 72 per minute.

How the Windows Work

• A window starts at the endpoint's first call, not on a clock boundary. The 24-hour window is not a reset at midnight UTC.
• Once a window is exceeded, that endpoint stays blocked for the full length of the window from that moment: up to 60 seconds for the minute window and up to 24 hours for the daily one.
• Calls made while blocked still count toward the window, so retrying early can keep the endpoint blocked.

Rate Limit Headers

Every response carries one set of headers per window, named short (1 minute), medium (5 minutes), long (1 hour), and daily (24 hours). The first call to an endpoint on the default minute and 5-minute limits returns, among others:

X-RateLimit-Limit-short: 72
X-RateLimit-Remaining-short: 71
X-RateLimit-Reset-short: 60
X-RateLimit-Limit-medium: 180
X-RateLimit-Remaining-medium: 179
X-RateLimit-Reset-medium: 300

Header meanings:

• X-RateLimit-Limit-[window]: The endpoint's limit for that window
• X-RateLimit-Remaining-[window]: Requests left in the window
• X-RateLimit-Reset-[window]: Seconds until the window resets

Rate Limit Exceeded (429 Response)

When a window is exceeded, the response carries a retry header named after that window, plus the standard Retry-After with the same value:

Retry-After-long: 2395
Retry-After: 2395

{
  "statusCode": 429,
  "message": "Too many requests. Please try again later.",
  "error": "Too Many Requests"
}

• Retry-After: Seconds to wait before calling this endpoint again, up to 60 for the minute window and up to 86,400 for the daily one. This is the standard header, and the one to read if your HTTP client, n8n or Zapier handles back-off for you.
• Retry-After-[window]: The same value, named after the window that was exceeded (for example Retry-After-long). Useful for telling which limit you hit.

Staying Inside the Limits

• Read the X-RateLimit-Remaining-[window] headers and slow down before one reaches 0.
• On a 429, wait Retry-After seconds before calling that endpoint again. Retrying earlier still counts toward the window.
• Don't poll the account list or the post list in a tight loop.

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.
   Node.jscURLPythonn8n

   // Upload file to S3 using the signed URL from previous step  
   const fs = require('fs');
   const file = fs.readFileSync('/path/to/your/image.png');
   
   const response = await fetch(signedUrl, {
     method: 'PUT',
     body: file,
     headers: {
       'Content-Type': 'image/png' // Must match contentType from step 1
     }
   });
   
   if (response.ok) {
     // File uploaded successfully
     // Use the 'key' from step 1 in your social posts
   }

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 (e.g., image/a1b2c3d4-e5f6-7890-1234-567890abcdef.png). Ensure the type field ('IMAGE' or 'VIDEO') matches the key prefix.
   • Optionally include controls for platform-specific settings.