Quickstart

01

Before you start

Every request goes to https://app.reelspan.com/api. You need a Reelspan account, and the API speaks the same endpoints, fields and responses as Upload-Post: if you already have scripts or n8n flows for it, change the base URL and the key and they keep working.

Prefer an AI agent to do the calling? Connect Claude or ChatGPT through the MCP server instead.

02

Create an API key

In the dashboard, open API keys and create one. Copy it straight away: Reelspan stores only a hash, so it is shown once. Keys start with rs_live_.

Keep it in an environment variable, never in code you commit:

export REELSPAN_KEY="rs_live_…"

Send it on every request as Authorization: Apikey $REELSPAN_KEY. Authentication covers scopes, profile-limited keys and expiry.

03

Add a profile and connect accounts

A profile is one brand or client, with one account per platform. Create one with a username you’ll use in every call:

curl -X POST https://app.reelspan.com/api/uploadposts/users \
  -H "Authorization: Apikey $REELSPAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-brand"}'

Then connect its accounts in the dashboard under Accounts, or create a connect link for someone else (a client, say) to connect their own accounts without a Reelspan login. The link works for 48 hours:

curl -X POST https://app.reelspan.com/api/uploadposts/users/generate-jwt \
  -H "Authorization: Apikey $REELSPAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-brand"}'

04

Publish a video

Send the file (or a public URL) once, with the profile and the platforms. Each platform gets the video in its own shape:

curl -X POST https://app.reelspan.com/api/upload \
  -H "Authorization: Apikey $REELSPAN_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "platform[]=youtube" \
  -F "platform[]=instagram" \
  -F "title=Golden hour, no filter" \
  -F "[email protected]"

The fields you’ll use most:

user

The profile’s username. Required.

platform[]

One per platform: tiktok, youtube, instagram, facebook, x, threads, linkedin, pinterest, bluesky. Required.

video

The file, or a public URL. video_url also works.

title

The caption. {platform}_title overrides it for one platform, e.g. youtube_title.

description

The longer text where a platform has one (YouTube, Facebook, LinkedIn).

first_comment

Posted as the first comment right after the post goes live. {platform}_first_comment overrides it.

scheduled_date

ISO 8601 time in the future (up to 365 days), with timezone (IANA, default UTC).

add_to_queue

true puts the post in the profile’s next free queue slot instead of a set time.

async_upload

true returns at once with a request_id instead of waiting for the results.

/api/upload_photos takes photos[] (up to 35) and /api/upload_text takes text posts. The API reference lists every field.

05

Read the results

The call waits up to about a minute for the platforms and answers with one result each. A failure on one platform never stops the others:

{
  "success": true,
  "request_id": "post_8fK2…",
  "results": {
    "tiktok":    { "success": true, "url": "https://www.tiktok.com/@…", "post_id": "73…" },
    "youtube":   { "success": true, "url": "https://youtube.com/shorts/…", "post_id": "dQw…" },
    "instagram": { "success": false, "error": "…", "error_code": "instagram_processing_timeout" }
  },
  "usage": { "count": 3, "limit": null, "last_reset": "2026-11-01T00:00:00.000Z" }
}

When a platform takes longer (or you sent async_upload=true), you get the request_id straight away. Poll the status every 5 seconds or more, or skip polling and use webhooks:

curl "https://app.reelspan.com/api/uploadposts/status?request_id=post_8fK2…" \
  -H "Authorization: Apikey $REELSPAN_KEY"

Something failed? Errors lists every code. POST /api/uploadposts/posts/retry resends only the platforms that failed.

06

Schedule instead

Add a time and the post waits for it. The answer is 202 with a job_id you can edit or cancel until a minute before it goes out:

curl -X POST https://app.reelspan.com/api/upload \
  -H "Authorization: Apikey $REELSPAN_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "title=Tomorrow at nine" \
  -F "[email protected]" \
  -F "scheduled_date=2026-11-08T09:00:00" \
  -F "timezone=America/New_York"

GET /api/uploadposts/schedule

Every post waiting to go out.

PATCH /api/uploadposts/schedule/{job_id}

Change its time, caption or fields.

DELETE /api/uploadposts/schedule/{job_id}

Cancel it; its upload credits come back.

07

Next steps