|

Generate an API key below, then send it as Authorization: Bearer fsp_live_… or FSP-API-KEY: fsp_live_…. Keys are scoped to your account and can be revoked anytime.

curl -X POST https://post.freesurf.tools/api/post \
  -H "Authorization: Bearer fsp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platforms":["x","linkedin"],"text":"Hello from the API","team":"Personal"}'

await fetch("https://post.freesurf.tools/api/post", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fsp_live_...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ platforms: ["x"], text: "Hello from JS", team: "Personal" })
});

import requests
requests.post("https://post.freesurf.tools/api/post",
  headers={"Authorization": "Bearer fsp_live_..."},
  json={"platforms": ["x"], "text": "Hello from Python", "team": "Personal"})

Body: platforms (array), text, team (name) or teamId (id) — one is required — plus optional mediaUrls.

Instagram feed images auto-fit by default; pass "instagramImageFit":"crop" to center-crop instead. For Facebook, LinkedIn, and YouTube, select a page/channel in the Accounts tab so posts go to the right target.

Response:

{
  "id": "post-uuid",
  "results": [
    { "platform": "x", "success": true, "postUrl": "https://x.com/..." }
  ],
  "postedAt": "2026-08-30T19:00:00Z"
}

Media (images / videos) — upload a local file to get an uploadId, then pass it in mediaUrls:

curl -X POST https://post.freesurf.tools/api/media/upload \
  -H "Authorization: Bearer fsp_live_..." \
  -F "file=@/path/to/image.png"

# then post with the returned uploadId
curl -X POST https://post.freesurf.tools/api/post \
  -H "Authorization: Bearer fsp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platforms":["x"],"text":"Caption here","team":"Personal","mediaUrls":["UPLOAD_ID"]}'

The upload response is JSON — grab the uploadId field (it's the first field) and use it in mediaUrls. PowerShell one-liner to capture it:

$uploadId = (curl.exe -s -X POST https://post.freesurf.tools/api/media/upload -H "FSP-API-KEY: fsp_live_..." -F "file=@video.mp4" | ConvertFrom-Json).uploadId

text is the caption. Pass multiple ids for carousels (X, LinkedIn, Instagram); TikTok/YouTube need a single video.

Supported types: jpg / jpeg / png / gif / mp4 / mov / pdf.

curl -X POST https://post.freesurf.tools/api/schedule \
  -H "Authorization: Bearer fsp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platforms":["x"],"text":"Later post","scheduledAt":"2026-08-31T14:00:00Z","team":"Personal"}'

scheduledAt must be a future ISO timestamp. Team (by name or teamId) is required, same as posting. Posts publish within ~5 minutes of that time.

curl https://post.freesurf.tools/api/scheduled \
  -H "Authorization: Bearer fsp_live_..."

curl -X DELETE https://post.freesurf.tools/api/scheduled/POST_ID \
  -H "Authorization: Bearer fsp_live_..."

Post to a team by name (team) or id (teamId) — either works. Team names are unique per account:

# By team name
curl -X POST https://post.freesurf.tools/api/post \
  -H "Authorization: Bearer fsp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platforms":["x"],"text":"For my business","team":"Personal"}'

# By team id (get ids from /api/teams)
curl -X POST https://post.freesurf.tools/api/post \
  -H "Authorization: Bearer fsp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platforms":["x"],"text":"For my business","teamId":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}'

A team is required for every post — posts never default to another team.

Developer / API only — irreversible, so it's intentionally not exposed in the UI. Deletes a post already published to a platform (currently X). X deletes are metered at $0.01 each, drawn from your credit balance.

curl -X POST https://post.freesurf.tools/api/posts/delete \
  -H "Authorization: Bearer fsp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platform":"x","postId":""}'

postId is the recorded postId from GET /api/posts/recent for that platform's result. There's no undo.

Backfill posts a connected account published before it was connected (runs as an async job) — useful for X, whose per-post analytics aren't served passively. Imported posts come back with their analytics (impressions / likes / comments / shares where the platform reports them). Supports x, bluesky, threads, tiktok, linkedin, instagram, facebook, pinterest, youtube, reddit, mastodon.

