OpenAPI 3.1.0·API v1.0.0

PostSocials Developer API Reference

Unified social media publishing API. Publish videos, Reels, Shorts, photos, carousels, and text across 14 social networks with one HTTP call.

Authentication

Authenticate all REST API requests with a scoped API key generated in Dashboard → Developers. Keys are hashed with SHA-256 at rest and prefixed with ps_live_.

Base URL: https://postsocials.dev/api/v1
Authorization: Bearer ps_live_a1b2c3...

Rate Limits & Response Headers

Every response includes sliding-window rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

PlanAPI ThroughputMonthly Uploads
Free30 req/min30 / month
Basic120 req/minUnlimited
Professional300 req/minUnlimited
Advanced600 req/minUnlimited
Business1,200 req/minUnlimited

Error Envelopes

Errors always return a structured JSON envelope: { "error": { "code", "message", "details?" } }.

HTTPError CodeDescription
400BAD_REQUESTMalformed JSON or invalid parameter.
401UNAUTHORIZEDMissing, invalid, or revoked Bearer API key.
402QUOTA_EXCEEDEDFree plan 30 uploads/month quota reached.
403PLAN_UPGRADE_REQUIREDFeature or network (e.g. TikTok, Whitelabel) requires a higher plan.
404NOT_FOUNDProfile or upload job ID does not exist.
422VALIDATION_ERRORSchema or platform media/caption constraint failed.
429RATE_LIMITEDPer-minute API rate limit exceeded. Respect Retry-After.

Webhook HMAC-SHA256 Verification

Verify the X-PostSocials-Signature: t=...,v1=... header against the raw request body using your webhook signing secret.

verify-webhook.mjs
import crypto from "node:crypto";

export function verifyPostSocialsWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((pair) => pair.split("="))
  );
  if (!parts.t || !parts.v1) return false;

  // Reject signatures older than 5 minutes
  const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t));
  if (ageSeconds > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(parts.v1, "utf8"),
    Buffer.from(expected, "utf8")
  );
}

Endpoint Reference

GET/usage
Usage

Get current plan and quota usage

Responses
200 Current billing period usage and profile/seat limits
401 Invalid or missing API key
cURL Example
curl -X GET "https://postsocials.dev/api/v1/usage" \
  -H "Authorization: Bearer ps_live_your_key_here"
GET/profiles
Profiles

List all profiles

Responses
200 Array of workspace profiles
cURL Example
curl -X GET "https://postsocials.dev/api/v1/profiles" \
  -H "Authorization: Bearer ps_live_your_key_here"
POST/profiles
Profiles

Create a profile

Responses
201 Created profile
403 Profile cap exceeded for current plan
cURL Example
curl -X POST "https://postsocials.dev/api/v1/profiles" \
  -H "Authorization: Bearer ps_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Brand", "description": "Primary social channels" }'
POST/profiles/{id}/connect-url
Whitelabel

Generate Whitelabel Connect Portal URL

Generates a single-use hosted OAuth Connect link styled with your workspace whitelabel settings. Requires the Professional plan or higher.

Parameters
idin path
required
Responses
201 Single-use hosted connect URL
403 Plan upgrade required (Professional+)
cURL Example
curl -X POST "https://postsocials.dev/api/v1/profiles/prof_acme_main/connect-url" \
  -H "Authorization: Bearer ps_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "redirectUrl": "https://yourapp.com/settings/social", "expiresInMinutes": 60 }'
GET/uploads
Uploads

List upload jobs

Parameters
limitin query
cursorin query
profileIdin query
statusin query
Responses
200 Paginated list of uploads
cURL Example
curl -X GET "https://postsocials.dev/api/v1/uploads" \
  -H "Authorization: Bearer ps_live_your_key_here"
POST/uploads
Uploads

Create and publish (or schedule) a multi-platform upload

Responses
201 Upload created and dispatched or scheduled
402 Monthly quota exceeded on Free plan (30 uploads/month)
403 Target platform requires a higher plan (e.g., TikTok on Basic+)
429 Rate limit exceeded
cURL Example
curl -X POST "https://postsocials.dev/api/v1/uploads" \
  -H "Authorization: Bearer ps_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "prof_acme_main",
    "mediaType": "video",
    "mediaItems": [{
      "url": "https://cdn.example.com/clip.mp4",
      "mimeType": "video/mp4",
      "sizeBytes": 12450000
    }],
    "title": "Release Demo",
    "caption": "Shipping v1.4 today.",
    "targetPlatforms": ["youtube", "instagram", "x"],
    "platformConfig": {
      "youtube": { "privacyStatus": "public", "isShort": true },
      "instagram": { "placement": "reels" }
    }
  }'
GET/uploads/{id}
Uploads

Get upload job status & per-platform results

Parameters
idin path
required
Responses
200 Upload job details
404 Upload not found
cURL Example
curl -X GET "https://postsocials.dev/api/v1/uploads/prof_acme_main" \
  -H "Authorization: Bearer ps_live_your_key_here"
DELETE/uploads/{id}
Uploads

Cancel a scheduled upload or delete a draft

Parameters
idin path
required
Responses
200 Upload canceled/deleted
cURL Example
curl -X DELETE "https://postsocials.dev/api/v1/uploads/upl_7f21d0c9a841" \
  -H "Authorization: Bearer ps_live_your_key_here"
GET/analytics
Analytics

Query aggregated analytics metrics

Parameters
profileIdin query
platformin query
fromin query
toin query
Responses
200 Aggregated KPIs, daily series, and platform breakdown
cURL Example
curl -X GET "https://postsocials.dev/api/v1/analytics" \
  -H "Authorization: Bearer ps_live_your_key_here"