# Start an import (async job — runs in the background)
curl -X POST https://post.freesurf.tools/api/import \
  -H "Authorization: Bearer fsp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platform":"x","count":50,"withAnalytics":true}'

# Poll job status (queued / running / completed / failed)
curl "https://post.freesurf.tools/api/imports?platform=x" \
  -H "Authorization: Bearer fsp_live_..."

# List the imported posts with their analytics + remaining capacity
curl "https://post.freesurf.tools/api/imports/posts?platform=x&count=50" \
  -H "Authorization: Bearer fsp_live_..."

count defaults to 50. Monthly import caps apply (e.g. 100/month on Pro); the posts endpoint returns remainingCapacity. Imports are billed at $0.005 per result. Refresh still only pulls live metrics for posts this app published — use import for anything that came before.

Pull the comments on one of your posts, then reply straight to a specific comment. Replying posts live and is metered like a post — $0.015 plain, $0.20 with a link — drawn from your credit balance.

# 1) Import the comments for a post (async — poll /api/comments until they appear)
curl -X POST https://post.freesurf.tools/api/comments/import \
  -H "Authorization: Bearer fsp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platform":"x","postId":""}'

# 2) List the fetched comments (each has an id, authorName, text, publishedAt)
curl "https://post.freesurf.tools/api/comments?platform=x&postId=" \
  -H "Authorization: Bearer fsp_live_..."

# 3) Reply to one of those comments (commentId = the comment's id from step 2)
curl -X POST https://post.freesurf.tools/api/reply \
  -H "Authorization: Bearer fsp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platform":"x","postId":"","commentId":"","text":"Thanks for the note!"}'

postId is the recorded postId of the original post (its per-platform result from GET /api/posts/recent). Works on X and Bluesky today.

Platform keys you can pass in platforms:

Key       Platform
--------  -----------
x         X / Twitter
linkedin  LinkedIn
facebook  Facebook
instagram Instagram
threads   Threads
tiktok    TikTok
youtube   YouTube
bluesky   Bluesky
reddit    Reddit
pinterest Pinterest
slack     Slack
discord   Discord
google_business Google Business

Reddit, Pinterest, Slack, Discord, and Google Business can be connected in Accounts. When posting to them, pass the required target: platformTargets = {"discord":"channelId","slack":"channelId","pinterest":"boardName","reddit":"r/example"}.

Source: X (metered at cost)

Credits endpoints:

curl https://post.freesurf.tools/api/credits \
  -H "Authorization: Bearer fsp_live_..."

curl -X POST https://post.freesurf.tools/api/credits/topup \
  -H "Authorization: Bearer fsp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amountCents":500}'   # returns a Stripe Checkout URL

Daily limits per social account.

Source: daily limits per connected account.

{"error":"Invalid JSON body"} (400) — usually a client-side quoting problem. PowerShell 5.1 corrupts embedded quotes when you pass -d as an argument; pipe the body through stdin instead (-d "@-") or write it to a file (-d @body.json). Keep captions ASCII — emoji/non-ASCII in a PowerShell -d argument also mangles the JSON.

{"error":"teamId or team is required"} (400) — every post and schedule needs a team, by name ("team": "Personal") or id ("teamId": "..."). Get ids from GET /api/teams.

401 Unauthorized — missing, revoked, or wrong-position API key. Send it as Authorization: Bearer fsp_live_... or FSP-API-KEY: fsp_live_....

{"error":"Unsupported file type"} (400) on upload — the file extension isn't in the supported list (jpg/jpeg/png/gif/mp4/mov/pdf). The type is inferred from the filename, so name the file with the right extension.

X: Insufficient X credit — X is metered ($0.015 plain, $0.20 with a link). Top up in the X fees tab.

Comment create: Request Validation Error (400) — a required field is missing (commonly the post id). The error message names the missing field.

{"error":"Unknown platform"} (400) — the platform key isn't supported (see the platform list above).