# Introduction

> Reelspan is one API that publishes your videos, photos and text to 22 social networks, schedules them, and tells you how each post did.

Reelspan turns "post this everywhere" into one HTTP request. You send a video (or photos, or text) once, name the networks, and Reelspan uploads it to each one in the format that network wants, then reports a result per network: the live post's URL, or exactly why it failed.

## What you can do

- **Publish** videos, photo carousels, text and LinkedIn documents to TikTok, YouTube, Instagram, Facebook, X, Threads, LinkedIn, Pinterest, Bluesky, Reddit, Google Business, Telegram, Discord, Slack, Mastodon, Nostr, Lemmy, Dev.to, Hashnode, WordPress, Whop and Listmonk.
- **Schedule** a post for later, drop it in a profile's posting queue, or repeat it every day, week or month.
- **Follow up**: check status, retry only the networks that failed, add a first comment, get a webhook when each post goes live.
- **Measure**: account and post analytics, daily history, best times to post, and branded reports.
- **Manage many brands**: each *profile* holds one account per network. Connect your own accounts in the dashboard, or send your clients a white-label link to connect theirs.

## How it works

1. **Get an API key** in the dashboard (Developers → API keys). Use a test key (`rs_test_…`) to try everything without publishing.
2. **Create a profile** and **connect accounts** to it, in the dashboard or through the API.
3. **Post** with `POST /v1/posts/video` (or `photos`, `text`, `document`), naming the profile as `user` and the networks in `platform[]`.
4. **Read the result** in the response, poll `GET /v1/posts/status`, or receive a webhook.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user": "my-brand", "platform": ["x", "bluesky", "threads"], "title": "Hello from Reelspan"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan(); // reads REELSPAN_API_KEY
await reelspan.posts.text({ user: 'my-brand', platforms: ['x', 'bluesky', 'threads'], title: 'Hello from Reelspan' });
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()  # reads REELSPAN_API_KEY
reelspan.posts.text("my-brand", ["x", "bluesky", "threads"], "Hello from Reelspan")
```

## Ways to use it

| You are… | Start with |
| --- | --- |
| Writing code | The [Quickstart](/quickstart), then the [Node.js or Python SDK](/sdks) |
| Using a no-code tool | [n8n](/integrations/n8n), [Make](/integrations/make), [Zapier](/integrations/zapier) or [Airtable](/integrations/airtable) |
| Building with AI agents | The [MCP server](/integrations/mcp), or one of the [agent frameworks](/integrations/langchain) |
| Moving from Upload-Post | [Migrate from Upload-Post](/migrate-from-upload-post): the same request shapes |

## Good to know

- **Base URL:** `https://api.reelspan.com/v1`. Every request carries `Authorization: Bearer <your key>`.
- **Per-network results:** one network failing never fails the others. Each has its own `success`, `url` and `error_code`.
- **Safe retries:** send an `Idempotency-Key` header and a retried request never posts twice. The SDKs do it for you.
- **Machine-readable:** the [OpenAPI spec](https://api.reelspan.com/openapi.json), [llms.txt](/llms.txt) and every page as Markdown (add `.md` to any URL).

Source: https://docs.reelspan.com/introduction

---

# Quickstart

> Go from no API key to a live post in a few minutes. Create a key and a profile, connect an account, publish, and read each network's result.

This guide takes you from nothing to a published post. You need a Reelspan account; everything else happens here.

## 1. Create an API key

In the dashboard, open **Developers → API keys** and create a key. Copy it straight away: Reelspan keeps only a hash, so the key is shown once.

- A **live key** starts with `rs_live_` and publishes for real.
- A **test key** starts with `rs_test_`. Every request goes through the same checks, but nothing reaches the networks and nothing counts against your plan (up to 500 test posts a day). Use one while you build. See [Test mode](/guides/test-mode).

Keep the key in an environment variable, never in code you commit. The SDKs read `REELSPAN_API_KEY` on their own:

```bash
export REELSPAN_API_KEY="rs_test_…"
```

Check it works:

```bash title="cURL"
curl https://api.reelspan.com/v1/me \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan(); // reads REELSPAN_API_KEY
console.log(await reelspan.me());
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()  # reads REELSPAN_API_KEY
print(reelspan.me())
```

The answer names your plan and this month's usage. A `401` means the key is wrong, expired or revoked. The SDKs install with `npm install reelspan` and `pip install reelspan`; see [SDKs](/sdks).

## 2. Create a profile

A profile is one brand or client. It holds one connected account per network, and every post names it as `user`.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/profiles \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-brand", "display_name": "My Brand"}'
```

```javascript title="Node.js"
await reelspan.profiles.create('my-brand', 'My Brand');
```

```python title="Python"
reelspan.profiles.create("my-brand", "My Brand")
```

The username can't be changed later; the display name can. See [Profiles](/api/profiles).

## 3. Connect an account

Pick whichever fits:

- **In the dashboard:** open **Accounts**, choose the profile and connect a network. This is the quickest way to connect your own accounts.
- **With a connect link:** for a client who should connect their own accounts without a Reelspan login. The link works for 48 hours. See [White-label connect](/white-label).
- **With credentials:** networks that use a token or webhook instead of a sign-in (Discord, Telegram, Slack, Mastodon, Bluesky and others) can be connected straight from your code. See [Connect with credentials](/api/connect-credentials).

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/connect-links \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-brand"}'
```

```javascript title="Node.js"
const { access_url } = await reelspan.connect.link('my-brand');
```

```python title="Python"
access_url = reelspan.connect.link("my-brand")["access_url"]
```

Send `access_url` to whoever owns the accounts. [Connecting accounts](/connecting-accounts) covers every option.

> [!TIP]
> No account connected yet? Post to `sandbox` instead of a real network. It needs no connection, reads the media like a real network would and answers with a pretend URL, so you can try the whole flow first. With a live key a sandbox post still counts as an upload.

## 4. Publish your first post

Send the video once, with the profile in `user` and one `platform[]` field per network. Reelspan uploads it to each network in the format that network wants.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "platform[]=youtube" \
  -F "platform[]=instagram" \
  -F "title=Golden hour, no filter" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['tiktok', 'youtube', 'instagram'],
  title: 'Golden hour, no filter',
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video("my-brand", ["tiktok", "youtube", "instagram"], "launch.mp4", "Golden hour, no filter")
```

The fields you'll use most:

| Field | What it does |
| --- | --- |
| `user` | The profile's username. Required. |
| `platform[]` | One per network. Required. |
| `video` | The file, or a public https URL (Google Drive and Dropbox share links work). |
| `title` | The caption. `{network}_title` (for example `youtube_title`) overrides it on one network. YouTube needs a title. |
| `description` | The longer text, where a network has one. |
| `first_comment` | Posted as the first comment right after the post goes live. |
| `scheduled_date` | An ISO 8601 time up to 365 days ahead, with `timezone` (IANA, default UTC). |
| `add_to_queue` | `true` takes the profile's next free queue slot. |

Photos, text and LinkedIn documents work the same way: [Post photos](/api/post-photos), [Post text](/api/post-text), [Post a document](/api/post-document). Every field for videos is on [Post a video](/api/post-video).

## 5. Read the result

The request waits up to 59 seconds for the networks and answers with one result each. One network failing never stops the others:

```json
{
  "success": true,
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "results": {
    "tiktok": { "success": true, "url": "https://www.tiktok.com/@mybrand/video/7441…", "post_id": "7441…" },
    "youtube": { "success": true, "url": "https://youtube.com/shorts/aB3…", "post_id": "aB3…" },
    "instagram": {
      "success": false,
      "skipped": true,
      "skip_reason": "profile_platform_not_configured",
      "failure_stage": "profile_platform_validation",
      "error": "Profile my-brand has no Instagram account configured",
      "error_code": "profile_platform_mapping_invalid"
    }
  },
  "usage": { "count": 2, "limit": null, "last_reset": "2026-11-01T00:00:00.000Z" }
}
```

Here Instagram was skipped because the profile has no Instagram account; a skipped network isn't charged.

If a network takes longer, or you sent `async_upload=true`, the answer has a `message` and the `request_id` instead of `results`, and the work carries on in the background. Poll the status every 5 seconds or more:

```bash title="cURL"
curl "https://api.reelspan.com/v1/posts/status?request_id=9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const status = await reelspan.posts.wait(post.request_id); // polls until every network has finished
```

```python title="Python"
status = reelspan.posts.wait(post["request_id"])  # polls until every network has finished
```

Or skip polling and let a [webhook](/webhooks) tell your server as each network finishes. If something failed, [Errors](/errors) explains the code, and [Retry](/api/retry) sends only the failed networks again without uploading the video twice.

## Next steps

- [API overview](/api/overview): base URL, errors, rate limits, idempotency and ids.
- [Scheduling and repeats](/guides/scheduling), then [Scheduled posts](/api/scheduled-posts) to edit or cancel them.
- [Webhooks](/webhooks) for results without polling.
- [Upload media](/api/upload-media) to send a file once and post it many times, or files over 100 MB.
- The [MCP server](/integrations/mcp) if you'd rather have an AI agent do the calling.

Source: https://docs.reelspan.com/quickstart

---

# API overview

> How the Reelspan API works - base URL, API keys, multipart and JSON bodies, response and error shapes, status codes, idempotency, rate limits, paging and ids.

The Reelspan API is plain HTTPS and JSON. This page covers the rules every endpoint shares; each endpoint's own page covers its fields.

## Base URL

```text
https://api.reelspan.com/v1
```

Every endpoint lives under `/v1`. The machine-readable [OpenAPI document](https://api.reelspan.com/openapi.json) describes all of them, and the [API reference](/reference) is built from it.

> [!NOTE]
> Send API keys to `api.reelspan.com`. The dashboard's own address (`app.reelspan.com`) answers a request made with an API key with **421** and `error_code: "USE_API_HOST"`, naming the right address.

## Authentication

Send your key in the `Authorization` header on every request:

```bash
curl https://api.reelspan.com/v1/me \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

`Authorization: Apikey $REELSPAN_API_KEY` works too, as Upload-Post clients send it. Create keys in the dashboard under **Developers → API keys**. A key can be limited in two ways:

- **Scopes:** `publish`, `read`, `profiles`, `analytics` and `webhooks`. A call outside the key's scopes gets **403** with `error_code: "INSUFFICIENT_SCOPE"`.
- **Profiles:** a key limited to some profiles gets **403** `PROFILE_FORBIDDEN` for any other profile, and posts or jobs of other profiles answer **404** as if they didn't exist.

A missing, wrong, revoked or expired key gets **401**. After 10 failed attempts from one IP address in 5 minutes, that address gets **429** with `error_code: "AUTH_RATE_LIMITED"` and `Retry-After: 300`. More in [Authentication](/authentication).

## Request formats

| Endpoint | Body |
| --- | --- |
| `POST /v1/posts/video`, `/photos`, `/document` | `multipart/form-data`: files and form fields together |
| `POST /v1/posts/text`, `POST /v1/youtube/thumbnail` | JSON or `multipart/form-data` |
| `POST /v1/media/upload` | `multipart/form-data`, one field named `file` |
| Everything else | JSON body (`Content-Type: application/json`) or query parameters |

In multipart forms:

- **Lists** repeat the field with `[]` in its name: `-F "platform[]=tiktok" -F "platform[]=youtube"`.
- **Booleans** are the strings `true` or `false`.
- **Media** can be a file or a public https URL in the same field, or the `media_id` of a file you [uploaded earlier](/api/upload-media).

In JSON (text posts), send the list as `"platform": ["x", "bluesky"]`; `"platform[]"` works too.

## Responses

A successful answer has `"success": true` and the data at the top level:

```json
{ "success": true, "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1", "results": { "…": "…" } }
```

An error has `"success": false`, a readable `message`, and usually a machine-readable `error_code` to branch on. Some errors add fields, such as `usage` on a monthly-limit error or `invalid_platforms` when none of the networks can be used:

```json
{ "success": false, "message": "This API key does not have the \"publish\" scope", "error_code": "INSUFFICIENT_SCOPE" }
```

An unexpected server error is `{ "success": false, "error": "Internal server error" }` with **500**. [Errors](/errors) lists the codes.

## Per-network results

A post to several networks never fails as a whole because one network did. When a post finishes within the request, `results` holds one object per network:

```json
{
  "success": true,
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "results": {
    "tiktok": { "success": true, "url": "https://www.tiktok.com/@mybrand/video/7441…", "post_id": "7441…" },
    "x": { "success": true, "url": "https://x.com/mybrand/status/18…", "post_id": "18…", "warnings": ["The text was posted as a thread of 2 posts."] },
    "pinterest": { "success": false, "error": "…", "error_code": "…" }
  },
  "usage": { "count": 41, "limit": null, "last_reset": "2026-11-01T00:00:00.000Z" }
}
```

- `success`, `url` and `post_id` say where it went live.
- `error` and `error_code` say why it didn't.
- `warnings` lists anything changed on the way (links removed on X, a long text split into a thread, a first comment that couldn't be posted).
- `skipped: true` with a `skip_reason` means the network was never tried, for example because the profile has no account on it. Skipped networks aren't charged.

The top-level `success` only says the request was accepted, so always read each network's own `success`. [Post status](/api/post-status) returns the same results as a list.

## Status codes

| Code | Meaning |
| --- | --- |
| `200` | Done. For a post: finished (with `results`) or moved to the background (with `request_id`). |
| `201` | Created (a profile, an approval link). |
| `202` | Scheduled or queued: the answer carries a `job_id`. |
| `400` | Something in the request is wrong; `message` says what. |
| `401` | No key, or the key is invalid, revoked or expired. |
| `403` | The key lacks the scope or the profile, or the workspace is suspended. |
| `404` | The profile, post, job or file doesn't exist (or the key can't see it). |
| `409` | A conflict: the same `Idempotency-Key` still running, a `request_id` already used, a scheduled post already publishing, nothing to retry, or an account that must be reconnected (`reauth_required`). |
| `413` | The file is larger than your plan allows. |
| `421` | An API key was sent to the dashboard's address instead of `api.reelspan.com`. |
| `429` | Rate limit, monthly upload limit, or the daily test-post limit. |
| `500` | Reelspan's fault. Safe to retry with an `Idempotency-Key`. |
| `502` | A network refused or didn't answer: a lookup (Pinterest boards, TikTok creator info, Facebook Page details…) or a change to a live post ([unpublish](/api/unpublish), [edit](/api/edit-post), [repost](/api/repost)). `error_code` says why. |

## Idempotency

Networks drop, and a retried POST could publish twice. Send an `Idempotency-Key` header (any string up to 200 characters, such as a UUID) on the four publish endpoints, and a repeat with the same key returns the first request's result instead of posting again:

```bash
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Idempotency-Key: 6f1c2a7e-weekly-tip-48" \
  -H "Content-Type: application/json" \
  -d '{"user": "my-brand", "platform": ["x"], "title": "Weekly tip"}'
```

- A key is remembered for 24 hours, per workspace and per kind of post (video, photos, text, document).
- A replay answers with the first request's current state, the header `Idempotent-Replayed: true` and `"idempotent_replay": true` in the body.
- While the first request with a key is still open (including its wait of up to 59 seconds for results), a second one gets **409** `IDEMPOTENCY_KEY_IN_USE`. Wait a few seconds and send it again.
- `X-Idempotency-Key` works as another name for the header.
- `X-Request-Id` is a third name, used only when neither of the others is sent, and it also becomes the post's `request_id` (below).

You can also pick the post's id yourself: send `request_id` (8 to 100 letters, digits, `_` or `-`), as a field or as the `X-Request-Id` header, and you can poll it even if the answer never arrived. A header in any other shape (a proxy's own trace id, say) is ignored. Reusing a `request_id` gets **409** `REQUEST_ID_IN_USE`. The SDKs add an `Idempotency-Key` to every post for you. See [Retrying safely](/guides/idempotency).

## Rate limits

Each workspace has a request limit per minute and per 10 minutes, set by its plan ([Plans and limits](/limits/plans)). Every answer to an API-key request carries the window closest to running out:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Requests allowed in the window |
| `X-RateLimit-Remaining` | Requests left in it |
| `X-RateLimit-Reset` | When it resets, in Unix seconds |

Past the limit you get **429** with `error_code: "RATE_LIMITED"` and a `Retry-After` header in seconds. The monthly upload limit (Free plan) is separate: a post that would go over it gets **429** with your `usage`. See [Rate limits](/rate-limits).

## Paging

List endpoints page in one of three ways:

| Endpoint | Parameters | Done when |
| --- | --- | --- |
| [History](/api/history) `GET /v1/posts` | `page` (from 1) and `limit` (10, 20, 50 or 100) | `page × limit ≥ total` |
| [Scheduled posts](/api/scheduled-posts) `GET /v1/scheduled` | `offset` and `limit` (1 to 200, default 50) | `offset + limit ≥ total` |
| [Media library](/api/library) `GET /v1/library` | `limit` (1 to 100) and `before` | `next_before` is `null`; otherwise pass it as `before` |

[Webhook deliveries](/webhooks) and approval links return the newest entries only, without pages.

## Ids

| Id | Looks like | What it names |
| --- | --- | --- |
| `request_id` | `9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1` (or your own) | One post request, across all its networks. Use it for status, retry, history and post analytics. |
| `job_id` | `sched_5d0e…` | A scheduled or queued post. Use it to read, edit or cancel it. A scheduled post has a `request_id` too. |
| `media_id` | `med_…` | A file uploaded with [Upload media](/api/upload-media), to post or keep in the library. |
| `external_id` | yours | Any id from your own system (up to 255 characters), sent with a post (as a field or the `X-External-Id` header) and returned in history, status and webhooks. |

## Test keys

A test key (`rs_test_…`) runs every check a live key does, then simulates the post: each network comes back `success: true` with a `post_id` that starts with `test_` and no `url`, and status answers carry `"test": true`. Nothing reaches the networks and nothing counts against your plan. A workspace can send 500 test posts a day; past that the answer is **429** `TEST_LIMIT`.

A test post still needs the networks connected to the profile, as a real post would. To try things with nothing connected, post to the `sandbox` network. See [Test mode](/guides/test-mode).

Source: https://docs.reelspan.com/api/overview

---

# SDKs

> The official Reelspan clients for Node.js, TypeScript and Python - install, configure, call every endpoint, and get retries, idempotent posts and webhook checks built in.

Reelspan has official clients for Node.js (with TypeScript types) and Python. Both cover every endpoint, have no dependencies, retry what is safe to retry, and never publish a post twice.

| | Node.js | Python |
| --- | --- | --- |
| Package | `reelspan` on npm | `reelspan` on PyPI |
| Runs on | Node 20+, Deno, Bun, edge runtimes; ESM and CommonJS | Python 3.10+, standard library only |
| Licence | MIT | MIT |

## Install

```bash title="Node.js"
npm install reelspan
```

```bash title="Python"
pip install reelspan
```

## Configure

Both clients read the key from `REELSPAN_API_KEY`, so most code needs no options:

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan({
  apiKey: process.env.REELSPAN_API_KEY, // the default
  baseUrl: 'https://api.reelspan.com', // or REELSPAN_BASE_URL
  timeoutMs: 120_000, // per attempt
  maxRetries: 2,
  headers: { 'x-my-app': 'scheduler' }, // sent on every request
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan(
    api_key=None,  # None reads REELSPAN_API_KEY
    base_url="https://api.reelspan.com",  # or REELSPAN_BASE_URL
    timeout=120,  # seconds per attempt
    max_retries=2,
    headers={"X-My-App": "scheduler"},  # sent on every request
)
```

Without a key, the constructor throws. Use a test key (`rs_test_…`) to run everything without publishing; see [Test mode](/guides/test-mode).

Node also takes `fetch` (your own, for proxies or tests) and `directUploadBytes`; Python takes `direct_upload_bytes`. Files at or above that size (90 MB by default) go to storage in parts, as described under [Upload media](/api/upload-media).

## Files

Anywhere a call takes a file:

- **Node:** `{ data, name, type }` with the bytes, a `Blob` or `File`, or a public https URL as a string.
- **Python:** a path, a `(name, bytes)` or `(name, bytes, content_type)` tuple, or a public https URL.

Google Drive and Dropbox share links work as URLs.

## Posts

`posts` publishes and follows up. Every post gets an `Idempotency-Key` on its own (pass `idempotencyKey` / `idempotency_key` to choose it). Network settings go in `extra`, with the same names as the API fields.

```javascript title="Node.js"
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['tiktok', 'youtube'],
  title: 'Launch day',
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: { privacy_level: 'PUBLIC_TO_EVERYONE', youtube_title: 'Launch day, in 60 seconds' },
});

await reelspan.posts.photos({ user: 'my-brand', platforms: ['instagram'], title: 'New colours', photos: ['https://example.com/photo1.jpg'], altTexts: ['A red mug'] });
await reelspan.posts.text({ user: 'my-brand', platforms: ['x', 'bluesky'], title: 'We shipped it.' });
await reelspan.posts.document({ user: 'my-brand', platforms: ['linkedin'], title: 'Q3 report', document: 'https://example.com/q3.pdf' });
```

```python title="Python"
post = reelspan.posts.video(
    "my-brand", ["tiktok", "youtube"], "launch.mp4", "Launch day",
    extra={"privacy_level": "PUBLIC_TO_EVERYONE", "youtube_title": "Launch day, in 60 seconds"},
)

reelspan.posts.photos("my-brand", ["instagram"], ["photo1.jpg"], "New colours", alt_texts=["A red mug"])
reelspan.posts.text("my-brand", ["x", "bluesky"], "We shipped it.")
reelspan.posts.document("my-brand", "q3.pdf", "Q3 report")
```

Common options on every post: `scheduledDate` / `scheduled_date`, `timezone`, `addToQueue` / `add_to_queue`, `async` / `run_async`, `firstComment` / `first_comment`, `repeatEvery` and `repeatTimes` / `repeat_every` and `repeat_times`, `externalId` / `external_id`, and `description`.

Then follow up:

```javascript title="Node.js"
const { request_id } = await reelspan.posts.video({ user: 'my-brand', platforms: ['youtube'], video, title: 'Long one', async: true });
const done = await reelspan.posts.wait(request_id); // polls status until every network has finished
await reelspan.posts.retry(request_id, ['youtube']); // sends failed networks again
const status = await reelspan.posts.status({ requestId: request_id });

for await (const row of reelspan.posts.all({ platform: 'tiktok', status: 'failed' })) console.log(row.post_url);
```

```python title="Python"
request_id = reelspan.posts.video("my-brand", ["youtube"], "long.mp4", "Long one", run_async=True)["request_id"]
done = reelspan.posts.wait(request_id)  # polls status until every network has finished
reelspan.posts.retry(request_id, ["youtube"])  # sends failed networks again
status = reelspan.posts.status(request_id=request_id)

for row in reelspan.posts.all(platform="tiktok", status="failed"):
    print(row["post_url"])
```

`posts.history` returns one page; `posts.all` walks every page for you. See [Post status](/api/post-status), [History](/api/history) and [Retry](/api/retry).

## Profiles and accounts

`profiles` manages brands; `accounts` connects and disconnects networks that use credentials; `connect` makes hosted links and OAuth starts for people without a Reelspan login.

```javascript title="Node.js"
await reelspan.profiles.create('client-a', 'Client A');
const { profiles } = await reelspan.profiles.list();

await reelspan.accounts.connect('client-a', 'discord', { webhook_url: 'https://discord.com/api/webhooks/…' });
await reelspan.accounts.disconnect('client-a', 'discord');

const { access_url } = await reelspan.connect.link('client-a', { redirect_url: 'https://example.com/done' });
const { authorize_url } = await reelspan.connect.oauthStart('tiktok', { profile: 'client-a' });
```

```python title="Python"
reelspan.profiles.create("client-a", "Client A")
profiles = reelspan.profiles.list()["profiles"]

reelspan.accounts.connect("client-a", "discord", webhook_url="https://discord.com/api/webhooks/…")
reelspan.accounts.disconnect("client-a", "discord")

access_url = reelspan.connect.link("client-a", redirect_url="https://example.com/done")["access_url"]
authorize_url = reelspan.connect.oauth_start("tiktok", profile="client-a")["authorize_url"]
```

Also: `profiles.get`, `profiles.rename`, `profiles.delete` and `connect.validate(token)`. See [Profiles](/api/profiles), [Connect with credentials](/api/connect-credentials) and [White-label connect](/white-label).

## Scheduled posts

```javascript title="Node.js"
const list = await reelspan.scheduled.list({ profile_username: 'my-brand' });
await reelspan.scheduled.edit('sched_5d0e…', { scheduled_date: '2026-12-01T09:00:00', timezone: 'Europe/London' });
await reelspan.scheduled.cancel('sched_5d0e…', { withLaterRepeats: true });
```

```python title="Python"
scheduled = reelspan.scheduled.list(profile_username="my-brand")
reelspan.scheduled.edit("sched_5d0e…", scheduled_date="2026-12-01T09:00:00", timezone="Europe/London")
reelspan.scheduled.cancel("sched_5d0e…", with_later_repeats=True)
```

Also `scheduled.get(jobId)`. See [Scheduled posts](/api/scheduled-posts).

## Queue

```javascript title="Node.js"
await reelspan.queue.setSettings('my-brand', { timezone: 'Europe/London', slots: [{ hour: 9, minute: 0 }, { hour: 17, minute: 30 }] });
const { next_slot } = await reelspan.queue.nextSlot('my-brand');
```

```python title="Python"
reelspan.queue.set_settings("my-brand", timezone="Europe/London", slots=[{"hour": 9, "minute": 0}, {"hour": 17, "minute": 30}])
next_slot = reelspan.queue.next_slot("my-brand")["next_slot"]
```

Also `queue.settings`, `queue.preview`, `queue.markFull` / `mark_full` and `queue.markOpen` / `mark_open`. See [Queue](/api/queue).

## Media and library

`media.upload` uploads a file once and returns its `media_id`. Files from 90 MB go straight to storage in parts, three at a time, each part retried on its own; Python reads the file from disk piece by piece. `library` keeps files to post again.

```javascript title="Node.js"
const media = await reelspan.media.upload(
  { data: await readFile('film.mp4'), name: 'film.mp4', type: 'video/mp4' },
  { kind: 'video', onProgress: (sent, total) => console.log(Math.round((sent / total) * 100), '%') },
);
await reelspan.posts.video({ user: 'my-brand', platforms: ['youtube'], title: 'The film', videoMediaId: media.media_id });

await reelspan.library.keep([media.media_id], 'The film');
const page = await reelspan.library.list({ kind: 'video' });
```

```python title="Python"
media = reelspan.media.upload("film.mp4", kind="video", on_progress=lambda sent, total: print(f"{sent * 100 // total}%"))
reelspan.posts.video("my-brand", ["youtube"], title="The film", video_media_id=media["media_id"])

reelspan.library.keep([media["media_id"]], "The film")
page = reelspan.library.list(kind="video")
```

Also `library.import` / `import_url` (from a share link), `library.remove` and `library.fileUrl` / `file_url` (a short-lived download link). See [Upload media](/api/upload-media) and [Media library](/api/library).

## Analytics

```javascript title="Node.js"
const totals = await reelspan.analytics.account('my-brand');
const best = await reelspan.analytics.bestTimes('my-brand', { timezone: 'Europe/London' });
```

```python title="Python"
totals = reelspan.analytics.account("my-brand")
best = reelspan.analytics.best_times("my-brand", timezone="Europe/London")
```

Also `analytics.history`, `analytics.post(requestId)` and `analytics.report(username, days)`. See [Analytics](/api/analytics), [Best times to post](/api/best-times) and [Reports](/api/reports).

## Approvals

```javascript title="Node.js"
const { approval_link } = await reelspan.approvals.create({ user: 'my-brand', jobIds: ['sched_5d0e…'], title: 'December posts' });
console.log(approval_link.url); // send this to the client
```

```python title="Python"
link = reelspan.approvals.create("my-brand", ["sched_5d0e…"], title="December posts")["approval_link"]
print(link["url"])  # send this to the client
```

Also `approvals.list` and `approvals.delete`. See [Approval links](/api/approval-links).

## AI captions

Each call uses one AI credit.

```javascript title="Node.js"
const captions = await reelspan.ai.writeCaptions({ text: 'We opened a second shop in Leeds', platforms: ['instagram', 'x', 'linkedin'] });
```

```python title="Python"
captions = reelspan.ai.write_captions(text="We opened a second shop in Leeds", platforms=["instagram", "x", "linkedin"])
```

Also `ai.captionsFromVideo` / `captions_from_video` and `ai.rewriteCaptions` / `rewrite_captions`. See [AI captions](/api/ai-captions).

## Pinterest boards

```javascript title="Node.js"
const { board } = await reelspan.pinterest.createBoard('my-brand', 'Spring range');
```

```python title="Python"
board = reelspan.pinterest.create_board("my-brand", "Spring range")["board"]
```

## Webhooks

`webhooks` sets the account webhook and reads its deliveries; `webhooks.profile` sets a profile's own.

```javascript title="Node.js"
await reelspan.webhooks.set('https://example.com/reelspan', ['upload_completed']);
await reelspan.webhooks.profile.set('client-a', 'https://client-a.example.com/hooks');
const { deliveries } = await reelspan.webhooks.deliveries();
```

```python title="Python"
reelspan.webhooks.set("https://example.com/reelspan", ["upload_completed"])
reelspan.webhooks.profile.set("client-a", "https://client-a.example.com/hooks")
deliveries = reelspan.webhooks.deliveries()["deliveries"]
```

Also `get`, `delete`, `test`, `redeliver(deliveryId)` and `rotateSecret` / `rotate_secret`. To check that a delivery came from Reelspan, use `verifyWebhook` / `verify_webhook` with the raw body and the two signature headers:

```javascript title="Node.js"
import express from 'express';
import { verifyWebhook } from 'reelspan';

const app = express();
app.post('/reelspan', express.raw({ type: 'application/json' }), async (req, res) => {
  const ok = await verifyWebhook(req.body.toString(), req.get('x-reelspan-signature'), req.get('x-reelspan-timestamp'), process.env.REELSPAN_WEBHOOK_SECRET);
  if (!ok) return res.sendStatus(401);
  res.sendStatus(200);
  // handle JSON.parse(req.body) after answering
});
```

```python title="Python"
import os
from flask import Flask, request
from reelspan import verify_webhook

app = Flask(__name__)

@app.post("/reelspan")
def reelspan_hook():
    ok = verify_webhook(request.get_data(), request.headers.get("X-Reelspan-Signature"), request.headers.get("X-Reelspan-Timestamp"), os.environ["REELSPAN_WEBHOOK_SECRET"])
    if not ok:
        return "", 401
    return "", 200
```

Both reject a timestamp more than 5 minutes away from now (change it with the last argument). See [Webhooks](/webhooks).

## Anything else

`request` calls any endpoint with your key, the retries and the error handling:

```javascript title="Node.js"
const me = await reelspan.request('GET', '/v1/me');
await reelspan.request('POST', '/v1/posts/retry', { json: { request_id: requestId, fields: { tiktok_title: 'Shorter caption' } } });
```

```python title="Python"
me = reelspan.request("GET", "/v1/me")
reelspan.request("POST", "/v1/posts/retry", json_body={"request_id": request_id, "fields": {"tiktok_title": "Shorter caption"}})
```

`me()` and `platforms()` are shortcuts for the account and the list of networks.

## Retries

Both clients retry on their own, with exponential backoff and jitter (about 0.5 s, 1 s, 2 s, up to 8 s), or after the `Retry-After` the API sent (capped at 60 seconds):

- **What is retried:** network errors and timeouts, and answers `408`, `409`, `429` and `5xx`.
- **When:** `GET`, `PUT` and `DELETE` always; `POST` and `PATCH` only with an idempotency key. Posts and the multipart upload calls carry one, so they are safe. A `429` is retried for any method.
- **How many times:** `maxRetries` / `max_retries` (default 2), so up to three attempts. Set it per call in Node with `{ maxRetries }`.

The last rate limit the API reported is on `reelspan.rateLimit` (Node) or `reelspan.rate_limit` (Python): `limit`, `remaining` and `reset` (Unix seconds).

## Errors

An error answer raises `ReelspanError` with the HTTP status, the `error_code`, the full body and, when the API sent `Retry-After`, how many seconds it asked you to wait. A request that never got an answer raises `ReelspanConnectionError`.

```javascript title="Node.js"
import { ReelspanError, ReelspanConnectionError } from 'reelspan';

try {
  await reelspan.posts.text({ user: 'my-brand', platforms: ['x'], title: 'Hi' });
} catch (err) {
  if (err instanceof ReelspanError) console.log(err.status, err.code, err.message, err.retryAfter, err.body);
  else if (err instanceof ReelspanConnectionError) console.log('no answer:', err.message);
  else throw err;
}
```

```python title="Python"
from reelspan import ReelspanError, ReelspanConnectionError

try:
    reelspan.posts.text("my-brand", ["x"], "Hi")
except ReelspanError as e:
    print(e.status, e.code, e, e.retry_after, e.body)
except ReelspanConnectionError as e:
    print("no answer:", e)
```

`isRateLimited` / `is_rate_limited` is true for a 429. A network that fails inside a post is not an exception: it is a result with `success: false` in `results`. See [Errors](/errors).

Source: https://docs.reelspan.com/sdks

---

# Migrate from Upload-Post

> Move an Upload-Post integration to Reelspan - the endpoint map, the auth header change, the field names that differ, and what you gain on the way.

Reelspan takes the same request shapes as Upload-Post: the same form fields (`user`, `platform[]`, `title`, `scheduled_date`, `async_upload`, `{platform}_title` and the rest), the same per-network `results` in the answer, and webhooks with the same event names and payloads. Most integrations move by changing the base URL, the key and the paths.

## 1. Change the base URL and the key

| | Upload-Post | Reelspan |
| --- | --- | --- |
| Base URL | `https://api.upload-post.com/api` | `https://api.reelspan.com/v1` |
| Auth header | `Authorization: Apikey <key>` | `Authorization: Apikey <key>` or `Authorization: Bearer <key>` |

Reelspan reads both schemes, so the header can stay as it is: only the key changes. Create a key in the dashboard under **Developers → API keys**; see [Authentication](/authentication).

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "platform[]=youtube" \
  -F "title=Launch day" \
  -F "video=@launch.mp4"
```

## 2. Change the paths

Paths drop the `/uploadposts` prefix and use `/v1/...` names. Bodies and query parameters stay the same unless a note says otherwise.

### Publishing

| Upload-Post | Reelspan |
| --- | --- |
| `POST /api/upload` | [`POST /v1/posts/video`](/api/post-video) |
| `POST /api/upload_photos` | [`POST /v1/posts/photos`](/api/post-photos) |
| `POST /api/upload_text` | [`POST /v1/posts/text`](/api/post-text) |
| `POST /api/upload_document` | [`POST /v1/posts/document`](/api/post-document) |
| `GET /api/uploadposts/status` | [`GET /v1/posts/status`](/api/post-status) |
| `GET /api/uploadposts/history` | [`GET /v1/posts`](/api/history) |
| `POST /api/uploadposts/posts/retry` | [`POST /v1/posts/retry`](/api/retry) |
| `POST /api/uploadposts/posts/unpublish` | [`POST /v1/posts/unpublish`](/api/unpublish) |
| `POST /api/uploadposts/posts/edit` | [`POST /v1/posts/edit`](/api/edit-post) |
| `POST /api/uploadposts/posts/repost` | [`POST /v1/posts/repost`](/api/repost) |
| `POST /api/uploadposts/posts/save` | [`POST /v1/posts/save`](/networks/pinterest#save-a-pin-to-a-board) (Pinterest) |
| `POST /api/uploadposts/youtube/thumbnail` | [`POST /v1/youtube/thumbnail`](/api/youtube-thumbnail) |

### Scheduling and the queue

| Upload-Post | Reelspan |
| --- | --- |
| `GET /api/uploadposts/schedule` | [`GET /v1/scheduled`](/api/scheduled-posts) (pages of up to 200; 50 when you send no `limit`) |
| `GET /api/uploadposts/schedule/{job_id}` | `GET /v1/scheduled/{job_id}` |
| `PATCH /api/uploadposts/schedule/{job_id}` | `PATCH /v1/scheduled/{job_id}` |
| `GET /api/uploadposts/schedule/{job_id}/thumbnail` | `GET /v1/scheduled/{job_id}/thumbnail` (a **302** to the image; `?format=json` for the link) |
| `GET /api/uploadposts/schedule/{job_id}/preview` | `GET /v1/scheduled/{job_id}/preview` |
| `DELETE /api/uploadposts/schedule/{job_id}` | `DELETE /v1/scheduled/{job_id}` |
| `GET` / `POST /api/uploadposts/queue/settings` | [`GET` / `POST /v1/queue/settings`](/api/queue) |
| `GET /api/uploadposts/queue/preview` | `GET /v1/queue/preview` |
| `GET /api/uploadposts/queue/next-slot` | `GET /v1/queue/next-slot` |
| `POST` / `DELETE /api/uploadposts/queue/slot-full` | `POST` / `DELETE /v1/queue/slot-full` |

### Profiles and accounts

| Upload-Post | Reelspan |
| --- | --- |
| `GET /api/uploadposts/me` | [`GET /v1/me`](/api/me) |
| `GET` / `POST /api/uploadposts/users/preferences` | [`GET` / `POST /v1/preferences`](/api/preferences) (adds `timezone`) |
| `POST /api/uploadposts/users` | [`POST /v1/profiles`](/api/profiles) |
| `GET /api/uploadposts/users` | `GET /v1/profiles` |
| `GET /api/uploadposts/users/{username}` | `GET /v1/profiles/{username}` |
| `PATCH /api/uploadposts/users/{username}` | `PATCH /v1/profiles/{username}` |
| `DELETE /api/uploadposts/users` | `DELETE /v1/profiles` |
| `DELETE /api/uploadposts/users/social` | `DELETE /v1/accounts` (same `profile_username` and `social_platform`) |
| `POST /api/uploadposts/users/generate-jwt` | [`POST /v1/connect-links`](/white-label) (same body, same `access_url`, valid 48 hours) |
| `GET /api/uploadposts/users/validate-jwt` | `GET /v1/connect-links/validate` |
| `POST /api/uploadposts/users/discord/credentials`, `…/telegram/credentials` | [`POST /v1/accounts/{platform}`](/api/connect-credentials), one route for every credential network |
| `POST /api/uploadposts/oauth/{platform}/start` | `POST /v1/oauth/{platform}/start` |

### Lookups and analytics

| Upload-Post | Reelspan |
| --- | --- |
| `GET /api/uploadposts/facebook/pages` | [`GET /v1/facebook/pages`](/networks/facebook#choose-the-page) (`profile` is required) |
| `POST` / `DELETE /api/uploadposts/users/facebook-page` | `POST` / `DELETE /v1/facebook/page`; the chosen Page is `selected_page_id` in `GET /v1/facebook/pages` |
| `GET /api/uploadposts/facebook/page-info` | `GET /v1/facebook/page-info` |
| `GET /api/uploadposts/google-business/locations` | [`GET /v1/google-business/locations`](/networks/google-business#choose-the-location) |
| `POST` / `DELETE /api/uploadposts/users/google-business-location` | `POST` / `DELETE /v1/google-business/location`; the chosen location is `selected_location_id` in `GET /v1/google-business/locations` |
| `GET /api/uploadposts/pinterest/boards` | [`GET /v1/pinterest/boards`](/networks/pinterest) |
| `POST /api/uploadposts/pinterest/boards` | `POST /v1/pinterest/boards` (`name`, `description`, `privacy`) |
| `GET` / `POST /api/uploadposts/pinterest/boards/{board_id}/sections` | `GET` / `POST /v1/pinterest/boards/{board_id}/sections` |
| `GET /api/uploadposts/tiktok/settings` | `GET /v1/tiktok/creator-info` (the list is `privacy_options`, not `privacy_level_options`) |
| `GET /api/uploadposts/instagram/publishing_limit`, `…/threads/publishing_limit` | [`GET /v1/publishing-limits`](/api/publishing-limits) (both networks in one call, or `platform=`) |
| `GET /api/uploadposts/reddit/detailed-posts` | [`GET /v1/reddit/posts`](/networks/reddit#list-the-accounts-posts) |
| `GET /api/analytics/{profile_username}` | [`GET /v1/analytics/{profile_username}`](/api/analytics) (`days` adds `change`) |
| `GET /api/uploadposts/total-impressions/{profile_username}` | [`GET /v1/analytics/{profile_username}/impressions`](/api/analytics#total-impressions) |
| `GET /api/uploadposts/post-analytics/{request_id}` | `GET /v1/post-analytics/{request_id}` |
| `GET /api/uploadposts/post-analytics?platform_post_id=…` | [`GET /v1/post-analytics?platform_post_id=…`](/api/analytics#any-post-by-the-networks-id) (same `platform` and `user`) |

### Webhooks

| Upload-Post | Reelspan |
| --- | --- |
| `GET` / `POST` / `DELETE /api/uploadposts/users/notifications` | [`GET` / `POST` / `DELETE /v1/webhook`](/webhooks) |
| `POST /api/uploadposts/users/webhook-secret` | `POST /v1/webhook/secret` |
| `GET` / `POST` / `DELETE /api/uploadposts/users/profile-webhook` | `GET` / `POST` / `DELETE /v1/profile-webhook` |

## 3. Fields and headers that differ

| Upload-Post | Reelspan |
| --- | --- |
| `flair_id` (Reddit) | `reddit_flair_id`. `subreddit` works as before, and so does `reddit_subreddit`. |

The rest carry over as they are: the `X-Request-Id` and `X-External-Id` headers ([Retrying safely](/guides/idempotency#your-own-request-id)), the `gbp_*` Google Business fields including `EVENT` and `OFFER` posts, `facebook_media_type=VIDEO`, and PDF, PPT, PPTX, DOC and DOCX documents.

Network fields that Reelspan doesn't read are ignored, not refused, so check each network's page under [Networks](/networks/tiktok) for the fields it takes.

## 4. Update your webhook receiver

Event names (`upload_completed`, `social_account_connected`, `social_account_disconnected`, `social_account_reauth_required`) and payloads are the same; dotted spellings such as `social_account.connected` are accepted when you subscribe. The headers are renamed, and the signature is built the same way, an HMAC-SHA256 of `"{timestamp}.{raw body}"`:

| Upload-Post | Reelspan |
| --- | --- |
| `X-Upload-Post-Signature` | `X-Reelspan-Signature` |
| `X-Upload-Post-Timestamp` | `X-Reelspan-Timestamp` |
| `X-Upload-Post-Event` | `X-Reelspan-Event` |
| `X-Upload-Post-Delivery` | `X-Reelspan-Delivery` |
| User-Agent `Upload-Post-Webhooks/1.0` | User-Agent `Reelspan-Webhooks/1.0` |

Register the endpoint again on Reelspan: it gets a new signing secret (`whsec_…`). Reelspan sends webhooks only; there is no Telegram notification channel. See [Webhooks](/webhooks).

## What you get on top

- **Test keys and a sandbox network.** A `rs_test_` key runs every check and publishes nothing; the `sandbox` network needs no connected account. See [Test mode](/guides/test-mode).
- **Upload once, post many times.** [Upload media](/api/upload-media) returns a `media_id` to use as `video_media_id`, `photo_media_ids[]`, `thumbnail_media_id` or `cover_media_id`, and files over 100 MB go straight to storage in parts.
- **Repeats.** `repeat_every` (`day`, `week`, `month`) and `repeat_times` schedule a whole series at once; `DELETE /v1/scheduled/{job_id}?series=rest` cancels the rest of it.
- **Finer retries.** [Retry](/api/retry) can send only some networks again, change their settings first, and run now or at a set time.
- **Webhook deliveries you can see.** Failed deliveries are retried with backoff, every delivery is in a log, and you can redeliver one or send a test event.
- **Approval links.** Send scheduled posts to a client, who approves each one from a link before it goes out. See [Approval links](/api/approval-links).
- **More analytics.** Daily account history, best times to post and period reports.
- **Official SDKs** for Node.js and Python with retries and idempotent posts built in. See [SDKs](/sdks).

## Not available yet

These Upload-Post endpoints have no Reelspan equivalent today: TikTok hashtag suggestions; comments, DMs and AutoDMs; cached bulk post analytics; Google Business location info and reviews. Editing or unpublishing YouTube videos and Threads posts isn't possible either: [Unpublish](/api/unpublish) and [Edit a post](/api/edit-post) list the networks that work. If your integration depends on one of these, [tell us](/support).

Source: https://docs.reelspan.com/migrate-from-upload-post

---

# Post a video

> Upload one video and publish it to any of 22 networks at once, now, at a set time, in the queue, or on repeat, with each network's own settings.

Send the video once as `multipart/form-data`. Name the profile in `user` and each network in a repeated `platform[]` field. Reelspan converts and uploads it to every network, then answers with one result per network.

## A first video

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Idempotency-Key: launch-2026-12-01" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "platform[]=youtube" \
  -F "platform[]=instagram" \
  -F "title=Launch day" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['tiktok', 'youtube', 'instagram'],
  title: 'Launch day',
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video("my-brand", ["tiktok", "youtube", "instagram"], "launch.mp4", "Launch day")
```

`video` can also be a public https URL instead of a file; Google Drive and Dropbox share links work. To post the same file more than once, upload it first with [Upload media](/api/upload-media) and send `video_media_id`.

## The response

The request waits up to 59 seconds for every network. Most finish in that time and you get **200** with `results`, keyed by network:

```json
{
  "success": true,
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "results": {
    "tiktok": { "success": true, "url": "https://www.tiktok.com/@mybrand/video/7441…", "post_id": "7441…" },
    "youtube": { "success": true, "url": "https://youtube.com/shorts/aB3…" },
    "instagram": { "success": false, "error": "Instagram is still processing the video", "error_code": "processing_timeout" }
  }
}
```

When a network takes longer, the answer is still **200**, but without `results`: it has a `message`, the `request_id` and `total_platforms`, and the work carries on in the background. Read the outcome with [Post status](/api/post-status) or a [webhook](/webhooks). Send `async_upload=true` to get that answer straight away.

```json
{
  "success": true,
  "message": "Upload initiated successfully in background.",
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "total_platforms": 3
}
```

A scheduled or queued post answers **202** with its `job_id` instead.

> [!TIP]
> One network failing never fails the others. Retry only the failed ones with [Retry](/api/retry): the video is not uploaded again.

## Captions per network

`title` is the caption every network uses. To say something different on one network, send `{network}_title` (for example `tiktok_title`, `instagram_title`, `x_title`), and `{network}_description` where the network has a separate body (YouTube, LinkedIn, Reddit, WordPress…). YouTube needs a title; it uses `youtube_title`, else `title`.

## Network settings

Each network's own options are plain form fields, named after the network: TikTok privacy and interactions, the YouTube category, tags and thumbnail, an Instagram Story instead of a Reel, a Pinterest board, a Reddit subreddit, and so on. The full list for each network, with what it does and its limits, is on that network's page under [Networks](/networks/tiktok).

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" -F "platform[]=youtube" \
  -F "title=How we ship" \
  -F "privacy_level=PUBLIC_TO_EVERYONE" \
  -F "youtube_title=How we ship, in 60 seconds" \
  -F "privacyStatus=public" \
  -F "video=@clip.mp4"
```

## Later, queued or repeated

- **At a time:** `scheduled_date` (ISO 8601) with an optional `timezone`. The answer is 202 with a `job_id`; see [Scheduled posts](/api/scheduled-posts).
- **In the queue:** `add_to_queue=true` takes the profile's next free slot; see [Queue](/api/queue).
- **On repeat:** `repeat_every` (`day`, `week`, `month`) and `repeat_times` (2 to 30) schedule the whole series at once; see [Scheduling and repeats](/guides/scheduling).

## Safe to retry

Send an `Idempotency-Key` header, or your own `request_id`. If the network drops after you sent the request, sending it again with the same key returns the first request's result instead of posting twice. See [Retrying safely](/guides/idempotency).

## Limits

The video must be within your plan's upload size and each network's own limits (length, size, aspect ratio). Reelspan checks before uploading and says which network can't take it; see [Video requirements](/limits/video).

Source: https://docs.reelspan.com/api/post-video

---

# Post photos

> Publish one photo or a carousel of up to 35 to Instagram, TikTok, Pinterest, X, LinkedIn and more at once, with alt text and per-network crops.

Send one photo or a carousel as `multipart/form-data`, in order, with the profile in `user` and each network in a repeated `platform[]` field. Each network gets the photos in the form it takes, and the answer has one result per network.

## A first carousel

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/photos \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Idempotency-Key: spring-range-01" \
  -F "user=my-brand" \
  -F "platform[]=instagram" \
  -F "platform[]=x" \
  -F "platform[]=linkedin" \
  -F "title=The spring range is here" \
  -F "photos[]=@photo1.jpg" \
  -F "photos[]=@photo2.jpg" \
  -F "alt_text[]=A red mug on a wooden table" \
  -F "alt_text[]=The same mug in blue"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.photos({
  user: 'my-brand',
  platforms: ['instagram', 'x', 'linkedin'],
  title: 'The spring range is here',
  photos: [
    { data: await readFile('photo1.jpg'), name: 'photo1.jpg', type: 'image/jpeg' },
    { data: await readFile('photo2.jpg'), name: 'photo2.jpg', type: 'image/jpeg' },
  ],
  altTexts: ['A red mug on a wooden table', 'The same mug in blue'],
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.photos(
    "my-brand",
    ["instagram", "x", "linkedin"],
    ["photo1.jpg", "photo2.jpg"],
    "The spring range is here",
    alt_texts=["A red mug on a wooden table", "The same mug in blue"],
)
```

The answer is the same as for a video: one result per network under `results`, or a `request_id` when it runs on in the background. See [Post status](/api/post-status).

## Where the photos come from

`photos[]` takes files, public https URLs, or both. You can also pass `photo_media_ids[]`, files you [uploaded earlier](/api/upload-media), to post the same photos again without sending them twice.

- Up to **35** items in all. Extra files are dropped with a warning.
- Each image can be up to **20 MB**. Supported images: JPEG, PNG, WebP, GIF and HEIC.
- When you mix sources, the carousel order is: uploaded files, then `photo_media_ids[]`, then URLs, each in the order you sent them.
- At least one photo is required; without one the answer is **400** `MEDIA_REQUIRED`.
- One request can fetch at most 100 URLs, counting every network's own photo URLs too.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/photos \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=threads" \
  -F "title=From the shoot" \
  -F "photos[]=https://example.com/photo1.jpg" \
  -F "photos[]=https://example.com/photo2.jpg"
```

```javascript title="Node.js"
await reelspan.posts.photos({
  user: 'my-brand',
  platforms: ['threads'],
  title: 'From the shoot',
  photos: ['https://example.com/photo1.jpg', 'https://example.com/photo2.jpg'],
});
```

```python title="Python"
reelspan.posts.photos("my-brand", ["threads"], ["https://example.com/photo1.jpg", "https://example.com/photo2.jpg"], "From the shoot")
```

## Which networks take photos

Instagram, Facebook, TikTok, X, Threads, LinkedIn, Pinterest, Bluesky, Reddit, Google Business, Telegram, Discord, Slack, Mastodon, Nostr, Lemmy, WordPress, Whop and Listmonk. YouTube, Dev.to and Hashnode don't: naming one gets **400** `UNSUPPORTED_POST_TYPE`.

How many photos each network shows, and the sizes and shapes it accepts, are on [Photo requirements](/limits/photos).

## Videos in a carousel

Instagram and Threads take videos and photos mixed in one carousel: put the video in `photos[]` (or its id in `photo_media_ids[]`) where it should appear. Every other network gets the photos only, and its result carries a warning that the videos were left out. A network left with no photos at all fails with `media_required`.

## A different set per network

A network can get its own photos instead of `photos[]`, for example a square crop for one network:

- `{network}_photos[]`: public URLs, such as `pinterest_photos[]`.
- `{network}_photo_media_ids[]`: uploaded files, such as `instagram_photo_media_ids[]`.

```bash
curl -X POST https://api.reelspan.com/v1/posts/photos \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=instagram" -F "platform[]=pinterest" \
  -F "title=New in" \
  -F "pinterest_board_id=1234567890" \
  -F "photos[]=@photo1.jpg" \
  -F "pinterest_photos[]=https://example.com/photo1-2x3.jpg"
```

## Alt text

`alt_text[]` gives one text per photo, in order. A single `alt_text` applies to every photo, and a JSON array in `alt_text` works too. `{network}_alt_text` overrides it for one network (for example `x_alt_text`). Alt text is sent to X, Instagram, Facebook, Threads, LinkedIn, Pinterest and Bluesky.

## Captions

`title` is the caption on every network. `{network}_title` replaces it on one network (`instagram_title`, `x_title`, `linkedin_title`…), and `{network}_description` sets the longer text where a network has one. A long caption on X or Bluesky is posted as a thread.

## Network settings

The fields below are the ones made for photo posts. Every network's full list is on its page under [Networks](/networks/instagram).

| Network | Field | What it does |
| --- | --- | --- |
| Instagram | `media_type=STORIES` | Shares each photo as a Story instead of a feed post. |
| Facebook | `facebook_media_type=STORIES` | Shares each photo as its own Page Story. |
| TikTok | `privacy_level` | Who can see it, as for videos. |
| TikTok | `photo_cover_index` | Which photo (from 0) is the cover. |
| TikTok | `auto_add_music` | `true` lets TikTok add music. |
| TikTok | `tiktok_description` | The post's description, up to 4,000 characters. Its title is the first 90 characters of the caption. |
| Pinterest | `pinterest_board_id` | The board to pin to. Required. |
| Reddit | `reddit_subreddit` | The community to post in. Required. |

> [!NOTE]
> Instagram takes photos from 4:5 to 1.91:1 and converts non-JPEG photos for you. A Pinterest carousel needs every photo in the same shape; use `pinterest_photos[]` to send it its own crops.

## Later, queued or repeated

The same as for a video: `scheduled_date` with `timezone`, `add_to_queue=true`, or `repeat_every` with `repeat_times`. A scheduled answer is **202** with a `job_id`. See [Scheduled posts](/api/scheduled-posts), [Queue](/api/queue) and [Scheduling and repeats](/guides/scheduling).

Source: https://docs.reelspan.com/api/post-photos

---

# Post text

> Publish a text-only post to X, Threads, Bluesky, LinkedIn, Facebook, Reddit, Mastodon and more in one call, with JSON or form fields. Long posts become threads.

A text post needs no media, so you can send it as JSON (or as form fields, if that is easier). `title` is the text of the post; name the profile in `user` and the networks in `platform`.

## A first text post

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-note-2026-12-01" \
  -d '{
    "user": "my-brand",
    "platform": ["x", "threads", "bluesky", "linkedin"],
    "title": "We just shipped scheduled reports. Every Monday, in your inbox."
  }'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const post = await reelspan.posts.text({
  user: 'my-brand',
  platforms: ['x', 'threads', 'bluesky', 'linkedin'],
  title: 'We just shipped scheduled reports. Every Monday, in your inbox.',
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.text("my-brand", ["x", "threads", "bluesky", "linkedin"], "We just shipped scheduled reports. Every Monday, in your inbox.")
```

In JSON, `platform` is an array (`"platform[]"` works as the key too). As a form, repeat `-F "platform[]=x"`. A post without `title` gets **400** `TITLE_REQUIRED`.

## Which networks take text

X, Threads, Bluesky, LinkedIn, Facebook, Reddit, Google Business, Telegram, Discord, Slack, Mastodon, Nostr, Lemmy, Dev.to, Hashnode, WordPress, Whop and Listmonk.

TikTok, Instagram, YouTube and Pinterest have no text posts: naming one gets **400** `UNSUPPORTED_POST_TYPE`, and nothing is posted.

## Long text and threads

On **X** a text longer than 280 characters is split into a thread, and on **Bluesky** one longer than 300; each later post replies to the one before. The result carries a warning saying how many posts the thread has. On X, send `x_long_text_as_post=true` to keep it as one long post instead (this needs an X account that can post long text).

> [!WARNING]
> Links are removed from X posts unless you send `x_keep_links=true`, because X charges for posts with a link. Keeping links uses a monthly allowance that depends on your plan (Free and Starter have none); past it the links are removed and the result says so.

## Title, description and per-network text

`title` is the text everywhere. To say something different on one network, send `{network}_title` (`x_title`, `linkedin_title`, `bluesky_title`…).

Some networks also read `description` (or `{network}_description`):

| Network | Uses `title` for | Uses `description` for |
| --- | --- | --- |
| LinkedIn, Facebook | the post, when there is no description | the post text, when given |
| Reddit | the post title (its first line, up to 300 characters; or `reddit_title`) | the body (`reddit_description`; else the caption) |
| Dev.to, Hashnode, WordPress | the article title (`{network}_title`, else the caption's first line) | the article body (else the caption) |
| Lemmy, Listmonk | the title | the body |

> [!NOTE]
> On LinkedIn and Facebook a `description` wins over `title`. Send only `title` for a plain post there, or set `linkedin_description` / `facebook_description` when you mean to.

## Network settings

| Network | Field | What it does |
| --- | --- | --- |
| Facebook | `facebook_link` | A link Facebook shows as a preview card. |
| Reddit | `reddit_subreddit` | The community to post in. Required. |
| Reddit | `reddit_flair_id`, `reddit_nsfw`, `reddit_spoiler` | Flair and labels. |
| X | `reply_settings`, `reply_to_id` | Who can reply; post as a reply. |
| Threads | `threads_reply_control`, `threads_topic_tag` | Who can reply; a topic tag. |
| LinkedIn | `visibility` | `PUBLIC`, `CONNECTIONS` or `LOGGED_IN`. |
| Mastodon | `mastodon_visibility`, `mastodon_spoiler_text` | Visibility; a content warning. |
| WordPress | `wordpress_status` | Publish or keep as a draft. |

Each network's page under [Networks](/networks/x) lists everything it takes and the values each field allows.

## First comment

`first_comment` is posted right after the post goes live: as a reply on X, Bluesky and Threads, as a comment elsewhere. `{network}_first_comment` overrides it for one network. If a network can't take it, the post still counts and its result carries a warning.

## The response

Text posts usually finish well inside the request, so the answer is **200** with `results`, one per network:

```json
{
  "success": true,
  "request_id": "4c7d1e9a0b2f4e6c8a1d3f5b7e9c0a2d",
  "results": {
    "x": { "success": true, "url": "https://x.com/mybrand/status/18…", "post_id": "18…" },
    "linkedin": { "success": true, "url": "https://www.linkedin.com/feed/update/urn:li:share:72…", "post_id": "urn:li:share:72…" }
  },
  "usage": { "count": 12, "limit": null, "last_reset": "2026-11-01T00:00:00.000Z" }
}
```

If one takes longer than 59 seconds, the answer has a `message` and the `request_id` instead, and you follow it with [Post status](/api/post-status) or a [webhook](/webhooks).

## Later, queued or repeated

- **At a time:** `scheduled_date` (ISO 8601) and `timezone`; the answer is **202** with a `job_id`.
- **In the queue:** `add_to_queue: true` takes the profile's next free slot; see [Queue](/api/queue).
- **On repeat:** `repeat_every` (`day`, `week` or `month`) with `repeat_times` (2 to 30); see [Scheduling and repeats](/guides/scheduling).

```javascript title="Node.js"
await reelspan.posts.text({
  user: 'my-brand',
  platforms: ['x', 'linkedin'],
  title: 'Tip of the week: schedule once, post everywhere.',
  scheduledDate: '2026-12-07T09:00:00',
  timezone: 'Europe/London',
  repeatEvery: 'week',
  repeatTimes: 6,
});
```

```python title="Python"
reelspan.posts.text(
    "my-brand", ["x", "linkedin"], "Tip of the week: schedule once, post everywhere.",
    scheduled_date="2026-12-07T09:00:00", timezone="Europe/London", repeat_every="week", repeat_times=6,
)
```

Source: https://docs.reelspan.com/api/post-text

---

# Post a document

> Publish a PDF, PowerPoint or Word file to LinkedIn as a swipeable document post, from a file, a link or an earlier upload, now or scheduled.

LinkedIn shows a document (PDF, PowerPoint or Word) as a carousel readers swipe through, page by page, under the post. Send the file as `multipart/form-data` with the profile in `user` and `platform[]=linkedin`.

## A first document

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/document \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Idempotency-Key: q3-report-post" \
  -F "user=my-brand" \
  -F "platform[]=linkedin" \
  -F "title=Q3 report" \
  -F "description=Our quarter in 12 slides: what grew, what didn't, and what's next." \
  -F "document=@q3-report.pdf"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.document({
  user: 'my-brand',
  platforms: ['linkedin'],
  title: 'Q3 report',
  description: "Our quarter in 12 slides: what grew, what didn't, and what's next.",
  document: { data: await readFile('q3-report.pdf'), name: 'q3-report.pdf', type: 'application/pdf' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.document(
    "my-brand", "q3-report.pdf", "Q3 report",
    description="Our quarter in 12 slides: what grew, what didn't, and what's next.",
)
```

## The document

- **Format:** PDF, PowerPoint (`.pptx`, `.ppt`) or Word (`.docx`, `.doc`). Reelspan reads the type from the file's own bytes, not its name or `Content-Type`. Other files, spreadsheets included, are refused with **400** `UNSUPPORTED_MEDIA`.
- **Size:** up to 100 MB. LinkedIn takes up to 300 pages.
- **Where from:** a file in `document`, a public https URL in `document` (Google Drive and Dropbox share links work), or `document_media_id` from an [upload](/api/upload-media) made with `kind=document`. Without any of them the answer is **400** `MEDIA_REQUIRED`.

```bash
curl -X POST https://api.reelspan.com/v1/posts/document \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=linkedin" \
  -F "title=Q3 report" \
  -F "document=https://example.com/q3-report.pdf"
```

## Title and post text

The two texts do different jobs:

- `title` names the document; LinkedIn shows it on the document itself. It is required (**400** `TITLE_REQUIRED` without it) and is cut to 400 characters. `document_title` names the document differently from the post's `title` if you need both.
- The post text above the document is `linkedin_description`, else `description`, else `linkedin_title`, else `title`.

## LinkedIn only

Documents go to LinkedIn only. Naming any other network gets **400** `UNSUPPORTED_POST_TYPE` and nothing is posted. The `sandbox` network doesn't take documents either, so to try this without publishing, use a [test key](/guides/test-mode) with a LinkedIn account connected to the profile.

## Settings

| Field | What it does |
| --- | --- |
| `visibility` | `PUBLIC` (the default), `CONNECTIONS`, `LOGGED_IN` or `CONTAINER`, passed to LinkedIn as given. `linkedin_visibility` works too. |
| `first_comment` | Posted as the first comment once the post is live. `linkedin_first_comment` works too. |
| `target_linkedin_page_id` | Post as a LinkedIn Company Page instead of the member. |

> [!NOTE]
> Reelspan doesn't have LinkedIn's company-page access yet, so `GET /v1/linkedin/pages` returns an empty list for now and posting as a Company Page may be refused by LinkedIn. Posting as the connected member works.

## The response

LinkedIn processes the document before it can be posted, which can take a while for a long document. When it finishes within the request, the LinkedIn result also names the document:

```json
{
  "success": true,
  "request_id": "a3e0c5d7b9f14e2a8c6b0d4f2e8a1c3b",
  "results": {
    "linkedin": {
      "success": true,
      "url": "https://www.linkedin.com/feed/update/urn:li:share:72…/",
      "post_id": "urn:li:share:72…",
      "document_urn": "urn:li:document:D4E…",
      "content_type": "application/pdf",
      "file_size": 2481152,
      "filename": "q3-report.pdf"
    }
  },
  "usage": { "count": 5, "limit": null, "last_reset": "2026-11-01T00:00:00.000Z" }
}
```

When it takes longer than 59 seconds, or you sent `async_upload=true`, the answer has a `message` and the `request_id`; follow it with [Post status](/api/post-status) or a [webhook](/webhooks).

## Later or repeated

`scheduled_date` with `timezone`, `add_to_queue=true`, or `repeat_every` with `repeat_times` work as for every other post; a scheduled answer is **202** with a `job_id`. See [Scheduled posts](/api/scheduled-posts).

Source: https://docs.reelspan.com/api/post-document

---

# Upload media

> Upload a video, photo or document once and get a media_id to post it many times, and send files over 100 MB straight to storage in parts.

Upload a file ahead of the post and you get a `media_id`. Use it in place of the file on any post: the same video to several profiles, a retry with new settings, or captions written from it, without sending the bytes again. Files over 100 MB go up in parts, straight to storage.

## Upload a file

Send the file in a multipart field named `file`, and say what it is with `kind` in the query: `video` (the default), `photo` or `document`.

```bash title="cURL"
curl -X POST "https://api.reelspan.com/v1/media/upload?kind=video" \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "file=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const media = await reelspan.media.upload({ data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' }, { kind: 'video' });
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
media = reelspan.media.upload("launch.mp4", kind="video")
```

```json
{
  "success": true,
  "media_id": "med_Xb7Qk2LmN4pR8sTv0wYz",
  "kind": "video",
  "content_type": "video/mp4",
  "size_bytes": 48211337,
  "duration_seconds": 42.5
}
```

`duration_seconds` is filled in for videos and `null` for photos and documents.

| `kind` | Accepts | Largest file |
| --- | --- | --- |
| `video` | MP4, MOV, WebM | Your plan's upload limit ([Plans and limits](/limits/plans)) |
| `photo` | JPEG, PNG, WebP, GIF, HEIC | 20 MB |
| `document` | PDF, PPTX, PPT, DOCX, DOC | 100 MB |

Reelspan checks the file's real type from its contents, not its name. A file of the wrong kind gets **400**; one over the limit gets **413** `FILE_TOO_LARGE`.

Add `save=true` (and an optional `title`) to the query to keep the file in the [media library](/api/library) right away.

## Post it by media_id

Use the id in the field for its role:

| Post | Field |
| --- | --- |
| [Video](/api/post-video) | `video_media_id` |
| Video thumbnail (YouTube) | `thumbnail_media_id` (a `photo` upload) |
| Video cover (TikTok) | `cover_media_id` (a `photo` upload) |
| [Photos](/api/post-photos) | `photo_media_ids[]`, or `{network}_photo_media_ids[]` for one network; videos work here too for Instagram and Threads carousels |
| [Document](/api/post-document) | `document_media_id` (a `document` upload) |
| [AI captions](/api/ai-captions) | `media_id` |

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "platform[]=youtube" \
  -F "title=Launch day" \
  -F "video_media_id=med_Xb7Qk2LmN4pR8sTv0wYz"
```

```javascript title="Node.js"
await reelspan.posts.video({ user: 'my-brand', platforms: ['tiktok', 'youtube'], title: 'Launch day', videoMediaId: media.media_id });
```

```python title="Python"
reelspan.posts.video("my-brand", ["tiktok", "youtube"], title="Launch day", video_media_id=media["media_id"])
```

An id of another workspace, or of the wrong kind (a photo as `video_media_id`), gets **400** `MEDIA_NOT_FOUND`.

### How long an upload lasts

- An upload that no post uses is deleted after a day.
- Once a post that uses it has finished, the file is kept for a few days (7 by default) so you can [retry](/api/retry), then deleted, unless another waiting post still needs it.
- Files kept in the [media library](/api/library) stay until you remove them, so keep anything you'll post again later.

## Large files, in parts

A single request carries at most 100 MB, so send bigger files straight to storage in parts. It takes three steps.

**1. Start the upload** with the kind and the exact size in bytes. You get a `media_id`, the `part_size`, and one signed URL per part:

```json
{
  "success": true,
  "kind": "video",
  "media_id": "med_Q9vT3kLw8ZpX2nB6yR1s",
  "part_size": 8388608,
  "parts": [
    { "part_number": 1, "url": "https://…" },
    { "part_number": 2, "url": "https://…" }
  ],
  "expires_in": 3600
}
```

Parts are at least 8 MB, and a file is split into 1,000 parts at most. The size is checked against your plan here (**413** if it's over).

**2. Upload each part** with a `PUT` to its URL. Part *n* is the bytes from `(n - 1) × part_size`, `part_size` long; the last part is whatever is left. Each URL is signed for its part's exact length, so a body of any other size is refused. Keep the `ETag` header from each answer, exactly as it comes (with its quotes). Parts can go up in parallel and in any order. The URLs work for `expires_in` seconds (an hour).

**3. Complete it** with every part's number and ETag. Reelspan then reads the stored file's real size and type; one that isn't the `kind` you declared, or is over your plan's limit, is deleted and refused with **400** or **413**. The answer is the same as a single upload's, and the `media_id` is ready to post.

```bash title="cURL"
FILE=film.mp4
SIZE=$(stat -c%s "$FILE")   # macOS: stat -f%z
API=https://api.reelspan.com/v1
AUTH="Authorization: Bearer $REELSPAN_API_KEY"

START=$(curl -s -X POST "$API/media/uploads" -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"kind\": \"video\", \"size_bytes\": $SIZE, \"filename\": \"$FILE\"}")
MEDIA_ID=$(echo "$START" | jq -r .media_id)
PART_SIZE=$(echo "$START" | jq -r .part_size)

PARTS='[]'
for row in $(echo "$START" | jq -c '.parts[]'); do
  N=$(echo "$row" | jq -r .part_number)
  URL=$(echo "$row" | jq -r .url)
  ETAG=$(dd if="$FILE" bs="$PART_SIZE" skip=$((N - 1)) count=1 2>/dev/null \
    | curl -s -X PUT --data-binary @- -D - -o /dev/null "$URL" \
    | grep -i '^etag:' | cut -d' ' -f2- | tr -d '\r')
  PARTS=$(echo "$PARTS" | jq --argjson n "$N" --arg e "$ETAG" '. + [{part_number: $n, etag: $e}]')
done

curl -X POST "$API/media/uploads/$MEDIA_ID/complete" -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"parts\": $PARTS}"
```

```javascript title="Node.js"
// media.upload switches to parts on its own from 90 MB: three at a time, each retried on its own
const media = await reelspan.media.upload(file, {
  kind: 'video',
  onProgress: (sent, total) => console.log(Math.round((sent / total) * 100), '%'),
});
```

```python title="Python"
# media.upload switches to parts on its own from 90 MB, reading the file from disk piece by piece
media = reelspan.media.upload("film.mp4", kind="video", on_progress=lambda sent, total: print(f"{sent * 100 // total}%"))
```

The SDKs also hand a large file to this flow when you pass it straight to `posts.video`.

### Stop an upload

To give up on an upload you started, call `POST /v1/media/uploads/{media_id}/abort`. Storage drops the parts sent so far and the `media_id` stops working. An upload that is never completed expires after 24 hours; completing or aborting it after that gets **404** `UPLOAD_NOT_FOUND`, and you start again.

```bash
curl -X POST "https://api.reelspan.com/v1/media/uploads/med_Q9vT3kLw8ZpX2nB6yR1s/abort" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

More on big files in [Large files](/guides/large-files).

Source: https://docs.reelspan.com/api/upload-media

---

# Post status

> Check where a post stands on each network - live with its URL, failed with a reason, or still working - by request_id or by a scheduled post's job_id.

Every post gets a `request_id`, and a scheduled one a `job_id` too. Pass either to see the post's overall state and each network's result. Use it after a post moved to the background, after a scheduled time, or after a [retry](/api/retry).

## Check a post

```bash title="cURL"
curl "https://api.reelspan.com/v1/posts/status?request_id=9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const status = await reelspan.posts.status({ requestId: '9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1' });
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
status = reelspan.posts.status(request_id="9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1")
```

For a scheduled post, send `job_id=sched_…` instead (`{ jobId }` in Node, `job_id=` in Python). Without either, the answer is **400**; an id that doesn't exist, or belongs to a profile your key can't use, is **404** with `"status": "not_found"`.

```json
{
  "success": true,
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "job_id": null,
  "external_id": "campaign-42",
  "status": "in_progress",
  "completed": 2,
  "total": 3,
  "results": [
    {
      "platform": "tiktok",
      "success": true,
      "status": "completed",
      "message": "Published",
      "upload_timestamp": "2026-12-01T09:00:41.000Z",
      "platform_post_id": "7441…",
      "post_url": "https://www.tiktok.com/@mybrand/video/7441…",
      "error_message": null,
      "error_code": null,
      "warnings": [],
      "post_id_resolved_late": false
    },
    {
      "platform": "instagram",
      "success": false,
      "status": "skipped",
      "message": "Profile my-brand has no Instagram account configured",
      "upload_timestamp": "2026-12-01T09:00:02.000Z",
      "platform_post_id": null,
      "post_url": null,
      "error_message": "Profile my-brand has no Instagram account configured",
      "error_code": "profile_platform_mapping_invalid",
      "warnings": [],
      "post_id_resolved_late": false,
      "skipped": true,
      "skip_reason": "profile_platform_not_configured"
    }
  ],
  "last_update": "2026-12-01T09:00:41.000Z"
}
```

## Overall status

| `status` | Meaning |
| --- | --- |
| `pending` | Waiting: scheduled for later, or not started yet. |
| `in_progress` | At least one network has started or finished, and at least one hasn't. |
| `completed` | Every network has finished and **at least one** went live. |
| `failed` | Every network has finished and none went live. |
| `cancelled` | A scheduled post that was cancelled. |

> [!IMPORTANT]
> `completed` doesn't mean every network succeeded. Read each result's `success`, or compare the count of successes with `total`.

`completed` and `total` count networks: how many have finished, and how many the post has. A post made with a [test key](/guides/test-mode) also carries `"test": true`.

## Each network's result

`results` lists only the networks that have finished, so it grows as the post goes out. A network finishes in one of three ways:

- `completed`: live. `post_url` and `platform_post_id` say where.
- `failed`: the network refused it, or kept failing. `error_message` and `error_code` say why; see [Errors](/errors).
- `skipped`: never tried, with a `skip_reason`. Most often the profile has no account on that network, or it needs reconnecting. A skipped network isn't charged.

`warnings` lists what changed on the way, such as links removed on X or a first comment that couldn't be posted. `post_id_resolved_late` is kept for Upload-Post compatibility and is always `false`.

While a network is still working it isn't in `results`. A temporary error (a network timing out, a rate limit) is retried on its own a few times, about 15, 30 and 60 seconds apart, before it counts as failed. [History](/api/history) shows networks still working under `in_progress`.

## Polling

Poll every 5 seconds or more, and stop once `status` is `completed`, `failed` or `cancelled`. The SDKs do it for you:

```javascript title="Node.js"
const done = await reelspan.posts.wait(requestId, { intervalMs: 5000, timeoutMs: 600_000 });
```

```python title="Python"
done = reelspan.posts.wait(request_id, timeout=600, interval=5)
```

Both return the last status they saw, finished or not, when the timeout passes.

> [!TIP]
> Rather than polling, set a [webhook](/webhooks): Reelspan sends an `upload_completed` event as each network finishes.

## Lost the answer?

If the network dropped before you got a `request_id`, you can still find the post:

- Send your own `request_id` (8 to 100 letters, digits, `_` or `-`) with the post, and poll that.
- Or send an `external_id` and look it up in [History](/api/history) with `?external_id=`.
- Or send an `Idempotency-Key` and repeat the request: it returns the first one's state instead of posting again. See [Retrying safely](/guides/idempotency).

Source: https://docs.reelspan.com/api/post-status

---

# History

> List every post Reelspan has published or tried, one row per network, filtered by network, outcome, profile, id or date, newest first.

History has one row per network post: a video sent to three networks is three rows. Use it to build a "recent posts" view, to find failures, or to look up a post by your own id.

## List recent posts

```bash title="cURL"
curl "https://api.reelspan.com/v1/posts?profile_username=my-brand&limit=20" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const page = await reelspan.posts.history({ profile_username: 'my-brand', limit: 20 });
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
page = reelspan.posts.history(profile_username="my-brand", limit=20)
```

```json
{
  "history": [
    {
      "profile_username": "my-brand",
      "platform": "youtube",
      "media_type": "video",
      "upload_timestamp": "2026-12-01T09:01:12.000Z",
      "success": true,
      "status": "completed",
      "platform_post_id": "aB3…",
      "post_url": "https://youtube.com/shorts/aB3…",
      "error_message": null,
      "post_title": "Launch day",
      "post_caption": "Launch day, in 60 seconds",
      "is_async": false,
      "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
      "job_id": null,
      "external_id": "campaign-42",
      "request_total_platforms": 3,
      "post_id_resolved_late": false,
      "video_was_transcoded": false
    }
  ],
  "in_progress": [],
  "total": 57,
  "page": 1,
  "limit": 20
}
```

## What a row holds

- `status` is `completed`, `failed` or `skipped`; `success` is `true` only for `completed`.
- `media_type` is `video`, `photo`, `text` or `document`.
- `upload_timestamp` is when that network finished.
- `post_title` is the post's `title`; `post_caption` is the text this network got (its `{network}_title`, else `title`).
- `is_async` is `true` for posts that were scheduled, queued or sent with `async_upload`.
- `request_id`, `job_id` and `external_id` tie the row to the post. Pass `request_id` to [Post status](/api/post-status) or [Retry](/api/retry).
- `post_id_resolved_late` and `video_was_transcoded` are kept for Upload-Post compatibility and are `false`.

`history` holds finished network posts only. Networks still working are listed separately under `in_progress`, with the same fields: up to 100 of them, from posts made in the last 24 hours. The filters below don't apply to `in_progress`. Scheduled posts that haven't run yet are in [Scheduled posts](/api/scheduled-posts) instead.

## Filters

| Parameter | What it does |
| --- | --- |
| `platform` | One network, like `tiktok`. |
| `status` | `success` for live posts; `failed` for failed and skipped ones (cancelled scheduled posts show here as skipped). |
| `profile_username` | One profile. `profile` works too. |
| `request_id`, `job_id`, `external_id` | Exact match: every network of that post. |
| `start`, `end` | A time range on when each network post last changed (normally when it finished). Send both, as dates (`2026-12-01`) or date-times with an offset (`2026-12-01T00:00:00Z`). `end` is not included, and the range can be at most 2 months. |

Find every network of one post sent with your own id:

```bash
curl "https://api.reelspan.com/v1/posts?external_id=campaign-42" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

Wrong filters get **400**: an unknown `status`, a `limit` other than the allowed values, only one of `start` and `end`, or a range that is backwards or longer than 2 months.

## Pages

Rows come newest first, by when each network post last changed. `page` starts at 1 and `limit` is 10 (the default), 20, 50 or 100. There are more pages while `page × limit` is less than `total`.

The SDKs walk every page for you:

```javascript title="Node.js"
for await (const row of reelspan.posts.all({ platform: 'tiktok', status: 'failed' })) {
  console.log(row.request_id, row.error_message);
}
```

```python title="Python"
for row in reelspan.posts.all(platform="tiktok", status="failed"):
    print(row["request_id"], row["error_message"])
```

A key limited to some profiles only sees their posts.

Source: https://docs.reelspan.com/api/history

---

# Retry

> Send a post again to only the networks that failed, now or at a set time, with the media it already has, after fixing a caption or setting if needed.

When some networks fail, retry just those. Reelspan reuses the media it already stored, so nothing is uploaded again, and the networks that went live are never touched.

## Retry the failed networks

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/retry \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const retry = await reelspan.posts.retry('9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1');
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
retry = reelspan.posts.retry("9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1")
```

```json
{
  "success": true,
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "message": "Failed platforms re-enqueued for retry",
  "platforms": ["instagram"]
}
```

`platforms` lists the networks sent again. They start straight away; follow them with [Post status](/api/post-status) or a [webhook](/webhooks), as for a new post. A scheduled post's `job_id` works in place of `request_id`.

## Only some networks

Send `platforms` to retry only those. Networks you don't name stay as they are.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/retry \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1", "platforms": ["tiktok"]}'
```

```javascript title="Node.js"
await reelspan.posts.retry('9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1', ['tiktok']);
```

```python title="Python"
reelspan.posts.retry("9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1", ["tiktok"])
```

## Fix a setting first

If a network failed because of what you sent (a caption too long, a privacy level the account can't use, a video too big for Bluesky), change it in `fields` and retry in one call. The names are the same as the post's own fields; an empty string removes a field.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/retry \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
    "platforms": ["tiktok", "bluesky"],
    "fields": { "privacy_level": "SELF_ONLY", "bluesky_compress": "true", "tiktok_title": "" }
  }'
```

```javascript title="Node.js"
await reelspan.request('POST', '/v1/posts/retry', {
  json: {
    request_id: '9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1',
    platforms: ['tiktok', 'bluesky'],
    fields: { privacy_level: 'SELF_ONLY', bluesky_compress: 'true', tiktok_title: '' },
  },
});
```

```python title="Python"
reelspan.request("POST", "/v1/posts/retry", json_body={
    "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
    "platforms": ["tiktok", "bluesky"],
    "fields": {"privacy_level": "SELF_ONLY", "bluesky_compress": "true", "tiktok_title": ""},
})
```

The change is saved on the post, so it also applies to any later retry. The profile (`user`), the networks (`platform[]`) and the media can't be changed: fields for them are ignored. To post different media, make a new post.

## Retry later

Send `scheduled_date` (ISO 8601, in the future and within 365 days) to retry at a set time instead of now, with `timezone` (an IANA zone such as `Europe/London`; UTC by default) when the date has no offset. The post becomes a scheduled post again: it gets a `job_id` and shows in [Scheduled posts](/api/scheduled-posts), where you can move, edit or cancel it like any other.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/retry   -H "Authorization: Bearer $REELSPAN_API_KEY"   -H "Content-Type: application/json"   -d '{
    "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
    "platforms": ["instagram"],
    "scheduled_date": "2026-11-08T09:00:00",
    "timezone": "Europe/London"
  }'
```

```javascript title="Node.js"
await reelspan.request('POST', '/v1/posts/retry', {
  json: { request_id: '9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1', platforms: ['instagram'], scheduled_date: '2026-11-08T09:00:00', timezone: 'Europe/London' },
});
```

```python title="Python"
reelspan.request("POST", "/v1/posts/retry", json_body={
    "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
    "platforms": ["instagram"],
    "scheduled_date": "2026-11-08T09:00:00",
    "timezone": "Europe/London",
})
```

```json
{
  "success": true,
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "message": "Failed platforms scheduled to retry at 2026-11-08T09:00:00.000Z",
  "platforms": ["instagram"],
  "job_id": "sched_3c7a1e9b5d2f48a6b0c4e8d2",
  "scheduled_date": "2026-11-08T09:00:00.000Z"
}
```

A post that was scheduled the first time keeps its `job_id`. A date in the past, more than 365 days ahead, not a date, or an unknown `timezone` gets **400**. Unlike a new scheduled post, the workspace's [default time zone](/api/preferences) isn't used here: without `timezone` the date is read in UTC.

## What gets retried

- Networks that **failed**, and networks that were **skipped** (for example because no account was connected yet, or it needed reconnecting). Connect or reconnect the account first, then retry.
- Not networks that went live, networks still working, or networks of a scheduled post that was cancelled.

## Credits

A network that failed was charged when the post was made, so retrying it costs nothing more. A network that was skipped when the post was made was never charged, so retrying it counts as a new upload, as if you had posted to it now. On a plan with a monthly limit, a retry that would go over it gets **429**.

## When a retry is refused

| Status | `error_code` | Why |
| --- | --- | --- |
| `400` | | Neither `request_id` nor `job_id` was sent, or `scheduled_date` or `timezone` is invalid. |
| `404` | | No post with that id (or your key can't use its profile). |
| `404` | `retry_media_expired` | The post's media has been deleted. Post it again as new. |
| `409` | | The post is still scheduled, or was cancelled. |
| `409` | `NOTHING_TO_RETRY` | Every network went live or is still working, or none of the `platforms` you named failed. |
| `429` | | The retry would go over your monthly upload limit. |

> [!NOTE]
> A post's media is kept for a few days after it finishes (7 by default), then deleted unless it is in the [media library](/api/library). Retry within that time, or keep the file in the library if you may need it later.

Source: https://docs.reelspan.com/api/retry

---

# Unpublish a post

> Delete a live post from the network itself, on Facebook, LinkedIn, X, Pinterest, Bluesky, Google Business, Discord, Telegram, Mastodon or WordPress.

Unpublish deletes a post from the network it went to, so it disappears there too. It works on posts Reelspan published and on posts made outside Reelspan, as long as the profile's connected account may delete them.

> [!WARNING]
> Deleting can't be undone, except on WordPress, where the post goes to the site's trash.

## Delete a post Reelspan published

Name the post by the `request_id` you got when you posted, and the `platform` to delete it from:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/unpublish \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1", "platform": "linkedin"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.request('POST', '/v1/posts/unpublish', {
  json: { request_id: '9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1', platform: 'linkedin' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.request("POST", "/v1/posts/unpublish", json_body={
    "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
    "platform": "linkedin",
})
```

```json
{ "success": true, "platform": "linkedin", "post_id": "urn:li:share:72…", "message": "Deleted from LinkedIn" }
```

`platform` can be left out when the request went live on one network only. When it went live on several, the answer without it is **400** `PLATFORM_REQUIRED`, naming them. Each call deletes one network's post: to remove a post everywhere, call once per network.

For a post Reelspan published, the network's result in [Post status](/api/post-status) then carries `unpublished: true` and `unpublished_at`.

## Delete any post of the account

For a post made outside Reelspan, or when you only have the network's id, send `platform`, the profile in `user`, and the network's `post_id`:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/unpublish \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform": "x", "user": "my-brand", "post_id": "1854123456789012345"}'
```

```javascript title="Node.js"
await reelspan.request('POST', '/v1/posts/unpublish', {
  json: { platform: 'x', user: 'my-brand', post_id: '1854123456789012345' },
});
```

```python title="Python"
reelspan.request("POST", "/v1/posts/unpublish", json_body={"platform": "x", "user": "my-brand", "post_id": "1854123456789012345"})
```

`profile_username` works in place of `user`. The `post_id` is the one each network uses, the same as `post_id` in a post's results.

## Which networks

| Network | `post_id` | Notes |
| --- | --- | --- |
| Facebook | The post, Reel or video id | Page posts. The Page is found from the post id, or the chosen Page is used. |
| LinkedIn | The post URN (`urn:li:share:…`) | A post already gone counts as deleted. |
| X | The post id | |
| Pinterest | The Pin id | A Pin already gone counts as deleted. |
| Bluesky | The `at://` URI, or a `bsky.app/profile/…/post/…` link | Only the connected account's own posts (`post_not_owned` otherwise). |
| Google Business | The post's full name, `accounts/…/locations/…/localPosts/…` | A post already gone counts as deleted. |
| Discord | The message id | Only messages the connected webhook sent. A message already gone counts as deleted. |
| Telegram | The message id | Telegram lets bots delete messages for 48 hours after sending. |
| Mastodon | The status id | |
| WordPress | The post id | Moved to the site's trash, where it can be restored for 30 days. |

Instagram, TikTok, Threads and YouTube posts can't be deleted through Reelspan: the first three have no delete in their APIs (Threads needs a permission Reelspan doesn't hold), and deleting a YouTube video needs a wider permission than the upload access Reelspan asks for. Asking for one of them gets **400** `platform_not_supported`, with the networks that work in `supported_platforms`.

## Errors

| Status | `error_code` | Why |
| --- | --- | --- |
| `400` | `INVALID_REQUEST` | Neither `request_id`, nor `platform` with `post_id`, was sent. |
| `400` | `PLATFORM_REQUIRED` | The request went live on several networks; send `platform`. |
| `400` | `platform_not_supported` | The network can't delete posts through its API. `supported_platforms` lists the ones that can. |
| `400` | `invalid_post_id` | The `post_id` isn't in the network's shape (Bluesky and Google Business check it). |
| `400` | `post_not_owned` | Bluesky: the post belongs to another account. |
| `404` | `NOT_FOUND` | No request with that `request_id` (or your key can't use its profile). |
| `404` | `POST_NOT_FOUND` | The request has no live post on that network, or the network says the post doesn't exist. |
| `404` | `profile_platform_mapping_invalid` | The profile has no account on that network, or the account that published the post was disconnected. |
| `409` | `reauth_required` | The account must be [reconnected](/connecting-accounts) first. |
| `502` | the network's code | The network refused; `error_code` (such as `x_error` or `meta_error`) and `message` say why, and `retryable` says whether trying again may help. |

Unpublishing needs a key with the `publish` scope. To change a post instead of deleting it, see [Edit a post](/api/edit-post).

Source: https://docs.reelspan.com/api/unpublish

---

# Edit a post

> Change the text of a post that is already live, and some settings such as a Pin's link or a WordPress status, on the networks that allow edits.

Edit changes a post after it went live, where the network allows it. Most networks let you change only the text; a few take more. To change a post that hasn't gone out yet, edit the [scheduled post](/api/scheduled-posts) instead.

## Edit a post Reelspan published

Name the post by its `request_id` (and `platform` when it went to several networks) and send the new `text`:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/edit \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
    "platform": "linkedin",
    "text": "We are hiring two engineers in Lisbon. Details and the application form are in the comments."
  }'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const edited = await reelspan.request('POST', '/v1/posts/edit', {
  json: {
    request_id: '9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1',
    platform: 'linkedin',
    text: 'We are hiring two engineers in Lisbon. Details and the application form are in the comments.',
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
edited = reelspan.request("POST", "/v1/posts/edit", json_body={
    "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
    "platform": "linkedin",
    "text": "We are hiring two engineers in Lisbon. Details and the application form are in the comments.",
})
```

```json
{
  "success": true,
  "platform": "linkedin",
  "post_id": "urn:li:share:72…",
  "url": "https://www.linkedin.com/feed/update/urn:li:share:72…/"
}
```

`message` and `commentary` work as other names for `text`. For a post made outside Reelspan, name it with `platform`, `user` and the network's `post_id` instead, as on [Unpublish](/api/unpublish#delete-any-post-of-the-account).

## What you can send

| Field | What it changes |
| --- | --- |
| `text` | The post's text: its caption, message or commentary. |
| `title` | A title, where the post has one: a Facebook video or Reel, a Pin, a WordPress post. |
| `description` | A Pin's description, a Facebook video's description, or a WordPress post's body. |
| `fields` | Network settings by their upload field name, as strings, for example `{"pinterest_link": "https://example.com/new"}`. |

Send only what changes. A request that changes nothing the network can change gets **400** `text_required`.

## Which networks, and what changes

| Network | What can change | Quirks |
| --- | --- | --- |
| Facebook | A post's text. A Reel's or video's description (`text` or `description`) and title (`title`, up to 255 characters). | |
| LinkedIn | The commentary only (up to 3,000 characters). | Media, visibility and the rest stay as they are. |
| X | The text. | Needs X Premium on the account; X allows edits within an hour of posting, up to five times. The edit is a **new post with a new id** (see below). |
| Pinterest | `title` (100 characters), `description` or `text` (800), and in `fields`: `pinterest_link`, `pinterest_alt_text` (500), `pinterest_board_id` and `pinterest_board_section_id` to move the Pin. | The image or video can't change. |
| Google Business | The text (up to 1,500 characters), and the button with `fields.google_business_cta_url` and `fields.google_business_cta` (`gbp_cta_url` and `gbp_cta_type` work too). | |
| Discord | The text (2,000 characters; longer is cut, with a warning). | Only messages the connected webhook sent. Attachments stay. |
| Telegram | The text of a message, or the caption of a photo, video or album. | Send `fields.telegram_parse_mode` again if the new text uses formatting. Longer text is cut to Telegram's limits. |
| Mastodon | The text, and `fields.mastodon_spoiler_text` and `fields.mastodon_sensitive`. | Attachments stay. |
| WordPress | `title`, the body (`text` or `description`), and in `fields`: `wordpress_excerpt` and `wordpress_status` (`publish`, `draft`, `private` or `pending`). | A new body replaces the text and keeps the images and video already in the post. |

Instagram, TikTok, Threads, YouTube and Bluesky posts can't be edited through Reelspan, and Reddit posts aren't supported either. Asking gets **400** `platform_not_supported`, with the networks that work in `supported_platforms`.

## X: an edit is a new post

X makes an edited post a new post that replaces the old one, so the id changes. The answer gives the new id as `post_id`, the old one as `previous_post_id`, and X's list of every version as `edit_history_post_ids`:

```json
{
  "success": true,
  "platform": "x",
  "post_id": "1854123456789099999",
  "url": "https://x.com/mybrand/status/1854123456789099999",
  "previous_post_id": "1854123456789012345",
  "edit_history_post_ids": ["1854123456789012345", "1854123456789099999"]
}
```

For a post Reelspan published, the stored post follows the new id, so [Post status](/api/post-status) and analytics use it from then on. Links are removed from the new text, as when posting, unless `fields.x_keep_links` is `"true"`; keeping them uses one of your plan's X link posts for the month, and when the allowance is used up they are removed anyway. See [Links in X posts](/networks/x#links-in-x-posts).

## After an edit

For a post Reelspan published, the network's result in [Post status](/api/post-status) carries `edited_at` and `edits` (how many times it was edited), and on X `previous_post_ids`. `warnings` in the answer lists anything changed on the way, such as text cut to fit.

## Errors

| Status | `error_code` | Why |
| --- | --- | --- |
| `400` | `INVALID_REQUEST` | Neither `request_id`, nor `platform` with `post_id`, was sent. |
| `400` | `PLATFORM_REQUIRED` | The request went live on several networks; send `platform`. |
| `400` | `platform_not_supported` | The network can't edit posts through its API. `supported_platforms` lists the ones that can. |
| `400` | `text_required` | Nothing the network can change was sent. |
| `400` | `invalid_post_id` | The `post_id` isn't in the network's shape (Google Business checks it). |
| `404` | `NOT_FOUND`, `POST_NOT_FOUND` | No such request, no live post on that network, or the network says the post doesn't exist. |
| `404` | `profile_platform_mapping_invalid` | The profile has no account on that network, or the account that published the post was disconnected. |
| `409` | `reauth_required` | The account must be [reconnected](/connecting-accounts) first. |
| `502` | the network's code | The network refused, for example an X account without Premium, or an edit window that has closed. `message` carries the network's reason. |

Editing needs a key with the `publish` scope.

Source: https://docs.reelspan.com/api/edit-post

---

# Repost

> Share a post again from a profile's account, as a LinkedIn reshare with commentary, an X or Threads repost, a Bluesky repost or a Mastodon boost.

Repost shares a post again from the profile's own account on the same network. The post can be one Reelspan published, one the account made elsewhere, or any public post on the network.

## Repost a post

Name the post by the network's `post_id` with `platform` and the profile in `user`:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/repost \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform": "bluesky", "user": "my-brand", "post_id": "https://bsky.app/profile/partner.bsky.social/post/3kxyz2abcd"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const repost = await reelspan.request('POST', '/v1/posts/repost', {
  json: { platform: 'bluesky', user: 'my-brand', post_id: 'https://bsky.app/profile/partner.bsky.social/post/3kxyz2abcd' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
repost = reelspan.request("POST", "/v1/posts/repost", json_body={
    "platform": "bluesky",
    "user": "my-brand",
    "post_id": "https://bsky.app/profile/partner.bsky.social/post/3kxyz2abcd",
})
```

```json
{
  "success": true,
  "platform": "bluesky",
  "post_id": "https://bsky.app/profile/partner.bsky.social/post/3kxyz2abcd",
  "repost_id": "at://did:plc:abc123/app.bsky.feed.repost/3kz…",
  "url": "https://bsky.app/profile/mybrand.bsky.social",
  "repost_uri": "at://did:plc:abc123/app.bsky.feed.repost/3kz…",
  "subject": "at://did:plc:xyz789/app.bsky.feed.post/3kxyz2abcd"
}
```

To repost something Reelspan published from the same account, send its `request_id` (and `platform` when it went to several networks) instead. `post_id` in the answer is the post that was reposted; `repost_id` is the new repost, where the network gives it one.

## Which networks

| Network | What happens | `post_id` | The answer adds |
| --- | --- | --- | --- |
| LinkedIn | A reshare: a new post on the member's profile that carries the original, with optional `commentary` above it (up to 3,000 characters). | The post URN | `repost_id` and `url` of the new post, `parent_post_id`, `author` |
| X | A repost. X counts reposts against the account's daily write limit. | The post id | `reposted: true`; `repost_id` is the original's id, since X gives no new one |
| Threads | A repost. | The Threads post id | `repost_id`; `url` is the account's profile |
| Bluesky | A repost. | The `at://` URI, or a `bsky.app/profile/…/post/…` link | `repost_uri`, `subject`; `url` is the account's profile |
| Mastodon | A boost. | The status id on the account's own server | `repost_id`, `url` of the boosted post |

Other networks get **400** `platform_not_supported`, with the networks that work in `supported_platforms`.

A LinkedIn reshare with commentary:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/repost \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
    "platform": "linkedin",
    "commentary": "In case you missed it last week: our Q3 report."
  }'
```

For a post Reelspan published, every repost is added to the network's result in [Post status](/api/post-status), under `reposts`.

## Errors

| Status | `error_code` | Why |
| --- | --- | --- |
| `400` | `INVALID_REQUEST` | Neither `request_id`, nor `platform` with `post_id`, was sent. |
| `400` | `PLATFORM_REQUIRED` | The request went live on several networks; send `platform`. |
| `400` | `platform_not_supported` | The network can't repost through its API. |
| `400` | `invalid_post_id` | Bluesky: `post_id` is neither an `at://` URI nor a `bsky.app` post link. |
| `404` | `NOT_FOUND`, `POST_NOT_FOUND` | No such request, no live post on that network, or the network can't find the post. |
| `404` | `profile_platform_mapping_invalid` | The profile has no account on that network. |
| `409` | `reauth_required` | The account must be [reconnected](/connecting-accounts) first. |
| `502` | the network's code | The network refused, for example a post already reposted or X's daily limit. `message` carries the network's reason. |

Reposting needs a key with the `publish` scope.

Source: https://docs.reelspan.com/api/repost

---

# YouTube thumbnail

> Set a new custom thumbnail on a YouTube video that is already published, from a file, a public link or an earlier upload, by video id or request_id.

Changes the thumbnail of a video already on YouTube. To set one while posting, send `thumbnail` with the video instead (see [YouTube](/networks/youtube)).

## Set a thumbnail

Send the image as a multipart `thumbnail` file, with the profile in `user` and the YouTube `video_id`:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/youtube/thumbnail \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "video_id=aB3xYz12Q" \
  -F "thumbnail=@thumbnail.jpg"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const out = await reelspan.request('POST', '/v1/youtube/thumbnail', {
  json: { user: 'my-brand', video_id: 'aB3xYz12Q', thumbnail_url: 'https://example.com/thumbnail.jpg' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
out = reelspan.request("POST", "/v1/youtube/thumbnail", json_body={
    "user": "my-brand",
    "video_id": "aB3xYz12Q",
    "thumbnail_url": "https://example.com/thumbnail.jpg",
})
```

```json
{
  "success": true,
  "video_id": "aB3xYz12Q",
  "width": 1280,
  "height": 720,
  "thumbnails": {
    "default": { "url": "https://i.ytimg.com/vi/aB3xYz12Q/default.jpg", "width": 120, "height": 90 },
    "high": { "url": "https://i.ytimg.com/vi/aB3xYz12Q/hqdefault.jpg", "width": 480, "height": 360 },
    "maxres": { "url": "https://i.ytimg.com/vi/aB3xYz12Q/maxresdefault.jpg", "width": 1280, "height": 720 }
  }
}
```

`width` and `height` are those of the largest size YouTube made; `thumbnails` lists every size.

## The image

Send one of these; when more than one is sent, the file wins, then the URL:

- `thumbnail`: the file, in a `multipart/form-data` body.
- `thumbnail_url`: a public https URL (in JSON or multipart).
- `thumbnail_media_id`: a photo [uploaded earlier](/api/upload-media) with `kind=photo`.

It must be JPEG, PNG, GIF or BMP and at most 2 MB. Reelspan doesn't keep the file afterwards; a `thumbnail_media_id` stays in your uploads.

## Which video

- `video_id` and `user` (or `profile_username`): any video on the profile's connected YouTube channel, including ones uploaded outside Reelspan. `post_id` works in place of `video_id`.
- Or `request_id`: the Reelspan request that published the video.

## Good to know

- **A verified channel.** YouTube allows custom thumbnails only on channels verified at [youtube.com/verify](https://www.youtube.com/verify). On other channels YouTube refuses with 403, which comes back as **502** `youtube_forbidden`.
- **Shorts** don't show custom thumbnails on YouTube, even when one is set.
- Thumbnails are the only change Reelspan can make to a published video: editing or deleting it needs a wider YouTube permission than the upload access Reelspan asks for.

## Errors

| Status | `error_code` | Why |
| --- | --- | --- |
| `400` | `MEDIA_REQUIRED` | No `thumbnail`, `thumbnail_url` or `thumbnail_media_id` was sent. |
| `400` | `UNSUPPORTED_MEDIA` | The image isn't JPEG, PNG, GIF or BMP. |
| `400` | `MEDIA_NOT_FOUND` | `thumbnail_media_id` isn't an image of this workspace. |
| `400` | `INVALID_REQUEST` | Neither `request_id`, nor `video_id` with `user`, was sent, or the body isn't JSON or multipart. |
| `404` | `NOT_FOUND`, `POST_NOT_FOUND` | No such request, or it has no live YouTube video. |
| `404` | `profile_platform_mapping_invalid` | The profile has no YouTube channel connected. |
| `409` | `reauth_required` | The channel must be [reconnected](/connecting-accounts) first. |
| `413` | `FILE_TOO_LARGE` | The image is over 2 MB. |
| `502` | `youtube_forbidden` | The channel isn't verified for custom thumbnails, or YouTube refused for another reason in `message`. |
| `502` | `youtube_…` | YouTube refused; `message` carries its reason. |

Setting a thumbnail needs a key with the `publish` scope.

Source: https://docs.reelspan.com/api/youtube-thumbnail

---

# Publishing limits

> See how many more posts a profile's Instagram and Threads accounts may publish in the next 24 hours, read live from each network's own quota.

Instagram and Threads cap how many posts an account can publish through their APIs in a moving 24-hour window. This endpoint asks each network how much of that an account has used, so you can hold a post back instead of watching it fail.

```bash title="cURL"
curl "https://api.reelspan.com/v1/publishing-limits?profile=my-brand" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { limits } = await reelspan.request('GET', '/v1/publishing-limits', { query: { profile: 'my-brand' } });
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
limits = reelspan.request("GET", "/v1/publishing-limits", query={"profile": "my-brand"})["limits"]
```

```json
{
  "success": true,
  "limits": {
    "instagram": {
      "posts": { "used": 12, "limit": 50, "remaining": 38, "window_seconds": 86400 },
      "limit_reached": false,
      "fetched_at": "2026-11-07T10:15:02.114Z",
      "cached": false
    },
    "threads": {
      "posts": { "used": 4, "limit": 250, "remaining": 246, "window_seconds": 86400 },
      "replies": { "used": 31, "limit": 1000, "remaining": 969, "window_seconds": 86400 },
      "limit_reached": false,
      "fetched_at": "2026-11-07T10:15:02.380Z",
      "cached": false
    }
  }
}
```

## The answer

- **One entry per network** the profile has connected, of Instagram and Threads. A network that isn't connected is left out. `platform=instagram` or `platform=threads` asks for one only; then a network that isn't connected gets **404** `profile_platform_mapping_invalid`.
- `posts`: `used` in the window, the network's `limit`, what is `remaining`, and the window's length in `window_seconds` (24 hours). Threads adds `replies`, counted separately; a `first_comment` on Threads is a reply.
- `limit_reached` is `true` when no posts are left.
- The numbers come from the networks. Instagram reports a quota of 50 posts, and a carousel counts as one. Threads allows 250 posts and 1,000 replies.

The profile goes in `profile` (`profile_username` and `user` work too).

## Caching

Each account's answer is kept for 60 seconds, so calls in a burst don't each reach the network: `cached` is `true` on those, and `fetched_at` says when the numbers were read. Add `refresh=true` to read them again now.

## When a network doesn't answer

A network that fails doesn't fail the call. It is left out of `limits` and listed under `errors` instead:

```json
{
  "success": true,
  "limits": {
    "threads": { "posts": { "used": 4, "limit": 250, "remaining": 246, "window_seconds": 86400 }, "replies": { "used": 31, "limit": 1000, "remaining": 969, "window_seconds": 86400 }, "limit_reached": false, "fetched_at": "2026-11-07T10:15:02.380Z", "cached": false }
  },
  "errors": {
    "instagram": { "error": "The Instagram account needs to be reconnected", "error_code": "reauth_required" }
  }
}
```

`reauth_required` means the account must be [reconnected](/connecting-accounts); any other code is the network's own.

Reading limits needs a key with the `read` scope. See [Network posting limits](/limits/network-limits) for the caps on other networks.

Source: https://docs.reelspan.com/api/publishing-limits

---

# Scheduled posts

> List the posts waiting to go out, preview their media, move one to a new time, change its caption, settings or cover, or cancel it and get credits back.

A post sent with `scheduled_date`, `add_to_queue` or `repeat_every` waits here until its time, under a `job_id`. Until a minute before it goes out you can read it, edit it, or cancel it.

## List what's scheduled

```bash title="cURL"
curl "https://api.reelspan.com/v1/scheduled?profile_username=my-brand" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { scheduled_posts, total } = await reelspan.scheduled.list({ profile_username: 'my-brand' });
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
page = reelspan.scheduled.list(profile_username="my-brand")
```

```json
{
  "scheduled_posts": [
    {
      "job_id": "sched_5d0e8c1a7b3f49e2a6c4d8b0",
      "request_id": "2f8a6c4e0b1d4f7a9c3e5b7d1a0c2e4f",
      "scheduled_date": "2026-12-01T09:00:00.000Z",
      "original_timezone": "Europe/London",
      "post_type": "video",
      "profile_username": "my-brand",
      "platforms": ["tiktok", "youtube"],
      "title": "Launch day",
      "description": null,
      "external_id": null,
      "queued": false,
      "caption": null,
      "platform_content": {
        "tiktok": { "title": "Launch day", "description": null },
        "youtube": { "title": "Launch day, in 60 seconds", "description": null }
      },
      "fields": {
        "user": "my-brand",
        "platform[]": ["tiktok", "youtube"],
        "title": "Launch day",
        "youtube_title": "Launch day, in 60 seconds",
        "scheduled_date": "2026-12-01T09:00:00",
        "timezone": "Europe/London"
      },
      "has_cover": false,
      "has_preview": true,
      "thumbnail_url": "https://api.reelspan.com/v1/scheduled/sched_5d0e8c1a7b3f49e2a6c4d8b0/thumbnail",
      "preview_url": "https://api.reelspan.com/v1/scheduled/sched_5d0e8c1a7b3f49e2a6c4d8b0/preview",
      "editable": true,
      "repeat": null,
      "approval": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

Posts come soonest first. Filter with `profile_username`, and with `from` and `to` (date-times with an offset; `to` not included). Page with `limit` (1 to 200, default 50) and `offset`.

Each post shows:

- `scheduled_date` in UTC, and `original_timezone`, the zone it was scheduled in.
- `post_type`: `video`, `photo`, `text` or `document`.
- `caption`: the same as `description` (Upload-Post's name for it).
- `platform_content`: the title and description each network will get.
- `fields`: every field the post was sent with.
- `has_cover`: whether a video post has its own cover image.
- `has_preview`: whether the post has media to [preview](#see-the-media).
- `thumbnail_url` and `preview_url`: links to the [thumbnail and preview](#see-the-media) endpoints, or `null` when the post has no media (a text post has no thumbnail). They are API links, so call them with your key.
- `queued`: `true` when it took a [queue](/api/queue) slot.
- `editable`: `false` once it is less than a minute from its time.
- `repeat`: for one post of a [repeating series](/guides/scheduling), its `series_id`, its `index`, how many `times` and how often (`every`).
- `approval`: when it is in an [approval link](/api/approval-links), the link's id and the client's answer (`pending`, `approved` or `changes`, with their comment).

## Read one

`GET /v1/scheduled/{job_id}` returns the same fields plus `status` and `form` (the same as `fields`):

```javascript title="Node.js"
const post = await reelspan.scheduled.get('sched_5d0e8c1a7b3f49e2a6c4d8b0');
console.log(post.form.privacy_level);
```

```python title="Python"
post = reelspan.scheduled.get("sched_5d0e8c1a7b3f49e2a6c4d8b0")
print(post["form"].get("privacy_level"))
```

## See the media

Two endpoints show what a scheduled post will publish, for a calendar or a review screen.

`GET /v1/scheduled/{job_id}/thumbnail` gives a small JPEG, 480 px wide: a frame of the video, or the cover or first photo. It answers with a **302** redirect to a signed link valid for an hour; the request itself needs your key, the signed link doesn't. Add `?format=json` to get the link instead, for example to put in an `<img>` tag:

```bash title="cURL"
curl "https://api.reelspan.com/v1/scheduled/sched_5d0e8c1a7b3f49e2a6c4d8b0/thumbnail?format=json"   -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const { thumbnail_url } = await reelspan.request('GET', '/v1/scheduled/sched_5d0e8c1a7b3f49e2a6c4d8b0/thumbnail', { query: { format: 'json' } });
```

```python title="Python"
thumb = reelspan.request("GET", "/v1/scheduled/sched_5d0e8c1a7b3f49e2a6c4d8b0/thumbnail", query={"format": "json"})
```

```json
{ "success": true, "thumbnail_url": "https://…", "expires_in": 3600 }
```

The first request makes the image, so it can take a few seconds. A text post, or one with no media, gets **404** `NO_MEDIA`; when no image can be made from the media, the answer is **404** `THUMBNAIL_UNAVAILABLE`.

`GET /v1/scheduled/{job_id}/preview` lists every file the post will publish, each with a signed link valid for an hour:

```json
{
  "success": true,
  "job_id": "sched_5d0e8c1a7b3f49e2a6c4d8b0",
  "expires_in": 3600,
  "media": [
    { "role": "video", "media_id": "med_…", "kind": "video", "content_type": "video/mp4", "size_bytes": 18350212, "url": "https://…" },
    { "role": "cover", "media_id": "med_…", "kind": "photo", "content_type": "image/jpeg", "size_bytes": 241337, "url": "https://…" }
  ]
}
```

`role` is `video`, `photo`, `document`, `cover`, `thumbnail`, or `<network>_photo` for photos sent to one network only.

## Reschedule or edit

`PATCH /v1/scheduled/{job_id}` changes the time, the text, any setting and a video's cover. Send only what changes:

| Field | What it does |
| --- | --- |
| `scheduled_date` | The new time, ISO 8601, at least a minute ahead and within 365 days. |
| `timezone` | The zone `scheduled_date` is in. Defaults to the zone the post was scheduled in. |
| `title`, `description` | The caption and the longer text. `caption` is another name for `description`. |
| `platform_content` | Text for one network: `{ "tiktok": { "title": "…" } }` sets `tiktok_title`, `description` sets `tiktok_description`. `null` removes one, so the network falls back to the overall text. Naming a network the post doesn't go to gets **400**. |
| `fields` | Any other post field, such as `{ "youtube_title": "…", "privacy_level": "SELF_ONLY" }`. `null` removes one. |
| `cover_image_url`, `cover_image_base64`, `cover_media_id` | A new cover for a video post (JPEG, PNG or WebP, up to 20 MB): a public https URL, base64 (a `data:` prefix is fine), or an image [uploaded](/api/upload-media) with `kind=photo`. |
| `remove_cover` | `true` removes the cover, so the networks pick a frame themselves. |

Send at most one of the four cover fields; more gets **400**. Covers are for video posts only: on a photo, text or document post the answer is **400**.

```bash title="cURL"
curl -X PATCH https://api.reelspan.com/v1/scheduled/sched_5d0e8c1a7b3f49e2a6c4d8b0 \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_date": "2026-12-02T18:30:00",
    "timezone": "Europe/London",
    "fields": { "youtube_title": "Launch day, one day late", "tiktok_title": null }
  }'
```

```javascript title="Node.js"
await reelspan.scheduled.edit('sched_5d0e8c1a7b3f49e2a6c4d8b0', {
  scheduled_date: '2026-12-02T18:30:00',
  timezone: 'Europe/London',
  fields: { youtube_title: 'Launch day, one day late', tiktok_title: null },
});
```

```python title="Python"
reelspan.scheduled.edit(
    "sched_5d0e8c1a7b3f49e2a6c4d8b0",
    scheduled_date="2026-12-02T18:30:00",
    timezone="Europe/London",
    fields={"youtube_title": "Launch day, one day late", "tiktok_title": None},
)
```

To change only the TikTok caption and the cover:

```bash title="cURL"
curl -X PATCH https://api.reelspan.com/v1/scheduled/sched_5d0e8c1a7b3f49e2a6c4d8b0   -H "Authorization: Bearer $REELSPAN_API_KEY"   -H "Content-Type: application/json"   -d '{
    "platform_content": { "tiktok": { "title": "Launch day 🚀 #launch" } },
    "cover_image_url": "https://example.com/launch-cover.jpg"
  }'
```

```javascript title="Node.js"
await reelspan.request('PATCH', '/v1/scheduled/sched_5d0e8c1a7b3f49e2a6c4d8b0', {
  json: {
    platform_content: { tiktok: { title: 'Launch day 🚀 #launch' } },
    cover_image_url: 'https://example.com/launch-cover.jpg',
  },
});
```

```python title="Python"
reelspan.scheduled.edit(
    "sched_5d0e8c1a7b3f49e2a6c4d8b0",
    platform_content={"tiktok": {"title": "Launch day 🚀 #launch"}},
    cover_image_url="https://example.com/launch-cover.jpg",
)
```

The answer is the updated post. Some things are fixed once a post is scheduled:

- The profile, the networks and the video or photos can't change. Sending `user`, `platform[]`, `video`, `photos[]` or `request_id` in `fields` gets **400**. To change them, cancel the post and make a new one.
- A queued post that you give a `scheduled_date` leaves the queue and keeps that exact time.
- Editing a post that is in an [approval link](/api/approval-links) sends it back to the client for approval.

## Cancel

`DELETE /v1/scheduled/{job_id}` cancels the post, and the upload credits it reserved come back.

```bash title="cURL"
curl -X DELETE https://api.reelspan.com/v1/scheduled/sched_5d0e8c1a7b3f49e2a6c4d8b0 \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
await reelspan.scheduled.cancel('sched_5d0e8c1a7b3f49e2a6c4d8b0');
```

```python title="Python"
reelspan.scheduled.cancel("sched_5d0e8c1a7b3f49e2a6c4d8b0")
```

```json
{ "success": true, "message": "Job sched_5d0e8c1a7b3f49e2a6c4d8b0 cancelled and assets deleted.", "credits_refunded": 2 }
```

`credits_refunded` is the number of networks given back (0 for a test post, which never took any). The post's networks show as skipped in [History](/api/history), with the error code `cancelled`.

### Cancel the rest of a series

Each post of a repeating series is its own scheduled post with its own `job_id`, so you can edit or cancel one without touching the others. To stop the series from one post onwards, add `series=rest`: that post and every later one still waiting are cancelled.

```bash title="cURL"
curl -X DELETE "https://api.reelspan.com/v1/scheduled/sched_5d0e8c1a7b3f49e2a6c4d8b0?series=rest" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
await reelspan.scheduled.cancel('sched_5d0e8c1a7b3f49e2a6c4d8b0', { withLaterRepeats: true });
```

```python title="Python"
reelspan.scheduled.cancel("sched_5d0e8c1a7b3f49e2a6c4d8b0", with_later_repeats=True)
```

```json
{ "success": true, "message": "4 posts of the series cancelled.", "credits_refunded": 8, "cancelled": 4 }
```

Earlier posts of the series are left alone, and so is any that is already publishing or due within a minute. On a post that isn't part of a series, `series=rest` cancels just that post.

## Too late to change

Once a post is publishing, or is less than a minute from its time, an edit or a cancel gets **409** with `error_code: "scheduled_post_in_progress"`. Check `editable` first if you are close to the time. A post still waiting for a client's approval is the exception: it can be edited or cancelled even after its time has passed.

An unknown `job_id`, or one of a profile your key can't use, gets **404**.

Source: https://docs.reelspan.com/api/scheduled-posts

---

# Queue

> Give each profile a posting schedule of days and times, then add posts with add_to_queue and they take the next free slot. Preview slots and block busy ones.

The queue saves you picking a time for every post. Each profile has a weekly schedule of slots; a post sent with `add_to_queue=true` takes the first slot that still has room.

## Add a post to the queue

Send any post with `add_to_queue=true` instead of a `scheduled_date`:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "platform[]=instagram" \
  -F "title=Behind the scenes" \
  -F "add_to_queue=true" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['tiktok', 'instagram'],
  title: 'Behind the scenes',
  addToQueue: true,
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video("my-brand", ["tiktok", "instagram"], "launch.mp4", "Behind the scenes", add_to_queue=True)
```

```json
{
  "success": true,
  "job_id": "sched_7a2c9e4b1d6f40a8c3e5b9d2",
  "request_id": "6e3b9d1f7a2c4e8b0d5f3a1c9e7b2d4f",
  "scheduled_date": "2026-12-01T12:00:00.000Z",
  "queue_slot": "2026-12-01T12:00:00.000Z",
  "message": "Post added to queue"
}
```

The answer is **202**, and from then on it is an ordinary [scheduled post](/api/scheduled-posts): edit or cancel it by `job_id`. Giving it a `scheduled_date` later takes it out of the queue.

- `add_to_queue` and `scheduled_date` can't be used together (**400**).
- `max_posts_per_slot` on the post overrides the profile's setting for this one post (1 to 100).
- The queue looks 30 days ahead. With no free slot in that time the answer is **400** `QUEUE_FULL`.
- Two posts sent at once never take the same last place in a slot.

## The schedule

Until you set one, every profile has this schedule:

```json
{
  "timezone": "America/New_York",
  "slots": [{ "hour": 9, "minute": 0 }, { "hour": 12, "minute": 0 }, { "hour": 17, "minute": 0 }],
  "days_of_week": [0, 1, 2, 3, 4, 5, 6],
  "max_posts_per_slot": 1,
  "full_slots": []
}
```

| Setting | What it is |
| --- | --- |
| `timezone` | The IANA zone the slots are in. |
| `slots` | Up to 24 times of day, as `hour` (0 to 23) and `minute` (0 to 59). |
| `days_of_week` | The days the slots run, `0` = Monday to `6` = Sunday. |
| `max_posts_per_slot` | How many posts one slot holds, 1 to 100. |
| `full_slots` | Slots you marked full by hand (see below). |

Read it with `GET /v1/queue/settings?profile_username=my-brand`. Change it with `POST /v1/queue/settings`; send only what changes, and the rest stays:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/queue/settings \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_username": "my-brand",
    "timezone": "Europe/London",
    "slots": [{ "hour": 8, "minute": 30 }, { "hour": 18, "minute": 0 }],
    "days_of_week": [0, 1, 2, 3, 4]
  }'
```

```javascript title="Node.js"
await reelspan.queue.setSettings('my-brand', {
  timezone: 'Europe/London',
  slots: [{ hour: 8, minute: 30 }, { hour: 18, minute: 0 }],
  days_of_week: [0, 1, 2, 3, 4],
});
```

```python title="Python"
reelspan.queue.set_settings(
    "my-brand",
    timezone="Europe/London",
    slots=[{"hour": 8, "minute": 30}, {"hour": 18, "minute": 0}],
    days_of_week=[0, 1, 2, 3, 4],
)
```

Duplicate slots are dropped and the list is sorted. Posts already in the queue keep their times when the schedule changes.

## How full is each slot

`GET /v1/queue/preview` lists the next slots (10 by default, `count` up to 50) and how many posts each holds:

```bash title="cURL"
curl "https://api.reelspan.com/v1/queue/preview?profile_username=my-brand&count=3" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const preview = await reelspan.queue.preview('my-brand');
```

```python title="Python"
preview = reelspan.queue.preview("my-brand")
```

```json
{
  "success": true,
  "timezone": "Europe/London",
  "max_posts_per_slot": 1,
  "slots": [
    { "datetime_utc": "2026-12-01T08:30:00.000Z", "datetime_local": "2026-12-01T08:30:00", "available": false, "post_count": 1, "max_posts_per_slot": 1, "is_full": true, "manually_full": false },
    { "datetime_utc": "2026-12-01T18:00:00.000Z", "datetime_local": "2026-12-01T18:00:00", "available": true, "post_count": 0, "max_posts_per_slot": 1, "is_full": false, "manually_full": false },
    { "datetime_utc": "2026-12-02T08:30:00.000Z", "datetime_local": "2026-12-02T08:30:00", "available": true, "post_count": 0, "max_posts_per_slot": 1, "is_full": false, "manually_full": false }
  ],
  "next_available": "2026-12-01T18:00:00.000Z"
}
```

`post_count` counts every post of the profile scheduled for exactly that time, queued or not. A slot less than a minute away isn't offered.

For just the next free slot, `GET /v1/queue/next-slot` answers `{ "next_slot": { "datetime_utc", "datetime_local", "timezone" } }`, or `"next_slot": null` when nothing is free in the next 30 days.

## Keep a slot free

Mark a slot full and the queue skips it, for example to keep a launch slot for one hand-picked post. `slot_datetime` is the slot's time with an offset, as `datetime_utc` shows it:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/queue/slot-full \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "slot_datetime": "2026-12-01T18:00:00Z"}'
```

```javascript title="Node.js"
await reelspan.queue.markFull('my-brand', '2026-12-01T18:00:00Z');
await reelspan.queue.markOpen('my-brand', '2026-12-01T18:00:00Z'); // open it again
```

```python title="Python"
reelspan.queue.mark_full("my-brand", "2026-12-01T18:00:00Z")
reelspan.queue.mark_open("my-brand", "2026-12-01T18:00:00Z")  # open it again
```

Both answer with `full_slots`, the slots now marked. `DELETE /v1/queue/slot-full` with the same body opens a slot again. Past slots drop off the list on their own.

## Keys and scopes

Reading the queue needs the `read` scope; changing the schedule or marking slots needs `profiles`; adding a post needs `publish`.

Source: https://docs.reelspan.com/api/queue

---

# Approval links

> Send scheduled posts to a client as one link they open without an account. Each post waits for their approval, and they can ask for changes instead.

An approval link puts a client in the loop before anything goes out. Schedule the posts as usual, put them in a link, and send the link to the client. They see each post as it will appear and approve it or ask for changes. A post in a link doesn't publish until it is approved.

## Create a link

Name the profile and the scheduled posts, by `job_ids` or `request_ids`:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/approval-links \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_username": "my-brand",
    "job_ids": ["sched_5d0e8c1a7b3f49e2a6c4d8b0", "sched_7a2c9e4b1d6f40a8c3e5b9d2"],
    "title": "December posts",
    "note": "Two posts for the launch week. Approve each, or tell us what to change.",
    "expires_in_days": 7
  }'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { approval_link } = await reelspan.approvals.create({
  user: 'my-brand',
  jobIds: ['sched_5d0e8c1a7b3f49e2a6c4d8b0', 'sched_7a2c9e4b1d6f40a8c3e5b9d2'],
  title: 'December posts',
  note: 'Two posts for the launch week. Approve each, or tell us what to change.',
  expiresInDays: 7,
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
link = reelspan.approvals.create(
    "my-brand",
    ["sched_5d0e8c1a7b3f49e2a6c4d8b0", "sched_7a2c9e4b1d6f40a8c3e5b9d2"],
    title="December posts",
    note="Two posts for the launch week. Approve each, or tell us what to change.",
    expires_in_days=7,
)["approval_link"]
```

```json
{
  "success": true,
  "approval_link": {
    "id": "apl_Hk3mP9qT2vX7wZ1bN5cR",
    "title": "December posts",
    "note": "Two posts for the launch week. Approve each, or tell us what to change.",
    "url": "https://app.reelspan.com/approve/…",
    "expires_at": "2026-12-08T10:15:00.000Z",
    "created_at": "2026-12-01T10:15:00.000Z",
    "posts": { "pending": 2, "approved": 0, "changes": 0 }
  }
}
```

Send `url` to the client. It works without a Reelspan account until `expires_at`, so treat it like a password: anyone with the link can answer for the client.

- Up to 100 posts per link, all scheduled and all of the named profile. Any other post gets **400** `NOT_SCHEDULED`; an id that doesn't exist gets **404**.
- `title` is up to 120 characters (default "Posts to approve"); `note`, shown above the posts, up to 1,000.
- `expires_in_days` is 1 to 60, 14 by default.
- A post can be in one link at a time. Putting it in a new link takes it out of the old one.

The SDKs take `job_ids`; to pass `request_ids`, use `request('POST', '/v1/approval-links', …)`.

## What the client sees

The link opens a page with the link's title, your note, and each post in time order:

- the networks it goes to, and when, in the time zone the posts were scheduled in;
- the video, or up to four of the photos;
- the caption;
- **Approve** and **Request changes**. Asking for changes needs a comment saying what should change.

The client can change an answer until the post goes out. On a plan with white-label, the page shows the profile's logo and says it was sent by the brand; otherwise it says it was sent with Reelspan. It is shown in the profile's white-label language if one is set, else in the browser's. An expired or deleted link shows a short message instead.

## How a post waits

- **Pending or changes asked:** the post doesn't publish. When its time comes it keeps waiting, still listed in [Scheduled posts](/api/scheduled-posts).
- **Approved before its time:** it publishes at its scheduled time as usual.
- **Approved after its time:** it publishes at once.
- **Edited:** changing a post with `PATCH /v1/scheduled/{job_id}` sends it back to the client as pending. A waiting post can be edited, and given a new time, even after its original time has passed.
- **Cancelled:** cancel it as any scheduled post; the page then shows it as cancelled, with no buttons.

## Follow the answers

`GET /v1/approval-links` lists links newest first (up to 100), each with its counts. Filter by `profile_username`:

```javascript title="Node.js"
const { approval_links } = await reelspan.approvals.list('my-brand');
for (const l of approval_links) console.log(l.title, l.posts);
```

```python title="Python"
for l in reelspan.approvals.list("my-brand")["approval_links"]:
    print(l["title"], l["posts"])
```

Each post's own answer is on the post: `GET /v1/scheduled` and `GET /v1/scheduled/{job_id}` include `approval` with the link's id, the `status` (`pending`, `approved` or `changes`), the client's `comment` and when they decided. Every answer also shows as a notification in the dashboard.

## Delete a link

`DELETE /v1/approval-links/{id}` removes the link. Its posts stop waiting: they publish at their scheduled times, and any whose time has already passed publish at once.

```bash title="cURL"
curl -X DELETE https://api.reelspan.com/v1/approval-links/apl_Hk3mP9qT2vX7wZ1bN5cR \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
await reelspan.approvals.delete('apl_Hk3mP9qT2vX7wZ1bN5cR');
```

```python title="Python"
reelspan.approvals.delete("apl_Hk3mP9qT2vX7wZ1bN5cR")
```

> [!WARNING]
> When a link expires, the client can no longer open it, but its unanswered posts keep waiting. Put them in a new link, or delete the old one to let them publish.

Creating and deleting links needs the `publish` scope; listing them needs `read`.

Source: https://docs.reelspan.com/api/approval-links

---

# Webhooks

> Get a signed POST on your server as each network's post goes live or fails, and when accounts connect or need reconnecting. Events, payloads, signatures, retries.

Instead of polling for results, give Reelspan a URL. It sends a signed JSON `POST` there each time a network's post finishes and each time an account is connected, disconnected or needs reconnecting.

## Events

| Event | Sent when |
| --- | --- |
| `upload_completed` | One network's post went live or failed. A post to three networks sends three. |
| `social_account_connected` | An account was connected (or reconnected) to a profile. |
| `social_account_disconnected` | An account was disconnected from a profile. |
| `social_account_reauth_required` | A network signed Reelspan out of an account; posts to it fail until it is reconnected. |

Skipped networks (no account connected, for example) don't send `upload_completed`. A test event, `test`, is sent only when you ask for one.

## Set up an endpoint

Set the account webhook in the dashboard under **Settings**, or with the API. Your URL must use `https://` and be publicly reachable.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/webhook \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://example.com/reelspan",
    "webhook_events": ["upload_completed", "social_account_reauth_required"]
  }'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { notifications } = await reelspan.webhooks.set('https://example.com/reelspan', ['upload_completed', 'social_account_reauth_required']);
console.log(notifications.webhook_secret); // keep this to check signatures
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
notifications = reelspan.webhooks.set("https://example.com/reelspan", ["upload_completed", "social_account_reauth_required"])["notifications"]
print(notifications["webhook_secret"])  # keep this to check signatures
```

```json
{
  "success": true,
  "notifications": {
    "channels": { "webhook": true },
    "webhook_url": "https://example.com/reelspan",
    "webhook_events": {
      "upload_completed": true,
      "social_account_connected": false,
      "social_account_disconnected": false,
      "social_account_reauth_required": true
    },
    "webhook_secret": "whsec_…",
    "consecutive_failures": 0
  }
}
```

- Leave out `webhook_events` to get all four. It also takes an object of booleans (`{ "upload_completed": true }`) and dotted names (`social_account.connected`). An unknown event name gets **400** `INVALID_WEBHOOK`.
- Saving again changes the URL or events and keeps the signing secret. `GET /v1/webhook` reads the settings, secret included; `DELETE /v1/webhook` (or `"channels": { "webhook": false }`) removes the webhook.
- The key needs the `webhooks` scope, which is off by default when you create a key in the dashboard. The account webhook also needs a key that isn't limited to some profiles.

### A webhook per profile

A profile can have its own endpoint, sent **in addition to** the account one, for that profile's events only. Useful when each client has their own server.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/profile-webhook \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "client-a", "webhook_url": "https://client-a.example.com/hooks"}'
```

```javascript title="Node.js"
const { webhook } = await reelspan.webhooks.profile.set('client-a', 'https://client-a.example.com/hooks');
```

```python title="Python"
webhook = reelspan.webhooks.profile.set("client-a", "https://client-a.example.com/hooks")["webhook"]
```

It has its own `webhook_secret`, in the answer under `webhook`. Read it with `GET /v1/profile-webhook?profile_username=client-a` and remove it with `DELETE /v1/profile-webhook` and `{"profile_username": "client-a"}` as the body. A key limited to some profiles can manage the webhooks of those profiles.

## Payloads

Every delivery is a JSON body with `event`, the event's data and `created_at`.

### upload_completed

```json
{
  "event": "upload_completed",
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "job_id": null,
  "external_id": "campaign-42",
  "profile_username": "my-brand",
  "platform": "tiktok",
  "media_type": "video",
  "title": "Launch day",
  "caption": "Launch day #behindthescenes",
  "result": {
    "success": true,
    "url": "https://www.tiktok.com/@mybrand/video/7441…",
    "post_id": "7441…",
    "error": null,
    "error_code": null
  },
  "created_at": "2026-12-01T09:00:41.512Z"
}
```

- `platform` is the one network this event is about; `media_type` is `video`, `photo`, `text` or `document`.
- `title` is the post's `title`; `caption` is the text this network got (its `{network}_title`, else `title`).
- `result` says how it went: `url` and `post_id` when it went live, `error` and `error_code` when it failed. It can carry more keys from the network, such as `first_comment`. A [test key](/guides/test-mode) post arrives with `"success": true`, `"test": true`, a `post_id` starting with `test_` and no `url`.
- `request_id`, `job_id` and `external_id` tie it back to the post you made.

### Account events

```json
{
  "event": "social_account_reauth_required",
  "platform": "instagram",
  "account_name": "mybrand",
  "status": "reauth_required",
  "profile_username": "my-brand",
  "reason": "token_refresh_failed",
  "created_at": "2026-12-01T09:00:41.512Z"
}
```

`status` is `connected`, `disconnected` or `reauth_required`. `reason` is there when Reelspan knows it: `manual_disconnect` on a disconnect, `token_refresh_failed` or `permission_revoked` when reconnecting is needed.

### test

```json
{ "event": "test", "message": "Webhook test from Reelspan", "created_at": "2026-12-01T09:00:41.512Z" }
```

Send one with `POST /v1/webhook/test` (or `reelspan.webhooks.test()`); the answer has its `delivery_id`. It goes to the account webhook.

## Headers

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |
| `User-Agent` | `Reelspan-Webhooks/1.0` |
| `X-Reelspan-Event` | The event name. |
| `X-Reelspan-Delivery` | The delivery's id. It stays the same across retries, so use it to ignore a delivery you've already handled. |
| `X-Reelspan-Timestamp` | Unix seconds when this attempt was sent. |
| `X-Reelspan-Signature` | `sha256=` and the hex HMAC-SHA256 of `"{timestamp}.{raw body}"`, keyed with your signing secret. |

## Check the signature

Check every delivery before you trust it: compute the HMAC over the timestamp, a dot and the **raw** body (before any JSON parsing), compare it with the header in constant time, and reject timestamps more than a few minutes old so an old delivery can't be replayed.

The SDKs do all of it, with a 5-minute window:

```javascript title="Node.js"
import express from 'express';
import { verifyWebhook } from 'reelspan';

const app = express();
app.post('/reelspan', express.raw({ type: 'application/json' }), async (req, res) => {
  const ok = await verifyWebhook(
    req.body.toString(),
    req.get('x-reelspan-signature'),
    req.get('x-reelspan-timestamp'),
    process.env.REELSPAN_WEBHOOK_SECRET,
  );
  if (!ok) return res.sendStatus(401);
  res.sendStatus(200);
  const event = JSON.parse(req.body.toString());
  // handle the event after answering
});
```

```python title="Python"
import os
from flask import Flask, request
from reelspan import verify_webhook

app = Flask(__name__)

@app.post("/reelspan")
def reelspan_hook():
    ok = verify_webhook(
        request.get_data(),
        request.headers.get("X-Reelspan-Signature"),
        request.headers.get("X-Reelspan-Timestamp"),
        os.environ["REELSPAN_WEBHOOK_SECRET"],
    )
    if not ok:
        return "", 401
    event = request.get_json()
    # queue the event and answer straight away
    return "", 200
```

Without the SDK, it is a few lines in any language:

```javascript title="Node.js"
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, signature, timestamp, secret) {
  if (!signature || !/^\d+$/.test(timestamp ?? '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; // older than 5 minutes
  const expected = 'sha256=' + createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  return signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
```

```python title="Python"
import hashlib
import hmac
import time

def verify(raw_body: bytes, signature: str | None, timestamp: str | None, secret: str) -> bool:
    if not signature or not timestamp or not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > 300:  # older than 5 minutes
        return False
    signed = f"{timestamp}.".encode() + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)
```

> [!WARNING]
> Sign the body exactly as it arrived. A framework that parses JSON and you then re-serialise it will change the bytes and the check will fail.

## Answer quickly

Answer with any `2xx` within 10 seconds. Anything else counts as a failed attempt: another status, a timeout, a connection error, or a redirect (redirects aren't followed). Do slow work after you answer, and make your handler safe to run twice for the same `X-Reelspan-Delivery`.

## Retries

A failed delivery is tried again, up to 8 attempts in all, waiting longer each time:

| After attempt | Next attempt in |
| --- | --- |
| 1 | 1 minute |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 6 hours |
| 6 | 12 hours |
| 7 | 24 hours |

Each attempt has a fresh timestamp and signature. Retries mean deliveries can arrive out of order, so use `created_at` and the post's status, not arrival order.

If something keeps failing, the workspace gets a dashboard notification (at most one a day per endpoint). After 20 deliveries in a row have failed every attempt, the endpoint is paused (`GET /v1/webhook` then shows `"channels": { "webhook": false }`) and you get a notification and an email. Fix it, then save the webhook again (`POST /v1/webhook` or the dashboard) to turn it back on.

## Delivery log

`GET /v1/webhook/deliveries` lists the workspace's recent deliveries, newest first, for the account and every profile webhook. `limit` is 1 to 200 (default 50).

```javascript title="Node.js"
const { deliveries } = await reelspan.webhooks.deliveries();
for (const d of deliveries.filter((d) => d.status === 'failed')) await reelspan.webhooks.redeliver(d.id);
```

```python title="Python"
for d in reelspan.webhooks.deliveries()["deliveries"]:
    if d["status"] == "failed":
        reelspan.webhooks.redeliver(d["id"])
```

```json
{
  "success": true,
  "deliveries": [
    {
      "id": "dlv_Wm4Kq8Zt1Rb6Yn3Px9Cv",
      "event": "upload_completed",
      "status": "failed",
      "attempts": 8,
      "last_status_code": 500,
      "last_error": "HTTP 500",
      "created_at": "2026-11-29T09:00:41.512Z",
      "delivered_at": null
    }
  ]
}
```

`status` is `pending` (still being tried), `succeeded` or `failed` (every attempt failed).

### Redeliver

`POST /v1/webhook/deliveries/{id}/redeliver` sends a delivery again as a fresh series of attempts, with the same payload and delivery id. Test events and redeliveries together are limited to 10 a minute and 100 an hour per workspace; past that the answer is **429** `RATE_LIMITED`.

## Rotate the secret

`POST /v1/webhook/secret` gives the account webhook a new signing secret and returns it as `webhook_secret`. The old one stops working at once, so deploy the new secret to your receiver straight after. Without an account webhook the answer is **404**.

```javascript title="Node.js"
const { webhook_secret } = await reelspan.webhooks.rotateSecret();
```

```python title="Python"
webhook_secret = reelspan.webhooks.rotate_secret()["webhook_secret"]
```

Source: https://docs.reelspan.com/webhooks

---

# Authentication

> Create a Reelspan API key, send it as a Bearer token, limit it to scopes and profiles, set it to expire, and use test keys that never publish.

Every request to the Reelspan API carries an API key in the `Authorization` header. A key belongs to one workspace. You can limit what it may do (scopes), which profiles it may use, and when it stops working.

```bash title="cURL"
curl https://api.reelspan.com/v1/me \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan(); // reads REELSPAN_API_KEY
const me = await reelspan.me();
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()  # reads REELSPAN_API_KEY
me = reelspan.me()
```

`GET /v1/me` is the quickest way to check a key: it answers 200 with your plan and usage, or 401. See [Current account](/api/me).

## Create a key

Keys are created in the dashboard, under **Developers → API keys**. Only workspace owners and admins can create, rename or revoke them.

When you create a key you choose:

- **Name**: so you can tell your keys apart, for example `n8n uploader`.
- **Test key**: tick it for a `rs_test_` key that never publishes (see [Test keys](#test-keys)).
- **Access**: everything, or only some [scopes](#scopes).
- **Profiles**: all profiles, or only some (shown when the workspace has more than one profile).
- **Expires**: never, in 30 days, in 90 days, or in a year.

A live key starts with `rs_live_`, a test key with `rs_test_`. The full key is shown once, when you create it. Reelspan stores only a SHA-256 hash of it, so a lost key can't be shown again: create a new one and revoke the old one.

The API keys page lists each key with its first characters, its scopes, when it was last used, how many posts it sent in the last 30 days, and when it expires.

## Send the key

Put the key in the `Authorization` header with the `Bearer` scheme. The word `Bearer` is not case-sensitive.

```http
Authorization: Bearer rs_live_…
```

The `Apikey` scheme works too, so code written for Upload-Post keeps working with only a new key:

```http
Authorization: Apikey rs_live_…
```

Those are the only accepted forms. A key in a query string, in another header, or with any other scheme answers 401.

The SDKs read the key from the `REELSPAN_API_KEY` environment variable, or you pass it in:

```javascript title="Node.js"
const reelspan = new Reelspan({ apiKey: process.env.REELSPAN_API_KEY });
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan(api_key=os.environ["REELSPAN_API_KEY"])
```

## Use api.reelspan.com

API keys work only on the API host: `https://api.reelspan.com/v1`. The dashboard's address (`app.reelspan.com`) refuses them with **421** and `error_code: USE_API_HOST`, and the answer names the right address in `api_url`.

## Scopes

A key can do only what its scopes allow. A key created with **Everything** has no scope list and can do it all. A call outside a key's scopes answers **403** with `error_code: INSUFFICIENT_SCOPE`.

| Scope | Allows |
| --- | --- |
| `publish` | Posting, uploading media, editing and cancelling scheduled posts, retrying, unpublishing, editing and reposting live posts, setting YouTube thumbnails, adding to and removing from the media library, creating and deleting approval links, creating Pinterest boards and board sections, saving Pins, AI captions |
| `read` | Post status, history, scheduled posts and their thumbnails and previews, reading queue settings and slots, listing profiles, the media library list and its files, approval links, network lookups (Facebook Pages and Page details, Google Business locations, LinkedIn pages, Pinterest boards and sections, TikTok creator info, Reddit posts), publishing limits |
| `profiles` | Creating, renaming and deleting profiles, connecting and disconnecting accounts, connect links, choosing the Facebook Page or Google Business location posts go to, changing queue settings and marking slots full, changing workspace preferences |
| `analytics` | Account analytics and their history, total impressions, post analytics, best times and reports |
| `webhooks` | Managing the workspace and profile webhooks and their deliveries |

When you untick **Everything** in the dashboard, every scope except `webhooks` starts ticked. `GET /v1/me` and `GET /v1/preferences` work with any key, whatever its scopes.

## Keys limited to profiles

Give a key only some profiles, for example one key per client. Then:

- A call that names another profile answers **403** with `error_code: PROFILE_FORBIDDEN`.
- Posts, scheduled jobs and requests of other profiles answer **404**, as if they didn't exist.
- `GET /v1/profiles` lists only the key's profiles.
- The workspace-wide webhook needs a key without a profile limit; per-profile webhooks work.

## Test keys

A test key (`rs_test_…`) runs every check a live key does, and its posts show as done, but nothing reaches the networks and nothing counts against your plan's monthly uploads. A workspace can send up to 500 test posts a day; past that the answer is **429** with `error_code: TEST_LIMIT`.

Only posting is simulated. Other calls made with a test key act on your real workspace: creating or deleting profiles, connecting accounts, the media library, and AI captions (which use your AI credits). See [Test mode](/guides/test-mode).

## Expiry and revoking

A key with an expiry date stops working at that moment and answers **401** `API key expired`. The dashboard shows which keys expire within 14 days.

Revoking a key in the dashboard takes effect on the next request. To rotate a key without downtime:

1. Create the new key.
2. Deploy it everywhere the old one is used.
3. Revoke the old key.

## When authentication fails

| Status | Message or `error_code` | What it means |
| --- | --- | --- |
| 401 | `Authorization header required` | No `Authorization` header was sent. |
| 401 | `Invalid API key` | The key is wrong, malformed or revoked. |
| 401 | `API key expired` | The key's expiry date has passed. |
| 403 | `INSUFFICIENT_SCOPE` | The key lacks the scope this call needs. |
| 403 | `PROFILE_FORBIDDEN` | The key is limited to other profiles. |
| 403 | `WORKSPACE_SUSPENDED` | The workspace is suspended; contact support. |
| 421 | `USE_API_HOST` | The key was sent to the dashboard's address instead of `api.reelspan.com`. |
| 429 | `AUTH_RATE_LIMITED` | 10 failed attempts from one IP address within 5 minutes. Wait for `Retry-After` (300 seconds). |

Error bodies look like this:

```json
{ "success": false, "message": "This API key does not have the \"webhooks\" scope", "error_code": "INSUFFICIENT_SCOPE" }
```

Every answer to a valid key also carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. See [Rate limits](/rate-limits).

## Keep keys safe

- Keep keys on your server. Never put one in a web page, a mobile app or a public repository.
- Store keys in environment variables or a secrets manager, not in code.
- Give each integration its own key with only the scopes it needs, so you can revoke one without breaking the others.
- Limit keys to the profiles they serve, and set an expiry on keys for short-lived work.
- Use a test key while you build, and a live key only in production.
- If a key may have leaked, revoke it at once and create a new one.

## AI agents

The [MCP server](/integrations/mcp) accepts the same API key. Claude and ChatGPT can also sign in to it with OAuth instead of a key.

Source: https://docs.reelspan.com/authentication

---

# Current account

> Check that an API key works and read the workspace's plan, plus how many uploads it has used this month against the plan's limit.

Call `GET /v1/me` to check a key before you do anything else: a valid key answers 200 with the plan and this month's usage, a bad one answers 401. It works with any key, whatever its [scopes](/authentication#scopes).

```bash title="cURL"
curl https://api.reelspan.com/v1/me \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const me = await reelspan.me();
console.log(me.plan, me.api_usage);
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
me = reelspan.me()
print(me["plan"], me["api_usage"])
```

## The response

```json
{
  "success": true,
  "message": "Token is valid",
  "email": "you@example.com",
  "plan": "free",
  "preferences": { "weekStartDay": 1, "timezone": "Europe/London" },
  "api_usage": { "count": 4, "limit": 15, "last_reset": "2026-11-01T00:00:00.000Z" }
}
```

- `email`: the email of the person who created the key. For a key with no creator, the workspace's first member.
- `plan`: the workspace's plan id: `free`, `starter`, `pro`, `agency` or `scale`.
- `preferences`: the workspace's [preferences](/api/preferences). `weekStartDay` is `1` when weeks start on Monday (the default) or `0` for Sunday. `timezone` is the zone a post's `scheduled_date` is read in when the post sends no `timezone`, or `null` for UTC.
- `api_usage.count`: uploads used this month. Each network a post goes to counts as one upload, so one video sent to TikTok, YouTube and Instagram counts 3. Test-key posts don't count.
- `api_usage.limit`: the plan's monthly uploads, or `null` when the plan has no limit. Only the Free plan has one (15 a month).
- `api_usage.last_reset`: when the current period began. Usage resets on the first day of each month, at midnight UTC.

When a post would go over the limit, the post request answers **429** and nothing is published. See [Plans and limits](/limits/plans).

## Errors

A missing, wrong, revoked or expired key answers **401**:

```json
{ "success": false, "message": "API key expired" }
```

The messages are listed under [When authentication fails](/authentication#when-authentication-fails).

Source: https://docs.reelspan.com/api/me

---

# Preferences

> Read and change the workspace preferences - the day weeks start on, and the default time zone a post's scheduled_date is read in.

Preferences are settings for the whole workspace. There are two:

| Preference | Values | What it does |
| --- | --- | --- |
| `weekStartDay` | `1` Monday (the default), `0` Sunday | The first day of the week in calendars. |
| `timezone` | an IANA zone such as `Europe/London`, or `null` (the default, UTC) | The zone a post's `scheduled_date` is read in when the post sends no `timezone`. |

## Read them

```bash title="cURL"
curl https://api.reelspan.com/v1/preferences \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { preferences } = await reelspan.request('GET', '/v1/preferences');
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
preferences = reelspan.request("GET", "/v1/preferences")["preferences"]
```

```json
{ "success": true, "preferences": { "weekStartDay": 1, "timezone": null } }
```

Any key can read them, whatever its scopes. [`GET /v1/me`](/api/me) returns the same `preferences`.

## Change them

Send only what changes. The answer has all the preferences as saved:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/preferences \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timezone": "America/New_York"}'
```

```javascript title="Node.js"
await reelspan.request('POST', '/v1/preferences', { json: { timezone: 'America/New_York' } });
```

```python title="Python"
reelspan.request("POST", "/v1/preferences", json_body={"timezone": "America/New_York"})
```

```json
{ "success": true, "preferences": { "weekStartDay": 1, "timezone": "America/New_York" } }
```

Send `"timezone": null` to go back to UTC. An unknown zone gets **400** `INVALID_REQUEST`, and a `weekStartDay` other than `0` or `1` gets **400**. Changing preferences needs a key with the `profiles` scope.

## The default time zone

With a `timezone` preference, a post that sends `scheduled_date` without its own `timezone` is scheduled in the workspace's zone. With the preference above, this post goes out at 9:00 in New York:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "title=Launch day" \
  -F "scheduled_date=2026-12-01T09:00:00" \
  -F "video=@launch.mp4"
```

- A `timezone` sent with the post always wins.
- A `scheduled_date` with its own offset (`2026-12-01T09:00:00-05:00` or `…Z`) is that exact moment, whatever the zones say.
- Only new posts use the preference. Rescheduling a post with [`PATCH /v1/scheduled/{job_id}`](/api/scheduled-posts#reschedule-or-edit) keeps the zone it was scheduled in, and a [retry later](/api/retry#retry-later) without `timezone` uses UTC.

See [Scheduling and repeats](/guides/scheduling) for the rest of scheduling.

Source: https://docs.reelspan.com/api/preferences

---

# Profiles

> Create, list, rename and delete profiles. A profile is the brand or client you post as, with one connected account per network.

A profile is the brand or client you post as. It holds at most one connected account per network: one TikTok, one YouTube channel, one Instagram account, and so on. When you post, you name the profile in `user`, and Reelspan publishes through that profile's accounts.

Use one profile per brand or per client. An agency with ten clients makes ten profiles, and connects each client's accounts to their own profile.

## Create a profile

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/profiles \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-brand", "display_name": "My Brand"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { profile } = await reelspan.profiles.create('my-brand', 'My Brand');
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
profile = reelspan.profiles.create("my-brand", "My Brand")["profile"]
```

The answer is **201** with the new profile. It has no accounts yet: connect them next, see [Connecting accounts](/connecting-accounts).

- `username` is the profile's id in every call. Use 1 to 64 letters, digits, `_`, `@` or `-`. It must be unique in your workspace and can't be changed later.
- `display_name` is optional, up to 100 characters. It is how the profile shows in the dashboard.

| Error | When |
| --- | --- |
| 400 `INVALID_USERNAME` | The username has other characters or is longer than 64. |
| 400 `INVALID_DISPLAY_NAME` | The display name is over 100 characters or has control characters. |
| 403 `PROFILE_LIMIT_REACHED` | The workspace already has as many profiles as its plan allows. |
| 409 `PROFILE_EXISTS` | Another profile in the workspace has this username. |

## How many profiles

| Plan | Profiles |
| --- | --- |
| Free | 1 |
| Starter | 5 |
| Pro | 25 |
| Agency | 75 |
| Scale | 225 |

`GET /v1/profiles` returns your plan's limit as `limit`, next to `plan`.

## List profiles

```bash title="cURL"
curl https://api.reelspan.com/v1/profiles \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const { profiles, limit, plan } = await reelspan.profiles.list();
```

```python title="Python"
result = reelspan.profiles.list()
profiles = result["profiles"]
```

Profiles come oldest first. A key [limited to some profiles](/authentication#keys-limited-to-profiles) sees only those.

## Read one profile

```bash title="cURL"
curl https://api.reelspan.com/v1/profiles/my-brand \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const { profile } = await reelspan.profiles.get('my-brand');
```

```python title="Python"
profile = reelspan.profiles.get("my-brand")["profile"]
```

```json
{
  "success": true,
  "profile": {
    "username": "my-brand",
    "display_name": "My Brand",
    "created_at": "2026-11-02T09:14:03.120Z",
    "social_accounts": {
      "youtube": {
        "username": "UCx4b2…",
        "handle": "@mybrand",
        "display_name": "My Brand",
        "social_images": "https://yt3.ggpht.com/…",
        "reauth_required": false,
        "capabilities": ["video", "schedule", "thumbnail", "playlist"]
      },
      "tiktok": "",
      "instagram": "",
      "x": ""
    }
  }
}
```

`social_accounts` has one entry for every network (shortened above). A network with no account connected is an empty string `""`. A connected one is an object:

- `username`: the account's id on the network.
- `handle` and `display_name`: how the account is named there.
- `social_images`: its avatar, when the network gives one.
- `reauth_required`: `true` when the network signed Reelspan out and the account must be connected again before it can post. See [Reconnecting](/connecting-accounts#reconnecting).
- `capabilities`: what the connection can do on that network, for example `video`, `reels`, `stories` or `thumbnail`.

## Rename a profile

Only the display name can change. Send `null` to clear it.

```bash title="cURL"
curl -X PATCH https://api.reelspan.com/v1/profiles/my-brand \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "My Brand (EU)"}'
```

```javascript title="Node.js"
await reelspan.profiles.rename('my-brand', 'My Brand (EU)');
```

```python title="Python"
reelspan.profiles.rename("my-brand", "My Brand (EU)")
```

## Delete a profile

```bash title="cURL"
curl -X DELETE https://api.reelspan.com/v1/profiles \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-brand"}'
```

```javascript title="Node.js"
await reelspan.profiles.delete('my-brand');
```

```python title="Python"
reelspan.profiles.delete("my-brand")
```

> [!WARNING]
> Deleting a profile can't be undone. Its connected accounts are disconnected, and its post history and scheduled posts are deleted with it. The posts already live on the networks stay there.

To remove just one network from a profile, disconnect it instead: see [Connecting accounts](/connecting-accounts#disconnecting).

## Scopes

Listing and reading profiles needs the `read` scope. Creating, renaming and deleting them needs `profiles`. See [Scopes](/authentication#scopes).

Source: https://docs.reelspan.com/api/profiles

---

# Connecting accounts

> Connect social accounts to a profile from the dashboard, through a white-label link for your clients, or through the API, and reconnect or disconnect them.

Before Reelspan can post to a network, the profile needs an account connected there. Each profile holds one account per network. There are three ways to connect one:

| Way | Who does it | Best for |
| --- | --- | --- |
| [The dashboard](#in-the-dashboard) | You, signed in to Reelspan | Your own brands |
| [A white-label connect link](#with-a-connect-link) | Your client, without a Reelspan login | Agencies and apps whose customers own the accounts |
| [The API](#through-the-api) | Your code | Building connecting into your own product |

All three save the same kind of connection: once an account is connected, it doesn't matter how.

## How each network connects

Ten networks connect with an **OAuth sign-in**: the account owner signs in on the network and allows Reelspan to post. The other twelve connect with **credentials** the owner makes on the network: a bot token, a webhook, an access token or an app password. Reelspan checks credentials with the network before saving them, and stores them encrypted.

| Network | `platform` | Connects with | What you need |
| --- | --- | --- | --- |
| YouTube | `youtube` | OAuth | A Google account with a YouTube channel |
| TikTok | `tiktok` | OAuth | A TikTok account |
| Instagram | `instagram` | OAuth (Facebook sign-in) | An Instagram Business or Creator account linked to a Facebook Page |
| Facebook | `facebook` | OAuth | A Facebook Page you manage |
| X | `x` | OAuth | An X account |
| Threads | `threads` | OAuth | A Threads account |
| LinkedIn | `linkedin` | OAuth | A LinkedIn account (company pages you admin are listed too) |
| Pinterest | `pinterest` | OAuth | A Pinterest account |
| Reddit | `reddit` | OAuth | A Reddit account |
| Google Business | `google_business` | OAuth | A Google account that manages a Business Profile |
| Bluesky | `bluesky` | Credentials | Your handle and an app password |
| Telegram | `telegram` | Credentials | A bot token, and the channel or group the bot is an admin of |
| Discord | `discord` | Credentials | A channel webhook URL |
| Slack | `slack` | Credentials | An incoming webhook URL, or a bot token and a channel |
| Mastodon | `mastodon` | Credentials | Your server and an access token |
| WordPress | `wordpress` | Credentials | Your site, username and an application password |
| Dev.to | `devto` | Credentials | An API key |
| Hashnode | `hashnode` | Credentials | A personal access token (and the blog, if you have several) |
| Lemmy | `lemmy` | Credentials | Your server, the community, and the account's username and password |
| Listmonk | `listmonk` | Credentials | Your Listmonk address, an API user and token, and the list |
| Whop | `whop` | Credentials | A company API key, and the forum (or the company id) |
| Nostr | `nostr` | Credentials | Your private key (`nsec1…`), and optionally relays |

The exact fields for each credentials network, with the names the API accepts, are on [Connect with credentials](/api/connect-credentials).

## In the dashboard

1. Open **Accounts** and pick the profile.
2. Click **Connect** next to the network.
3. For an OAuth network, sign in on the network and allow access. You come back to the Accounts page.
4. For a credentials network, a form shows the setup steps for that network and the fields to fill in.

Only workspace owners and admins can connect accounts.

**Facebook:** if you manage several Pages, the dashboard asks which Page to post to after you connect. You can change it later on the account's page, or choose per post with `facebook_page_id`.

## With a connect link

Send your client a link to a hosted page where they connect their own accounts to one of your profiles. They don't need a Reelspan account and never see your API key.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/connect-links \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-brand", "platforms": ["tiktok", "instagram", "youtube"]}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { access_url } = await reelspan.connect.link('my-brand', { platforms: ['tiktok', 'instagram', 'youtube'] });
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
access_url = reelspan.connect.link("my-brand", platforms=["tiktok", "instagram", "youtube"])["access_url"]
```

The link works for 48 hours. On the page, OAuth networks have a **Connect** button and credentials networks have a short form. Your logo, texts, theme and language are set on the same call; see [White-label connect](/white-label).

## Through the API

### OAuth networks

Start the sign-in with `POST /v1/oauth/{platform}/start`, send the person to the `authorize_url` it returns, and they come back to your `redirect_url` with the outcome in the query string.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/oauth/tiktok/start \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile": "my-brand", "redirect_url": "https://example.com/connected"}'
```

```javascript title="Node.js"
const { authorize_url } = await reelspan.connect.oauthStart('tiktok', { profile: 'my-brand', redirectUrl: 'https://example.com/connected' });
```

```python title="Python"
authorize_url = reelspan.connect.oauth_start("tiktok", profile="my-brand", redirect_url="https://example.com/connected")["authorize_url"]
```

The `authorize_url` is good for 15 minutes and works once. When the person returns, `connect_status` is `success`, `cancelled` or `error`. The whole flow, including starting it with a connect link's token from your client's browser, is on [White-label connect](/white-label#your-own-connect-page).

### Credentials networks

Send the fields to `POST /v1/accounts/{platform}`. Reelspan checks them with the network and answers with the connected account.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/discord \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "webhook_url": "https://discord.com/api/webhooks/123/abc"}'
```

```javascript title="Node.js"
await reelspan.accounts.connect('my-brand', 'discord', { webhook_url: 'https://discord.com/api/webhooks/123/abc' });
```

```python title="Python"
reelspan.accounts.connect("my-brand", "discord", webhook_url="https://discord.com/api/webhooks/123/abc")
```

Every network's fields are on [Connect with credentials](/api/connect-credentials).

## See what is connected

`GET /v1/profiles/{username}` lists every network in `social_accounts`: `""` when nothing is connected, or the account's details. See [Profiles](/api/profiles#read-one-profile).

## Reconnecting

Networks sometimes sign Reelspan out: the person changed their password, removed the app's access, or a token couldn't be renewed. Reelspan notices when a post fails for that reason, and then:

- the account shows `reauth_required: true` in `social_accounts`;
- posts to that network are skipped with `error_code: reauth_required` until it is fixed, while the other networks still post;
- the `social_account_reauth_required` [webhook](/webhooks) fires, and the workspace gets a dashboard notification and an email.

To fix it, connect the same network again on the same profile, in any of the three ways. Connecting again replaces the old connection on that profile and makes it active; posts that were skipped can then be sent with [Retry](/api/retry). For Facebook, the Page you had chosen is kept if it is still shared.

Connecting a different account on a network that already has one also replaces it: a profile never has two accounts on one network.

## Disconnecting

```bash title="cURL"
curl -X DELETE https://api.reelspan.com/v1/accounts \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "social_platform": "tiktok"}'
```

```javascript title="Node.js"
await reelspan.accounts.disconnect('my-brand', 'tiktok');
```

```python title="Python"
reelspan.accounts.disconnect("my-brand", "tiktok")
```

Disconnecting deletes the stored tokens or credentials and fires the `social_account_disconnected` webhook. It is safe to repeat: disconnecting a network that isn't connected also answers 200. Your client can also disconnect from a connect link's page, unless the link is read-only.

> [!NOTE]
> Disconnecting removes Reelspan's copy of the access. To revoke it on the network's side too, remove Reelspan from the account's connected apps in that network's settings.

## Scopes

Connecting and disconnecting through the API, and creating connect links, need a key with the `profiles` scope. See [Authentication](/authentication#scopes).

## Features waiting for a network's approval

Some features use a permission a network grants only after it reviews Reelspan's app. They are built and in the API now. Until the network approves, they answer `403` with `error_code: "permission_pending"`. Once approved, Reelspan switches the permission on: new connections ask for it, and accounts connected before then must reconnect once (the call answers `409 permission_reconnect` until they do). [`GET /v1/permissions`](/api/permissions) lists each one with `status: "pending"` or `"live"`.

| Feature | Network | Permission | Approval |
| --- | --- | --- | --- |
| Edit and delete published videos ([edit](/api/edit-post), [unpublish](/api/unpublish-post)), subtitles on upload (`youtube_subtitle_*`), first comments | YouTube | `youtube.force-ssl` | Google OAuth verification |
| Delete posts ([unpublish](/api/unpublish-post)) | Threads | `threads_delete` | Meta App Review |
| Change a Page's about, website, phone, emails and hours (`PATCH /v1/facebook/page-info`) | Facebook | `pages_manage_metadata` | Meta App Review |
| First comments | Facebook | `pages_manage_engagement`, `pages_read_user_content` | Meta App Review |
| First comments | Instagram | `instagram_manage_comments` | Meta App Review |
| Company pages: list, choose and post or reshare as one (`/v1/linkedin/pages`, `target_linkedin_page_id`) | LinkedIn | `r_organization_admin`, `w_organization_social`, `r_organization_social` | LinkedIn Community Management API |
| Every post of the account in [`GET /v1/reddit/posts`](/api/reddit-posts), not only those made through Reelspan | Reddit | `history` | None (granted on consent) |

These need API access that the networks haven't opened to Reelspan's apps yet. They aren't in the API until that access exists:

- **TikTok:** music (trending, search, `tiktok_music_*`), locations (`tiktok_location_*`), `tiktok_is_ads_only` and `tiktok_tto_invite_link`, comments and audience insights. TikTok's public Content Posting API has none of them.
- **Comments, direct messages and auto-replies** on Instagram, Facebook, Threads, YouTube, TikTok and LinkedIn: each needs its network's comment or messaging permission.

A few Upload-Post fields have no counterpart in the networks' public APIs, so Reelspan doesn't offer them: YouTube `allowedCountries` and `blockedCountries` (read-only in the YouTube API), X Articles, and `pinterest_ai_disclosures`.

Source: https://docs.reelspan.com/connecting-accounts

---

# Connect with credentials

> Connect Bluesky, Telegram, Discord, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Listmonk, Whop or Nostr to a profile with a token, key or webhook.

Twelve networks connect with credentials the account owner makes on the network, instead of an OAuth sign-in. Send them to `POST /v1/accounts/{platform}` with the profile in `profile_username`. Reelspan checks them with the network first, saves them encrypted, and answers with the account it connected.

For the other ten networks, use the OAuth sign-in instead: see [Connecting accounts](/connecting-accounts#oauth-networks).

## Examples

### Telegram

Create a bot with @BotFather, add it to your channel as an admin that can post, then send its token and the channel. A public channel is its `@name`; a private one is its numeric id, which starts with `-100`.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/telegram \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "bot_token": "123456789:AAH…", "chat": "@mybrandchannel"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.accounts.connect('my-brand', 'telegram', { bot_token: process.env.TELEGRAM_BOT_TOKEN, chat: '@mybrandchannel' });
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.accounts.connect("my-brand", "telegram", bot_token=os.environ["TELEGRAM_BOT_TOKEN"], chat="@mybrandchannel")
```

### Bluesky

Use an app password (Bluesky: Settings → Privacy and security → App passwords), never your main password.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/bluesky \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "identifier": "mybrand.bsky.social", "app_password": "abcd-efgh-ijkl-mnop"}'
```

```javascript title="Node.js"
await reelspan.accounts.connect('my-brand', 'bluesky', { identifier: 'mybrand.bsky.social', app_password: process.env.BLUESKY_APP_PASSWORD });
```

```python title="Python"
reelspan.accounts.connect("my-brand", "bluesky", identifier="mybrand.bsky.social", app_password=os.environ["BLUESKY_APP_PASSWORD"])
```

### WordPress

In your WordPress admin, open Users → Profile → Application Passwords (WordPress 5.6 or later, on https) and create one for Reelspan.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/wordpress \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "site": "blog.example.com", "username": "editor", "app_password": "abcd efgh ijkl mnop qrst uvwx"}'
```

```javascript title="Node.js"
await reelspan.accounts.connect('my-brand', 'wordpress', { site: 'blog.example.com', username: 'editor', app_password: process.env.WP_APP_PASSWORD });
```

```python title="Python"
reelspan.accounts.connect("my-brand", "wordpress", site="blog.example.com", username="editor", app_password=os.environ["WP_APP_PASSWORD"])
```

## The response

```json
{ "success": true, "platform": "telegram", "account": "@mybrandchannel", "reconnected": false }
```

`account` is how the connected account is named. `reconnected` is `true` when the profile already had an account on this network: the new credentials replace it.

## Fields per network

Each field also accepts the name in the **Also accepted** column, so calls written for Upload-Post work unchanged. When both are sent, the Reelspan name wins.

| Network | Field | Also accepted | Required | What it is |
| --- | --- | --- | --- | --- |
| `bluesky` | `identifier` | `handle` | Yes | Your handle (like `mybrand.bsky.social`) or account email |
| | `app_password` | `password` | Yes | An app password, not your main password |
| `telegram` | `bot_token` | | Yes | The token @BotFather gave you, like `123456789:AAH…` |
| | `chat` | `chat_id` | Yes | `@name` of a public channel, or the numeric id of a private channel or group |
| `discord` | `webhook_url` | | Yes | The channel's webhook: channel settings → Integrations → Webhooks |
| `slack` | `webhook_url` | | One way | An incoming webhook URL (`https://hooks.slack.com/services/…`) |
| | `name` | | No | How the channel shows in Reelspan, with a webhook |
| | `bot_token` | | Other way | A bot token (`xoxb-…`) with `chat:write`, `files:write`, `channels:read` and `channels:join` |
| | `channel` | | With `bot_token` | The channel's name or id (`C…`) |
| `mastodon` | `server` | `instance_url` | Yes | Your server, like `mastodon.social` |
| | `access_token` | | Yes | From Preferences → Development → New application, with `read` and `write` |
| `wordpress` | `site` | `site_url` | Yes | Your site's address |
| | `username` | | Yes | Your WordPress username |
| | `app_password` | `application_password` | Yes | An application password, not your login password |
| `devto` | `api_key` | | Yes | From Settings → Extensions → DEV Community API Keys |
| `hashnode` | `token` | `pat` | Yes | A personal access token from Account settings → Developer |
| | `blog` | `publication_id` | No | The blog's address or publication id; needed only with more than one blog |
| `lemmy` | `server` | `instance_url` | Yes | Your server, like `lemmy.world` |
| | `community` | | Yes | The community name, or `name@server` for one on another server |
| | `username` | | Yes | An account that may post in the community |
| | `password` | | Yes | Used once to get a token; it isn't kept |
| `listmonk` | `server` | `instance_url` | Yes | Your Listmonk address |
| | `user` | `username` | Yes | An API user (Listmonk 4+), or the admin username |
| | `token` | `password` | Yes | The API user's token, or the admin password |
| | `list` | `list_id` | Yes | The list's name or id |
| `whop` | `api_key` | | Yes | A company API key with `forum:read`, `forum:post:create` and file permissions |
| | `forum` | `experience_id` | One of these | The forum's experience id (`exp_…`) |
| | `company_id` | | One of these | The company id (`biz_…`), to post to its public forum |
| `nostr` | `nsec` | `private_key` | Yes | Your private key, `nsec1…` (or 64 hex characters) |
| | `relays` | | No | `wss://` relays, as a list or separated by spaces |

Slack has two ways in. A webhook is quickest: messages and photos post into the channel, and a video or file goes as a link. A bot token uploads videos, photos and files into the channel itself; for a private channel, invite the bot first with `/invite @yourbot`.

Nostr without `relays` publishes to `relay.damus.io`, `nos.lol` and `relay.primal.net`. Media is hosted on nostr.build.

Values can be strings, numbers (a Telegram chat id, for example) or lists of strings; a list is joined with spaces.

## Errors

| Status | `error_code` | When |
| --- | --- | --- |
| 400 | `MISSING_FIELD` | A required field is missing. The message names it. |
| 400 | A code for the problem, such as `INVALID_TOKEN`, `INVALID_WEBHOOK` or `BOT_NOT_ADMIN` | The credentials are malformed or the network refused them. The message says what to fix. |
| 403 | `PLATFORM_DISABLED` | Connecting this network is switched off for now. |
| 403 | `PROFILE_FORBIDDEN` | The key is limited to other profiles. |
| 404 | `PROFILE_NOT_FOUND` | No profile has that username. |
| 429 | `RATE_LIMITED` | More than 30 connection attempts from your workspace in 10 minutes. |

Each attempt reaches the network, which is why attempts are capped. Calls need a key with the `profiles` scope.

## Disconnect

`DELETE /v1/accounts` removes one network from a profile, for credentials and OAuth networks alike. It deletes the stored credentials and fires the `social_account_disconnected` webhook. Disconnecting a network that isn't connected also answers 200.

```bash title="cURL"
curl -X DELETE https://api.reelspan.com/v1/accounts \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "social_platform": "telegram"}'
```

```javascript title="Node.js"
await reelspan.accounts.disconnect('my-brand', 'telegram');
```

```python title="Python"
reelspan.accounts.disconnect("my-brand", "telegram")
```

```json
{ "success": true, "message": "telegram disconnected" }
```

When nothing was connected, the message is `telegram was not connected`.

Source: https://docs.reelspan.com/api/connect-credentials

---

# White-label connect

> Let your clients connect their own social accounts to a profile through a branded hosted page, or through your own connect page built on the Connect API.

When your clients own the social accounts, they should connect them themselves: they sign in on each network, and you never handle their passwords. Reelspan gives you two ways to do that without a Reelspan login for them:

- **A hosted connect link**: one call returns a link to a page with your logo, texts and language. Send it to your client.
- **Your own connect page**: you build the page, and call the Connect API to start each network's sign-in.

## A hosted connect link

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/connect-links \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my-brand",
    "platforms": ["tiktok", "instagram", "youtube"],
    "logo_image": "https://example.com/logo.png",
    "connect_title": "Connect your accounts to Example Studio",
    "redirect_url": "https://example.com/onboarding/done",
    "redirect_button_text": "Back to Example Studio",
    "language": "es",
    "connect_theme": "dark"
  }'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { access_url } = await reelspan.connect.link('my-brand', {
  platforms: ['tiktok', 'instagram', 'youtube'],
  logo_image: 'https://example.com/logo.png',
  connect_title: 'Connect your accounts to Example Studio',
  redirect_url: 'https://example.com/onboarding/done',
  redirect_button_text: 'Back to Example Studio',
  language: 'es',
  connect_theme: 'dark',
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
access_url = reelspan.connect.link(
    "my-brand",
    platforms=["tiktok", "instagram", "youtube"],
    logo_image="https://example.com/logo.png",
    connect_title="Connect your accounts to Example Studio",
    redirect_url="https://example.com/onboarding/done",
    redirect_button_text="Back to Example Studio",
    language="es",
    connect_theme="dark",
)["access_url"]
```

```json
{ "success": true, "access_url": "https://app.reelspan.com/connect?token=eyJhbGciOiJIUzI1NiIs…", "duration": "48h" }
```

Send `access_url` to your client. It works for 48 hours; make a new one whenever you need it. Anyone with the link can connect accounts to that one profile, so send it only to the person it is for.

### What the page shows

- Your logo, title and description, or Reelspan's default texts.
- Each network you listed in `platforms` (every network when you leave it out). OAuth networks have a **Connect** button that opens the network's sign-in; Bluesky and the other credentials networks show a short form for the token or key.
- For each connected network: the account's name, a **Disconnect** button, and **Reconnect** when the account needs it.
- The profile's scheduled posts, unless you send `show_calendar: false`.
- A button back to your `redirect_url`, labelled with `redirect_button_text` (default "Done").

After each sign-in your client returns to the same page, which says whether the network connected, was cancelled, or failed and why.

### Branding options

| Field | What it does | Plans |
| --- | --- | --- |
| `username` | The profile the link connects accounts to. Required. | All |
| `platforms` | The networks to offer, by id (up to 20). Your client can't connect any other network with this link, here or through the Connect API. | All |
| `redirect_url` | Where the page's final button goes. An `http` or `https` address. | All |
| `show_calendar` | `false` hides the scheduled posts. | All |
| `readonly_calendar` | `true` makes a view-only link: your client sees the connections and scheduled posts, but can't connect or disconnect anything. | All |
| `language` | The page's language (see [Languages](#languages)). | All |
| `logo_image` | Your logo, as an `http` or `https` image URL. | White-label |
| `connect_title` | The heading, up to 120 characters. | White-label |
| `connect_description` | The text under it, up to 500 characters. | White-label |
| `redirect_button_text` | The final button's label, up to 60 characters. | White-label |
| `connect_theme` | `light`, `dark` or `auto` (the default). | White-label |
| `ui_labels` | Your own wording for any text on the page (see [Your own wording](#your-own-wording)). | White-label |

White-label is part of the Pro, Agency and Scale plans; those plans also drop the "Secure connection powered by Reelspan" line at the bottom of the page. On Free and Starter the link still works with Reelspan's look: the white-label fields are left out, and the answer says so in `warnings`.

```json
{
  "success": true,
  "access_url": "https://app.reelspan.com/connect?token=…",
  "duration": "48h",
  "warnings": ["Branding (logo_image, connect_title) needs a plan with white-label; the link uses Reelspan's default look."]
}
```

### Settings are remembered

Branding is saved on the profile, so the next link for that profile only needs `username`. Fields you send change only themselves; the rest stay as they were. Send `ui_labels: null` (or `{}`) to clear your labels.

`readonly_calendar` is fixed into each link when it is made: changing it later doesn't change links already sent.

### Languages

The hosted page comes in English (`en`), Spanish (`es`), German (`de`), French (`fr`), Portuguese (`pt`), Polish (`pl`) and Turkish (`tr`). Without `language`, it follows your client's browser language, and falls back to English.

### Your own wording

`ui_labels` replaces any text on the page, in any language. Send up to 100 labels, each up to 300 characters:

```json
{ "username": "my-brand", "ui_labels": { "connect.button": "Link account", "calendar.title": "Coming up" } }
```

| Key | Default text |
| --- | --- |
| `connect.title` | Connect your social accounts |
| `connect.description` | Connect the accounts you want us to publish to. You can disconnect them here at any time. |
| `connect.button` | Connect |
| `connect.reconnect` | Reconnect |
| `connect.disconnect` | Disconnect |
| `connect.connected` | Connected |
| `connect.success` | connected. |
| `connect.cancelled` | was not connected: permission was not granted. |
| `connect.error` | could not be connected |
| `connect.expired` | This link has expired or is not valid. Ask for a new one. |
| `connect.done` | Done |
| `connect.maintenance` | Under maintenance. It can't be connected right now; check back soon. |
| `calendar.title` | Scheduled posts |
| `calendar.empty` | Nothing is scheduled. |
| `bluesky.handle` | Bluesky handle |
| `bluesky.password` | App password (Settings → Privacy and security → App passwords). Never your main password. |
| `footer.powered` | Secure connection powered by Reelspan |

`connect_title` and `connect_description` take priority over the `connect.title` and `connect.description` labels.

### Embedding

The hosted page can be shown in an `<iframe>` on any https site, so your client can connect without leaving your app.

## Your own connect page

To keep your client on your own site from start to finish, build the page yourself and use the Connect API for the OAuth networks:

1. **Start**: call `POST /v1/oauth/{platform}/start`. The answer has an `authorize_url`.
2. **Send your client** to `authorize_url`. They sign in on the network and allow access.
3. **They come back** to your `redirect_url` with the outcome in the query string.

You can call it from your server with your API key and the profile:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/oauth/youtube/start \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile": "my-brand", "redirect_url": "https://example.com/connected"}'
```

```javascript title="Node.js"
const { authorize_url } = await reelspan.connect.oauthStart('youtube', { profile: 'my-brand', redirectUrl: 'https://example.com/connected' });
```

```python title="Python"
authorize_url = reelspan.connect.oauth_start("youtube", profile="my-brand", redirect_url="https://example.com/connected")["authorize_url"]
```

```json
{ "success": true, "platform": "youtube", "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth?…", "state": "q3J9…", "expires_in": 900 }
```

Or, from your client's browser, with a connect link's token instead of your key. Take the token from a link's `access_url` (the `token` parameter) and send it as the Bearer token, with no `profile`:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/oauth/youtube/start \
  -H "Authorization: Bearer $CONNECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"redirect_url": "https://example.com/connected"}'
```

A token can do only what its link allows: the link's `platforms`, nothing on a read-only link, and at most 20 sign-ins every 10 minutes. If the profile has a `redirect_url` saved, a token's `redirect_url` must be on the same site, or the saved one is used.

### The flow

- `authorize_url` works once, for 15 minutes (`expires_in: 900`).
- `platform` is the network's id: `youtube`, `tiktok`, `instagram`, `facebook`, `x` (or `twitter`), `threads`, `linkedin`, `pinterest`, `reddit` or `google_business` (or `google-business`).
- Always send `redirect_url`. Without one, your client ends on the Reelspan dashboard.

When your client comes back, read these query parameters:

| Parameter | Value |
| --- | --- |
| `connect_status` | `success`, `cancelled` (they declined on the network) or `error` |
| `platform` | The network |
| `error_code` | On `cancelled` and `error`: for example `ACCESS_DENIED`, `INVALID_STATE` (the link expired or was used), `PROVIDER_ERROR` or `CONNECTION_FAILED` |
| `error_description` | On `cancelled` and `error`: a readable reason |

```text
https://example.com/connected?connect_status=success&platform=youtube
```

Then confirm with `GET /v1/profiles/{username}`: the network's entry in `social_accounts` now has the account. Each connect and disconnect also fires the `social_account_connected` and `social_account_disconnected` [webhooks](/webhooks).

### Credentials networks on your page

Bluesky, Telegram, Discord and the other credentials networks have no sign-in to start: `POST /v1/oauth/{platform}/start` answers 400 `NOT_OAUTH` for them. Collect the fields on your page and send them from your server with [Connect with credentials](/api/connect-credentials), or send your client the hosted link for those.

### Check a token

`GET /v1/connect-links/validate`, with the connect token as the Bearer token, tells your page whether a link is still good and what the profile has connected:

```bash title="cURL"
curl https://api.reelspan.com/v1/connect-links/validate \
  -H "Authorization: Bearer $CONNECT_TOKEN"
```

```javascript title="Node.js"
const { profile } = await reelspan.connect.validate(connectToken);
```

```python title="Python"
profile = reelspan.connect.validate(connect_token)["profile"]
```

```json
{
  "success": true,
  "isValid": true,
  "profile": {
    "username": "my-brand",
    "social_accounts": {
      "youtube": "",
      "tiktok": { "username": "-000Abc…", "handle": "@mybrand", "display_name": "My Brand", "social_images": "https://…", "reauth_required": false, "capabilities": ["video", "draft", "video_privacy"] }
    },
    "ui_labels": {}
  }
}
```

An expired or altered token answers **401** with `isValid: false`.

## Errors

| Status | `error_code` | When |
| --- | --- | --- |
| 400 | `NOT_OAUTH` | The network connects with credentials, not a sign-in. |
| 400 | `UNSUPPORTED_PLATFORM` | No such OAuth network. |
| 400 | `PROVIDER_NOT_CONFIGURED` | The network can't be connected right now; the message says why. |
| 401 | | The API key or connect token is invalid or expired. |
| 403 | `ACCESS_DENIED` | The token's link doesn't offer this network, or is read-only. |
| 403 | `PROFILE_FORBIDDEN` | The API key is limited to other profiles. |
| 404 | `PROFILE_NOT_FOUND` | No profile has that username. |
| 429 | `RATE_LIMITED` | More than 20 sign-ins started with one link in 10 minutes. |

Creating links and starting sign-ins with an API key need the `profiles` scope.

Source: https://docs.reelspan.com/white-label

---

# Media library

> Keep uploaded videos, photos and PDFs in your media library, import them from Google Drive or Dropbox, and post them again by media_id.

The media library keeps files you want to post more than once: a brand intro, a product video, a set of photos. Files in the library are never deleted on their own. You post them by `media_id`, without uploading them again.

Files that are not in the library are temporary: an upload is deleted 7 days after the posts that use it finish, and an upload no post ever used is deleted after a day.

## Add files

There are three ways to put a file in the library:

- **Upload and keep it at once**: [Upload media](/api/upload-media) with `save=true` (and an optional `title`).
- **Keep something already uploaded**: `POST /v1/library` with its `media_ids`.
- **Import from a link**: `POST /v1/library/import` with a Google Drive or Dropbox share link, or any public https link.

```bash title="cURL"
curl -X POST "https://api.reelspan.com/v1/media/upload?kind=video&save=true&title=Brand%20intro" \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "file=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const { media_id } = await reelspan.media.upload(
  { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  { kind: 'video', save: true, title: 'Brand intro' },
);
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
media_id = reelspan.media.upload("launch.mp4", kind="video", save=True, title="Brand intro")["media_id"]
```

### Keep an earlier upload

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/library \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": ["med_4f2a…"], "title": "Brand intro"}'
```

```javascript title="Node.js"
await reelspan.library.keep(['med_4f2a…'], 'Brand intro');
```

```python title="Python"
reelspan.library.keep(["med_4f2a…"], title="Brand intro")
```

Send 1 to 50 `media_ids`. A file that is already in the library only gets the new `title`.

### Import from a link

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/library/import \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://drive.google.com/file/d/1AbC…/view?usp=sharing", "title": "Product demo"}'
```

```javascript title="Node.js"
const { item } = await reelspan.library.import('https://drive.google.com/file/d/1AbC…/view?usp=sharing', 'Product demo');
```

```python title="Python"
item = reelspan.library.import_url("https://drive.google.com/file/d/1AbC…/view?usp=sharing", title="Product demo")["item"]
```

The link must be `https`. A Google Drive or Dropbox file must be shared as "anyone with the link". Reelspan copies the file in, so the link can change or go away afterwards. It takes videos, photos and PDFs: a video or PDF up to your plan's upload size, a photo up to 20 MB, as long as the library has room.

## Post from the library

Use the `media_id` where a post takes an uploaded file:

- `video_media_id` on [Post a video](/api/post-video)
- `photo_media_ids[]` on [Post photos](/api/post-photos)
- `document_media_id` on [Post a document](/api/post-document)

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "platform[]=youtube" \
  -F "title=Meet the team" \
  -F "video_media_id=med_4f2a…"
```

```javascript title="Node.js"
await reelspan.posts.video({ user: 'my-brand', platforms: ['tiktok', 'youtube'], title: 'Meet the team', videoMediaId: 'med_4f2a…' });
```

```python title="Python"
reelspan.posts.video("my-brand", ["tiktok", "youtube"], title="Meet the team", video_media_id="med_4f2a…")
```

## List the library

```bash title="cURL"
curl "https://api.reelspan.com/v1/library?kind=video&limit=20" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const page = await reelspan.library.list({ kind: 'video', limit: 20 });
```

```python title="Python"
page = reelspan.library.list(kind="video", limit=20)
```

```json
{
  "success": true,
  "usage": { "used_bytes": 734003200, "limit_bytes": 26843545600, "items": 12 },
  "items": [
    {
      "media_id": "med_4f2a…",
      "kind": "video",
      "title": "Brand intro",
      "filename": "launch.mp4",
      "content_type": "video/mp4",
      "size_bytes": 48211022,
      "duration_seconds": 31.5,
      "width": 1080,
      "height": 1920,
      "saved_at": "2026-11-03T10:22:41.000Z",
      "url": "https://…"
    }
  ],
  "next_before": "2026-11-03T10:22:41.000Z"
}
```

- Newest first. `kind` is `video`, `photo` or `document`; leave it out for all.
- `limit` is 1 to 100 (default 48). When there are more, pass `next_before` as `before` to get the next page; it is `null` on the last page.
- Each item's `url` is a link to the file that works for an hour. For a fresh one later, call `GET /v1/library/{media_id}/file`, which redirects (302) to a new link.
- `duration_seconds`, `width` and `height` are `null` when they aren't known (always for PDFs).

## Remove a file

```bash title="cURL"
curl -X DELETE https://api.reelspan.com/v1/library/med_4f2a… \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
await reelspan.library.remove('med_4f2a…');
```

```python title="Python"
reelspan.library.remove("med_4f2a…")
```

Removing takes the file out of the library and frees its space. The file itself is deleted once no post waiting to go out uses it, so a scheduled post that uses it still publishes.

## Storage per plan

Files in the library count against your plan's library space. Temporary uploads don't.

| Plan | Library space |
| --- | --- |
| Free | 1 GB |
| Starter | 25 GB |
| Pro | 100 GB |
| Agency | 250 GB |
| Scale | 500 GB |

`usage` in each answer shows the bytes used, your plan's limit and the number of files. When a file doesn't fit, the answer is **413** with `error_code: LIBRARY_FULL` and says how much space is left. See [Plans and limits](/limits/plans).

## Errors

| Status | `error_code` | When |
| --- | --- | --- |
| 400 | varies | The import link couldn't be fetched or isn't a video, photo or PDF. The message says why. |
| 404 | `MEDIA_NOT_FOUND` | No upload or library file with that `media_id` in your workspace. |
| 413 | `LIBRARY_FULL` | Not enough library space left. |
| 413 | `FILE_TOO_LARGE` | The imported file is over the size limit, or bigger than the space left. |

Listing and downloading need the `read` scope; adding, importing and removing need `publish`.

Source: https://docs.reelspan.com/api/library

---

# Analytics

> Read follower counts and account totals per network, how they changed, their daily history, total impressions, and the likes and views of each post.

Reelspan reads numbers straight from each network: account totals such as followers, and per-post numbers such as likes and views. Five calls cover it:

- **Account totals now** (and how they changed): `GET /v1/analytics/{profile_username}`
- **Account totals per day**: `GET /v1/analytics/{profile_username}/history`
- **Impressions and views over a period**: `GET /v1/analytics/{profile_username}/impressions`
- **The numbers of a post Reelspan published**: `GET /v1/post-analytics/{request_id}`
- **The numbers of any post of the account**: `GET /v1/post-analytics?platform=…&platform_post_id=…`

Every network shares different numbers, and some share none. The [tables below](#what-each-network-shares) list them.

## Account totals

```bash title="cURL"
curl "https://api.reelspan.com/v1/analytics/my-brand?platforms=youtube,instagram,tiktok" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const stats = await reelspan.analytics.account('my-brand', ['youtube', 'instagram', 'tiktok']);
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
stats = reelspan.analytics.account("my-brand", ["youtube", "instagram", "tiktok"])
```

```json
{
  "success": true,
  "profile_username": "my-brand",
  "youtube": { "followers": 12840, "views": 1893220, "posts": 214 },
  "instagram": { "followers": 30412, "following": 180, "posts": 655 },
  "tiktok": { "error": "TikTok statistics are not available yet", "error_code": "not_supported" }
}
```

Each connected network is a key at the top level. Leave out `platforms` to get every connected network. A network that can't give numbers answers with `error` and `error_code` instead, and the others are unaffected:

| `error_code` | Meaning |
| --- | --- |
| `not_supported` | The network doesn't share account numbers through Reelspan. |
| `reauth_required` | The account must be [reconnected](/connecting-accounts#reconnecting) first. |
| `stats_reconnect` | The account was connected before Reelspan asked for permission to read its numbers. Connect it again to grant it. |

Answers are cached for 10 minutes per account, so calling more often returns the same numbers. Each reading also becomes that day's row in the history.

### How the numbers changed

Add `days` (1 to 365) and each network also gets `change`: how much each number moved over those days. It is the latest daily reading in the [history](#history) minus the last reading from at least `days` before it, and `null` for a number with no reading that old (an account connected recently, say). The answer also echoes `days`.

```bash title="cURL"
curl "https://api.reelspan.com/v1/analytics/my-brand?platforms=youtube&days=30"   -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const stats = await reelspan.request('GET', '/v1/analytics/my-brand', { query: { platforms: 'youtube', days: 30 } });
```

```python title="Python"
stats = reelspan.request("GET", "/v1/analytics/my-brand", query={"platforms": "youtube", "days": 30})
```

```json
{
  "success": true,
  "profile_username": "my-brand",
  "days": 30,
  "youtube": {
    "followers": 12840,
    "views": 1893220,
    "posts": 214,
    "change": { "followers": 412, "views": 96310, "posts": 9 }
  }
}
```

## History

One row per account per day (UTC), oldest first. Each row has the last reading of that day.

```bash title="cURL"
curl "https://api.reelspan.com/v1/analytics/my-brand/history?days=90&platforms=youtube" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const { history } = await reelspan.analytics.history('my-brand', { days: 90, platforms: ['youtube'] });
```

```python title="Python"
history = reelspan.analytics.history("my-brand", days=90, platforms=["youtube"])["history"]
```

```json
{
  "success": true,
  "profile_username": "my-brand",
  "days": 90,
  "history": [
    { "date": "2026-08-10", "platform": "youtube", "followers": 11920, "views": 1702114, "posts": 198 },
    { "date": "2026-08-11", "platform": "youtube", "followers": 11934, "views": 1704890, "posts": 198 }
  ]
}
```

- `days` is 1 to 365, 30 by default.
- Reelspan reads every connected account once a day, so the history fills in even if you never call the API. It starts on the day an account's numbers were first read: there is nothing from before it was connected.
- Add `format=csv` for a spreadsheet instead of JSON. The SDKs don't wrap that; request it directly.

```bash title="cURL"
curl -o my-brand.csv "https://api.reelspan.com/v1/analytics/my-brand/history?days=90&format=csv" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

## Total impressions

`GET /v1/analytics/{profile_username}/impressions` adds up impressions and views over the posts the profile published in a period, per network and per day.

```bash title="cURL"
curl "https://api.reelspan.com/v1/analytics/my-brand/impressions?days=30"   -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const totals = await reelspan.request('GET', '/v1/analytics/my-brand/impressions', { query: { days: 30 } });
```

```python title="Python"
totals = reelspan.request("GET", "/v1/analytics/my-brand/impressions", query={"days": 30})
```

```json
{
  "success": true,
  "profile_username": "my-brand",
  "from": "2026-10-08T10:00:00.000Z",
  "to": "2026-11-07T10:00:00.000Z",
  "posts": 18,
  "posts_with_stats": 15,
  "total": { "impressions": 48210, "views": 31544 },
  "by_platform": {
    "x": { "impressions": 48210, "views": 0, "posts": 6 },
    "youtube": { "impressions": 0, "views": 31544, "posts": 12 }
  },
  "by_day": [
    { "date": "2026-10-09", "impressions": 8120, "views": 2210 }
  ]
}
```

- **The period:** `days` (1 to 365, 30 by default), or `start_date` and `end_date` (`YYYY-MM-DD`, both or neither, `end_date` included, at most a year).
- **Filters:** `platforms` (comma-separated) and `metrics` (comma-separated post numbers to add up, `impressions,views` by default; any name from [Post numbers by network](#post-numbers-by-network) works, such as `likes,comments`).
- **Where the numbers come from:** the readings Reelspan keeps for each post it published, taken about two days after the post goes out. Posts from the last two days count in `posts` but not yet in `posts_with_stats`. Test posts are left out, and so are posts made outside Reelspan.
- `by_day` groups posts by the day they went out, not the day they were seen. A network that doesn't share a number adds `0` for it.

## Post numbers

Use the `request_id` you got when you posted. The answer has one entry per network the post went live on.

```bash title="cURL"
curl https://api.reelspan.com/v1/post-analytics/9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1 \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const { results } = await reelspan.analytics.post('9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1');
```

```python title="Python"
results = reelspan.analytics.post("9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1")["results"]
```

```json
{
  "success": true,
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "results": {
    "youtube": {
      "post_id": "aB3xYz12Q",
      "post_url": "https://youtube.com/shorts/aB3xYz12Q",
      "metrics": { "views": 4810, "likes": 312, "comments": 27, "favorites": 0 }
    },
    "tiktok": {
      "post_id": "7441…",
      "post_url": "https://www.tiktok.com/@mybrand/video/7441…",
      "metrics": { "error": "TikTok post statistics are not available", "error_code": "not_supported" }
    }
  }
}
```

- Add `platform=youtube` to read one network only.
- Only networks where the post went live are listed; failed ones aren't.
- Numbers are cached for 10 minutes per post.
- A `request_id` from another workspace, or of a profile your key can't use, answers **404**.

### Any post, by the network's id

For a post made outside Reelspan (or when you only have the network's id), send `platform`, `platform_post_id` and the profile in `user`:

```bash title="cURL"
curl "https://api.reelspan.com/v1/post-analytics?platform=youtube&platform_post_id=aB3xYz12Q&user=my-brand"   -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const stats = await reelspan.request('GET', '/v1/post-analytics', { query: { platform: 'youtube', platform_post_id: 'aB3xYz12Q', user: 'my-brand' } });
```

```python title="Python"
stats = reelspan.request("GET", "/v1/post-analytics", query={"platform": "youtube", "platform_post_id": "aB3xYz12Q", "user": "my-brand"})
```

```json
{ "success": true, "platform": "youtube", "platform_post_id": "aB3xYz12Q", "metrics": { "views": 4810, "likes": 312, "comments": 27, "favorites": 0 } }
```

The post must belong to the profile's connected account on that network. A network with no post numbers answers **400** `platform_not_supported`; a profile with no account on the network answers **404**. Numbers are cached for 10 minutes. If the account must be reconnected, `metrics` holds `error` and `error_code: "reauth_required"` instead.

## What each network shares

Numbers a network doesn't give are left out of the answer, not returned as `0`.

### Account numbers by network

| Network | Numbers |
| --- | --- |
| YouTube | `followers` (subscribers), `views`, `posts` |
| TikTok | `followers`, `following`, `likes`, `posts` |
| Instagram | `followers`, `following`, `posts` |
| Facebook | `followers`, `likes` (Page likes) |
| X | `followers`, `following`, `posts`, `likes` |
| Threads | `followers`, plus `views`, `likes`, `replies`, `reposts` and `quotes` over the last 30 days |
| LinkedIn | `followers` |
| Pinterest | `followers`, `following`, `posts`, `monthly_views` |
| Bluesky | `followers`, `following`, `posts` |
| Mastodon | `followers`, `following`, `posts` |

Reddit, Google Business, Telegram, Discord, Slack, WordPress, Dev.to, Hashnode, Lemmy, Listmonk, Whop and Nostr give no account totals.

TikTok, Threads and LinkedIn give their numbers only with an extra permission. Until Reelspan has it for your account, the answer is `not_supported` or `stats_reconnect`. Threads gives the follower count only to profiles with at least 100 followers.

### Post numbers by network

| Network | Numbers |
| --- | --- |
| YouTube | `views`, `likes`, `comments`, `favorites` |
| X | `impressions`, `likes`, `reposts`, `replies`, `quotes`, `saves` (bookmarks) |
| Instagram | `likes`, `comments` |
| Facebook | `likes`, `comments` |
| Threads | `views`, `likes`, `replies`, `reposts`, `quotes`, `shares` |
| Bluesky | `likes`, `reposts`, `replies`, `quotes` |
| Mastodon | `likes`, `reposts`, `replies` |
| Reddit | `likes` (upvotes), `comments`, `score` |
| Dev.to | `likes` (reactions), `comments`, `views` when Dev.to gives them |

TikTok, LinkedIn, Pinterest, Google Business and the remaining networks give no post numbers through Reelspan.

## Built on these numbers

- [Best times to post](/api/best-times) compares your posts' numbers by hour and weekday.
- [Reports](/api/reports) add up a period's posts, interactions and follower growth.

All these analytics calls need a key with the `analytics` scope.

Source: https://docs.reelspan.com/api/analytics

---

# Best times to post

> Find the hours and weekdays when a profile's posts do best on each network, worked out from your own published posts, in any time zone.

Best times are worked out from your own results, not from general advice. For each network, Reelspan compares how your posts did by the hour and weekday they went out, and returns the hours and days that beat your usual post.

```bash title="cURL"
curl "https://api.reelspan.com/v1/best-times/my-brand?timezone=Europe/Berlin&platforms=tiktok,instagram" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { best_times } = await reelspan.analytics.bestTimes('my-brand', { timezone: 'Europe/Berlin', platforms: ['tiktok', 'instagram'] });
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
best = reelspan.analytics.best_times("my-brand", timezone="Europe/Berlin", platforms=["tiktok", "instagram"])["best_times"]
```

## The response

```json
{
  "success": true,
  "profile_username": "my-brand",
  "timezone": "Europe/Berlin",
  "best_times": {
    "instagram": {
      "posts": 23,
      "needed": 0,
      "hours": [
        { "hour": 18, "lift": 1.64, "posts": 4 },
        { "hour": 12, "lift": 1.31, "posts": 3 }
      ],
      "days": [{ "day": 3, "lift": 1.42, "posts": 5 }]
    },
    "tiktok": { "posts": 5, "needed": 3, "hours": [], "days": [] }
  }
}
```

For each network:

- `posts`: how many of your posts with numbers were compared.
- `needed`: how many more posts the network needs before anything is suggested. A network needs 8.
- `hours`: up to 3 hours of the day (`0` to `23`), best first.
- `days`: up to 2 weekdays, best first. `0` is Monday and `6` is Sunday.
- `lift`: how posts at that time did against your usual post on the network. `1.64` means 64% better.

Only hours and days that did better than usual (a `lift` above 1) are listed, and only those with at least 2 posts. An empty list means nothing stood out yet.

## How it works

1. About two days after each post goes out, Reelspan reads its numbers once, so every post is compared at the same age.
2. Each post gets one score: likes, saves and favorites count once, comments and replies twice, reposts, shares and quotes three times, and every 100 views or impressions add one.
3. For each network, the posts of the last 120 days are grouped by hour and by weekday in your `timezone`, and each group is compared with the median post.

Posts made with a [test key](/guides/test-mode) aren't counted. Only networks that share post numbers can have best times; see [What each network shares](/api/analytics#post-numbers-by-network).

## Parameters

- `timezone`: an IANA time zone such as `America/New_York` or `Asia/Karachi`. Default `UTC`. An unknown zone answers **400**.
- `platforms`: comma-separated network ids. A network you name that has no posts yet is still listed, with `needed: 8`. Leave it out for every network the profile posted to.

## Use them

Feed the hours into your profile's posting queue so new posts take the best slots: see [Queue](/api/queue).

The call needs a key with the `analytics` scope.

Source: https://docs.reelspan.com/api/best-times

---

# Reports

> Get a profile's report for a period, with posts published and failed, interactions and views per network, follower growth, and the top five posts.

A report sums up how a profile did over a period: what went out, how it did, and how each account grew. It returns the same numbers the dashboard's branded PDF report shows, so you can build your own client reports.

```bash title="cURL"
curl "https://api.reelspan.com/v1/reports/my-brand?days=30" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { report } = await reelspan.analytics.report('my-brand', 30);
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
report = reelspan.analytics.report("my-brand", days=30)["report"]
```

`days` is 1 to 365, 30 by default. The period ends now.

## The response

```json
{
  "success": true,
  "profile_username": "my-brand",
  "report": {
    "from": "2026-10-08T12:00:00.000Z",
    "to": "2026-11-07T12:00:00.000Z",
    "posts": {
      "published": 41,
      "failed": 2,
      "by_platform": {
        "youtube": { "published": 14, "failed": 0 },
        "instagram": { "published": 14, "failed": 1 },
        "x": { "published": 13, "failed": 1 }
      }
    },
    "engagement": {
      "interactions": 4970,
      "views": 182340,
      "by_platform": {
        "youtube": { "views": 150210, "likes": 3302, "comments": 214, "favorites": 0 },
        "x": { "impressions": 32130, "likes": 1201, "reposts": 133, "replies": 70, "quotes": 9, "saves": 41 }
      }
    },
    "followers": [
      { "platform": "youtube", "start": 11920, "end": 12840, "change": 920, "series": [{ "day": "2026-10-08", "value": 11920 }, { "day": "2026-11-07", "value": 12840 }] }
    ],
    "top_posts": [
      {
        "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
        "platform": "youtube",
        "title": "How we ship",
        "url": "https://youtube.com/shorts/aB3xYz12Q",
        "published_at": "2026-10-21T16:02:11.000Z",
        "score": 1508,
        "stats": { "views": 48100, "likes": 905, "comments": 61, "favorites": 0 }
      }
    ]
  }
}
```

### posts

How many posts went live (`published`) and how many failed in the period, in total and per network. A post sent to three networks counts once per network.

### engagement

The numbers of the period's posts, added up per network in `by_platform`. `interactions` adds likes, favorites, comments, replies, reposts, shares, quotes and saves across every network. `views` adds views, or impressions where a network gives those instead.

A post's numbers are read about two days after it goes out, so the last two days of a period have little or no engagement yet. Networks that share no post numbers don't appear here; see [What each network shares](/api/analytics#post-numbers-by-network).

### followers

Per network, from the daily account readings (see [History](/api/analytics#history)):

- `start` and `end`: the first and last follower count in the period. `start` is `null` when there is only one reading.
- `change`: `end` minus `start`, or `null` without a start.
- `series`: every daily reading, for a chart.

Networks are sorted by `end`, biggest first.

### top_posts

The five posts with the highest score in the period. The score counts likes, saves and favorites once, comments and replies twice, reposts, shares and quotes three times, and adds one for every 100 views. `stats` has the post's numbers as read.

Posts made with a [test key](/guides/test-mode) are left out of reports.

The call needs a key with the `analytics` scope.

Source: https://docs.reelspan.com/api/reports

---

# AI captions

> Have AI write a title or caption for each network from a video, photos or your own text, within each network's limits. Each call uses one AI credit.

Reelspan can write the captions for you: a YouTube title, description and tags, an Instagram caption, an X post, and so on, each in that network's style and within its limits. It works from what the post has: the video's frames and speech, the photos, or a caption you wrote.

There are three calls:

| Call | Give it | Use it when |
| --- | --- | --- |
| `POST /v1/ai/video-captions` | A video file or link | You have a video and no caption yet |
| `POST /v1/ai/adapt-captions` | Any of: your text, notes, an uploaded video or photos | You already uploaded the media, or have a rough caption |
| `POST /v1/ai/rewrite-captions` | Captions you already have | You want your captions reshaped for other networks |

Each successful call uses one AI credit. Nothing is posted: you get the captions back and send them with your post.

## From a video

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/ai/video-captions \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "video=@launch.mp4" \
  -F "platforms=youtube,tiktok,instagram" \
  -F "context=Our new app launches on Monday; free for the first month"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const captions = await reelspan.ai.captionsFromVideo(
  { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  { platforms: ['youtube', 'tiktok', 'instagram'], context: 'Our new app launches on Monday; free for the first month' },
);
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
captions = reelspan.ai.captions_from_video(
    "launch.mp4",
    platforms=["youtube", "tiktok", "instagram"],
    context="Our new app launches on Monday; free for the first month",
)
```

Reelspan samples frames from the video and transcribes its speech, then writes the captions. The video can be a file or a public https link (Google Drive and Dropbox share links work), up to 100 MB and 5 minutes long. It is deleted once the captions are written; to post it, upload it separately.

- `platforms`: comma-separated; `youtube,instagram,tiktok` when left out.
- `language`: the language to write in, such as `English` or `es`. Without it, the captions follow the language spoken or written in the video.
- `context`: your notes on the video (facts, names, the angle you want), up to 4,000 characters. The AI is told to use only what the video and your notes show, and not to invent facts.

```json
{
  "success": true,
  "ai_generated": true,
  "remaining_analyses": 99,
  "youtube": {
    "title": "Our new app launches Monday: first month free #shorts",
    "description": "Our new app launches on Monday, and the first month is free…",
    "tags": ["app launch", "new app", "productivity app"]
  },
  "tiktok": { "caption": "New app drops Monday. First month on us. #applaunch #productivity #newapp" },
  "instagram": { "caption": "Our new app launches Monday.\n\nTry it free for the first month…" }
}
```

`remaining_analyses` is how many AI credits are left this month.

## From an upload, photos or your text

`adapt-captions` writes from whatever you give it. The most common case is media you already uploaded with [Upload media](/api/upload-media): send its `media_id`, and Reelspan reads the frames and speech on the server.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/ai/adapt-captions \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_id": "med_4f2a…", "platforms": ["youtube", "linkedin", "x"], "notes": "Behind the scenes of our launch week"}'
```

```javascript title="Node.js"
const captions = await reelspan.ai.writeCaptions({ mediaId: 'med_4f2a…', platforms: ['youtube', 'linkedin', 'x'], notes: 'Behind the scenes of our launch week' });
```

```python title="Python"
captions = reelspan.ai.write_captions(media_id="med_4f2a…", platforms=["youtube", "linkedin", "x"], notes="Behind the scenes of our launch week")
```

Give it any of these (at least one):

- `text`: your own caption, up to 5,000 characters. It is kept as the facts and adapted per network. With `text`, the video's speech isn't transcribed.
- `notes`: hints for the AI without writing the caption yourself, up to 4,000 characters.
- `media_id`: a video uploaded earlier.
- `photo_media_ids`: up to 10 photos uploaded earlier.
- `frames`, `images` and `audio`: the media itself, base64-encoded, if you'd rather not upload it first. See the fields below.

`kind` (`video`, `photo` or `text`) says what the post is, and `language` sets the language. The answer is like the one above, plus `summary` (one or two neutral sentences about the post, useful as a base caption) and `transcript` when the speech was transcribed.

With nothing to work from, the answer is **400** `NOTHING_TO_ADAPT`.

## Rewrite your captions

`rewrite-captions` keeps your facts and changes the style, length and hashtags for each network.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/ai/rewrite-captions \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "youtube": { "title": "How we ship a release in one day", "description": "A walk through our release checklist." } },
    "platforms": ["linkedin", "x", "threads"],
    "instructions": "Friendly, no emojis"
  }'
```

```javascript title="Node.js"
const captions = await reelspan.ai.rewriteCaptions(
  { youtube: { title: 'How we ship a release in one day', description: 'A walk through our release checklist.' } },
  { platforms: ['linkedin', 'x', 'threads'], instructions: 'Friendly, no emojis' },
);
```

```python title="Python"
captions = reelspan.ai.rewrite_captions(
    {"youtube": {"title": "How we ship a release in one day", "description": "A walk through our release checklist."}},
    platforms=["linkedin", "x", "threads"],
    instructions="Friendly, no emojis",
)
```

- `content`: your captions, keyed by network, up to 20,000 characters in all.
- `platforms`: the networks to write for. Without it, the supported networks named in `content`.
- `instructions`: how to write them, up to 1,000 characters.

## What you get per network

Captions are cut to fit each network's limit, at a word where possible.

| Network | Fields | Limits (characters) |
| --- | --- | --- |
| `youtube` | `title`, `description`, `tags` | 100, 5,000; up to 15 tags |
| `instagram` | `caption` | 2,200 |
| `tiktok` | `caption` | 2,200 |
| `facebook` | `caption` | 2,200 |
| `x` | `text` | 280 |
| `threads` | `text` | 500 |
| `bluesky` | `text` | 300 |
| `linkedin` | `text` | 3,000 |
| `pinterest` | `title`, `description` | 100, 500 |

These nine networks are the ones AI captions support; any other network in `platforms` answers **400**. To post them, put each value in that network's caption field, for example `youtube_title` and `youtube_description` on [Post a video](/api/post-video).

## Credits per plan

| Plan | AI credits a month |
| --- | --- |
| Free | 10 |
| Starter | 100 |
| Pro | 400 |
| Agency | 1,000 |
| Scale | 2,500 |

Credits renew on the first day of each month (UTC) and don't carry over. A credit is used only when captions come back; a call that fails costs nothing. Calls made with a [test key](/guides/test-mode) use real credits too.

## Errors

| Status | `error_code` | When |
| --- | --- | --- |
| 400 | `NOTHING_TO_ADAPT` | `adapt-captions` got no text, notes or media. |
| 400 | `MEDIA_REQUIRED` | `video-captions` got no video file or link. |
| 400 | `VIDEO_TOO_LONG` | The video is longer than 5 minutes. |
| 400 | | A network in `platforms` isn't supported. The message lists the supported ones. |
| 413 | `FILE_TOO_LARGE` | The video is over 100 MB. |
| 429 | `AI_CREDITS_EXHAUSTED` | No credits left this month. |
| 502 | varies | The AI provider failed. Try again; no credit was used. |
| 503 | `AI_NOT_CONFIGURED` | AI captions are unavailable right now. |

All three calls need a key with the `publish` scope.

Source: https://docs.reelspan.com/api/ai-captions

---

# Post to TikTok

> Post videos and photo carousels to TikTok through the API, directly or to the TikTok inbox, with privacy, interaction and disclosure settings.

Reelspan posts to TikTok through TikTok's Content Posting API. You send the video or photos once; Reelspan checks what the account may post, uploads the file in chunks, waits for TikTok to finish processing and returns the post's link.

## What you can post

| Post | How | Notes |
| --- | --- | --- |
| Video | [`POST /v1/posts/video`](/api/post-video) | Posted directly, or sent to the TikTok inbox as a draft |
| Photo post | [`POST /v1/posts/photos`](/api/post-photos) | Up to 35 photos, swiped like a carousel |

TikTok has no text-only posts and no documents. Reelspan handles for you:

- **The creator check.** TikTok asks apps to read the account's current options before every direct post. Reelspan does it on each post: the privacy levels the account allows, the interactions the creator has turned off, and the longest video it may post.
- **Chunked upload.** Videos up to 64 MB go up in one piece; larger ones in 10 MB chunks.
- **Photo formats.** TikTok takes JPEG and WebP only. Other formats, and photos over 20 MB, are converted to JPEG first (the result says so in `warnings`).
- **Waiting.** Reelspan follows the post until TikTok reports it published, for up to 10 minutes.

## Connect the account

TikTok connects with an OAuth sign-in: in the dashboard go to **Accounts → TikTok**, or send your client a [white-label connect link](/white-label). Any TikTok account works, personal or business.

> [!IMPORTANT]
> Until Reelspan's TikTok app passes TikTok's audit, TikTok only accepts **private** posts. Reelspan posts them as private (Only me) and says so in `warnings`; you make them public in the TikTok app. If TikTok refuses because the account itself is public, set it to private in TikTok (Settings → Privacy → Private account), or send the post to the inbox with `post_mode=MEDIA_UPLOAD`.

## Example

A video with a caption, visible to everyone, with duets turned off:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "tiktok_title=Three ways to fold a shirt #laundry #lifehack" \
  -F "privacy_level=PUBLIC_TO_EVERYONE" \
  -F "disable_duet=true" \
  -F "cover_timestamp=1500" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['tiktok'],
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: {
    tiktok_title: 'Three ways to fold a shirt #laundry #lifehack',
    privacy_level: 'PUBLIC_TO_EVERYONE',
    disable_duet: true,
    cover_timestamp: 1500,
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["tiktok"], "launch.mp4",
    extra={
        "tiktok_title": "Three ways to fold a shirt #laundry #lifehack",
        "privacy_level": "PUBLIC_TO_EVERYONE",
        "disable_duet": True,
        "cover_timestamp": 1500,
    },
)
```

A photo post works the same way with [`POST /v1/posts/photos`](/api/post-photos): add `photo_cover_index` to pick the cover and `auto_add_music=true` to let TikTok add a track.

## Check the account first

`GET /v1/tiktok/creator-info?profile=my-brand` returns what this TikTok account may post right now. Use it to offer only the privacy levels TikTok allows, and to warn before a video is too long.

```bash title="cURL"
curl "https://api.reelspan.com/v1/tiktok/creator-info?profile=my-brand" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const info = await reelspan.request('GET', '/v1/tiktok/creator-info', { query: { profile: 'my-brand' } });
```

```python title="Python"
info = reelspan.request("GET", "/v1/tiktok/creator-info", query={"profile": "my-brand"})
```

```json
{
  "success": true,
  "nickname": "My Brand",
  "username": "mybrand",
  "avatar": "https://p16-sign.tiktokcdn.com/…",
  "privacy_options": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY"],
  "comment_disabled": false,
  "duet_disabled": false,
  "stitch_disabled": true,
  "max_video_post_duration_sec": 600
}
```

It answers 404 when the profile has no TikTok account, and 409 with `reauth_required` when the account needs to be connected again.

## Fields

Send these as form fields next to the usual ones (`user`, `platform[]`, the media). Booleans take `true` or `false`.

| Field | Type | Values | What it does |
| --- | --- | --- | --- |
| `tiktok_title` | string | up to 2,200 characters | The caption. Falls back to `title`. On a photo post, the first line (up to 90 characters) becomes the post's title. |
| `tiktok_description` | string | up to 4,000 characters | Photo posts only: the description under the photos. Defaults to the caption. |
| `privacy_level` | string | `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY` | Who can see the post. Must be one of the account's `privacy_options`. Without it, Reelspan uses `PUBLIC_TO_EVERYONE` when allowed, otherwise the first allowed option. |
| `post_mode` | string | `DIRECT_POST` (default), `MEDIA_UPLOAD` | `MEDIA_UPLOAD` sends the post to the creator's TikTok inbox to finish in the app. |
| `tiktok_upload_to_draft` | boolean | default `false` | Same as `post_mode=MEDIA_UPLOAD`. `upload_to_draft` works too. |
| `disable_comment` | boolean | default `false` | Turns comments off. Always on when the creator has turned comments off. |
| `disable_duet` | boolean | default `false` | Videos only: turns duets off. Always on when the creator has turned them off. |
| `disable_stitch` | boolean | default `false` | Videos only: turns stitches off. Always on when the creator has turned them off. |
| `cover_timestamp` | number | milliseconds | Videos only: the frame TikTok uses as the cover. |
| `photo_cover_index` | number | 0-based, default `0` | Photo posts only: which photo is the cover. |
| `auto_add_music` | boolean | default `false` | Photo posts only: TikTok adds music to the photos. |
| `brand_organic_toggle` | boolean | default `false` | Discloses that the post promotes your own business ("Promotional content"). |
| `brand_content_toggle` | boolean | default `false` | Discloses a paid partnership with another brand ("Paid partnership"). Branded content can't be private. |
| `is_aigc` | boolean | default `false` | Videos only: adds TikTok's AI-generated label. `tiktok_is_ai_generated` and `is_ai_generated` work too. |

The privacy, interaction, disclosure and AI settings apply to direct posts only. A video sent to the inbox carries only the video, not the caption; a photo post sent to the inbox keeps its title and description. The creator sets the rest in the TikTok app.

## Limits

- **Caption:** 2,200 characters for a video. A photo post has a 90-character title (the caption's first line) and a description up to 4,000 characters.
- **Video length:** whatever TikTok allows this account, shown as `max_video_post_duration_sec` in the creator check. A longer video fails before it is uploaded.
- **Video size:** your plan's upload limit (see [Plans and limits](/limits/plans)).
- **Photos:** up to 35 per post, JPEG or WebP (other formats are converted), up to 20 MB each.
- **Shape:** vertical 9:16.

## Good to know

- **Processing.** TikTok processes every post before it goes live. Reelspan waits up to 10 minutes. When TikTok has published the post but is still reviewing it, the result has no `url` yet and says so in `warnings`.
- **Inbox posts** come back with `url: null` and a warning: the creator finishes them in TikTok's notifications.
- **Result extras:** `publish_id` (TikTok's id for the upload) and `status` (`PUBLISH_COMPLETE` or `SEND_TO_USER_INBOX`).
- **Covers.** TikTok's cover is a frame of the video, picked with `cover_timestamp`; an uploaded cover image is not sent to TikTok.
- **First comment:** TikTok's API has no comments, so `first_comment` isn't posted; the result says `first_comment: "unsupported"`.
- **Analytics:** account numbers (followers, following, likes, videos) when your Reelspan workspace has TikTok statistics turned on. An account connected before that has to be reconnected. There are no per-post numbers.
- **TikTok's own limits** apply on top: a daily post limit per account, and a daily limit on how many people one app can post for.

## Errors

| `error_code` | What happened | What to do |
| --- | --- | --- |
| `tiktok_privacy_unavailable` | `privacy_level` isn't one the account allows | Read `privacy_options` from the creator check and send one of those. |
| `tiktok_duration_too_long` | The video is longer than this account may post | Trim it under `max_video_post_duration_sec`. |
| `tiktok_unaudited_client_can_only_post_to_private_accounts` | The TikTok account is public, and TikTok only takes posts to private accounts from unaudited apps | Make the account private, or post with `post_mode=MEDIA_UPLOAD`. |
| `tiktok_spam_risk_too_many_posts` | The account reached TikTok's daily post limit | Post again tomorrow. |
| `tiktok_spam_risk_user_banned_from_posting` | TikTok has blocked this account from posting | Sort it out with TikTok. |
| `tiktok_reached_active_user_cap` | The app reached TikTok's daily limit of posting accounts | Retry later. |
| `tiktok_url_ownership_unverified` | TikTok hasn't verified the domain Reelspan serves photos from | Photo posts work once it is verified; videos are not affected. |
| `tiktok_processing_timeout` | TikTok took more than 10 minutes | Reelspan retries it; check the post in TikTok before posting again. |
| `tiktok_…` (other) | TikTok refused the post or failed to process it; the code carries TikTok's reason | Read `error` for TikTok's message. |
| `reauth_required` | The connection expired or lost a permission | Reconnect TikTok. |

Source: https://docs.reelspan.com/networks/tiktok

---

# Post to Instagram

> Publish Instagram Reels, Stories, photo posts and carousels through the API, with collaborators, cover images, trial Reels and alt text.

Reelspan publishes to Instagram professional accounts through Meta's Graph API. You send the video or photos once; Reelspan creates the Instagram media, waits for Instagram to process it, publishes it and returns the permalink.

## What you can post

| Post | How | Notes |
| --- | --- | --- |
| Reel | [`POST /v1/posts/video`](/api/post-video) | The default for a video |
| Video Story | [`POST /v1/posts/video`](/api/post-video) with `media_type=STORIES` | No caption |
| Photo post | [`POST /v1/posts/photos`](/api/post-photos) with one photo | |
| Carousel | [`POST /v1/posts/photos`](/api/post-photos) with 2 to 10 items | Photos and videos can be mixed |
| Photo Story | [`POST /v1/posts/photos`](/api/post-photos) with `media_type=STORIES` | No caption |

Instagram has no text-only posts and no documents. Reelspan handles for you:

- **JPEG only.** Instagram takes JPEG photos. PNG, WebP, HEIC and JPEGs over 8 MB are converted to a JPEG under 8 MB first; the result says so in `warnings`.
- **Mixed carousels.** Videos sent in `photos[]` become video items of the carousel. Each video item is processed before the carousel is made.
- **Processing.** Instagram fetches the media from a short-lived signed link and processes it. Reelspan waits for it (up to 15 minutes), publishes it, then reads back the post's permalink.

## Connect the account

Instagram connects through Facebook Login, so the account needs to be set up the way Meta's API requires:

1. The Instagram account is a **professional account** (Business or Creator). Switch in the Instagram app under Settings → Account type and tools.
2. It is **linked to a Facebook Page** you manage.
3. In Reelspan, go to **Accounts → Instagram**, sign in with the Facebook account that manages that Page, and share the Page when Facebook asks.

Reelspan connects the Instagram account linked to the first shared Page that has one. If you manage several, share only the Page whose Instagram account you want on this profile. The same Facebook sign-in can connect Facebook Pages too; each is its own connection.

## Example

A Reel with a co-author and a custom cover:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=instagram" \
  -F "instagram_title=Behind the scenes of our spring shoot 🌸" \
  -F "collaborators=@partnerstudio" \
  -F "share_to_feed=true" \
  -F "cover_url=https://example.com/cover.jpg" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['instagram'],
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: {
    instagram_title: 'Behind the scenes of our spring shoot 🌸',
    collaborators: '@partnerstudio',
    share_to_feed: true,
    cover_url: 'https://example.com/cover.jpg',
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["instagram"], "launch.mp4",
    extra={
        "instagram_title": "Behind the scenes of our spring shoot 🌸",
        "collaborators": "@partnerstudio",
        "share_to_feed": True,
        "cover_url": "https://example.com/cover.jpg",
    },
)
```

A carousel is the same request on [`POST /v1/posts/photos`](/api/post-photos) with several `photos[]`, and `alt_text[]` (or `instagram_alt_text[]`) in the same order.

## Fields

| Field | Type | Values | What it does |
| --- | --- | --- | --- |
| `instagram_title` | string | up to 2,200 characters | The caption. Falls back to `title`. Longer text is cut. Not used on Stories. |
| `media_type` | string | Video: `REELS` (default), `STORIES`. Photos: `FEED` (default), `STORIES` | Post a Story instead of a Reel or feed post. |
| `share_to_feed` | boolean | default `true` | Reels: also show the Reel in the profile's feed. `false` keeps it on the Reels tab. |
| `collaborators` | string | comma-separated usernames, up to 3 | Reels: accounts invited to co-author the Reel. A leading `@` is removed. |
| `cover_url` | string | public https URL of an image | Reels: the cover image. You can also upload the image as a `cover` file or send `cover_media_id`. |
| `thumb_offset` | number | milliseconds | Reels: the frame used as the cover when there is no cover image. |
| `audio_name` | string | | Reels: the name shown for the Reel's audio. |
| `location_id` | string | numeric Facebook place id | Reels: tags a location. A non-numeric value is ignored with a warning. |
| `share_mode` | string | `CUSTOM` (a normal Reel), `TRIAL_REELS_SHARE_TO_FOLLOWERS_IF_LIKED`, or another trial mode | Reels: post a trial Reel, shown to non-followers first. With `TRIAL_REELS_SHARE_TO_FOLLOWERS_IF_LIKED` Instagram shares it with followers if it performs well; any other value except `CUSTOM` makes a trial Reel you share with followers yourself. |
| `instagram_alt_text` | string or list | up to 1,000 characters each | Photo alt text: one text for every photo, or one per photo in order. Falls back to `alt_text`. Not used on Stories or video items. |
| `instagram_first_comment` | string | up to 2,200 characters | A comment posted under the new post. Falls back to `first_comment`. |

## Limits

- **Caption:** 2,200 characters. Instagram also allows at most 30 hashtags and 20 mentions.
- **Carousel:** up to 10 items; with more, the first 10 are used and the result says so.
- **Photos:** JPEG up to 8 MB (other photos are converted). Instagram takes feed photos from 4:5 to 1.91:1.
- **Video size:** your plan's upload limit (see [Plans and limits](/limits/plans)).
- **Shapes:** 9:16 for Reels and Stories, 4:5 or 1:1 for feed posts.

## Good to know

- **Stories carry no caption,** and a photo Story uses the first photo only.
- **Collaborators, covers, location, audio name and trial Reels** apply to Reels; they are ignored on Stories and photo posts.
- **Result extras:** `container_id` (Instagram's media container) and, for videos, `media_type`.
- **First comment:** Reelspan posts it under the new post. If Meta refuses it (for example a missing comment permission on the connection), the post stays up and the result carries `first_comment: "failed"` and a warning.
- **Analytics:** account followers, following and post count; per post, likes and comments.

## Errors

| `error_code` | What happened | What to do |
| --- | --- | --- |
| `instagram_processing_failed` | Instagram couldn't process the media (wrong format, length or shape) | Check the file against Instagram's rules and post again. |
| `instagram_processing_timeout` | Instagram took more than 15 minutes | Reelspan retries it; check Instagram before posting again. |
| `meta_permission_denied` | The connection lacks a permission Meta needs | Reconnect Instagram and accept every permission. |
| `meta_rate_limited` | Meta's rate limit was hit | Reelspan retries it later. |
| `meta_error` | Meta refused the request | Read `error` for Meta's message. |
| `reauth_required` | The token expired or was revoked | Reconnect Instagram. |
| `media_required` | The request had no video or photo for Instagram | Send media: Instagram has no text posts. |

Source: https://docs.reelspan.com/networks/instagram

---

# Post to YouTube

> Upload YouTube Shorts and long-form videos through the API, with title, tags, privacy, scheduled release, playlists and a custom thumbnail.

Reelspan uploads to YouTube with the YouTube Data API. You send the video once with a title; Reelspan uploads it to the channel with your metadata, sets the thumbnail and playlists, and returns the video's link. A vertical video up to 3 minutes gets a `youtube.com/shorts/…` link, anything else a `watch?v=` link.

## What you can post

| Post | How | Notes |
| --- | --- | --- |
| Short | [`POST /v1/posts/video`](/api/post-video) | A vertical video up to 3 minutes |
| Long-form video | [`POST /v1/posts/video`](/api/post-video) | Any other video |

YouTube takes videos only: no photos, text or Community posts through the API. Reelspan handles for you:

- **Resumable upload** of the file to YouTube, so large videos go up in one session.
- **Clean metadata.** YouTube refuses `<` and `>` in descriptions; Reelspan removes them. Titles over 100 characters and descriptions over 5,000 are cut.
- **Extras that never fail the post.** The thumbnail and playlists are added after the upload. If YouTube refuses one, the video stays up and the result says what didn't work.

## Connect the account

YouTube connects with a Google sign-in: in the dashboard go to **Accounts → YouTube**, or send a [white-label connect link](/white-label). Sign in with the Google account that owns or manages the channel. The account must already have a YouTube channel; create one at youtube.com first if it doesn't.

## Example

A public Short with tags, in a playlist, with a custom thumbnail:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=youtube" \
  -F "youtube_title=How we ship a release in 60 seconds" \
  -F "youtube_description=Our release checklist, start to finish." \
  -F "tags[]=devops" -F "tags[]=release" \
  -F "privacyStatus=public" \
  -F "categoryId=28" \
  -F "youtube_playlist_id=PLxxxxxxxxxxxxxxxx" \
  -F "thumbnail=@thumbnail.jpg" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['youtube'],
  title: 'How we ship a release in 60 seconds',
  description: 'Our release checklist, start to finish.',
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  thumbnail: { data: await readFile('thumbnail.jpg'), name: 'thumbnail.jpg', type: 'image/jpeg' },
  extra: {
    tags: ['devops', 'release'],
    privacyStatus: 'public',
    categoryId: '28',
    youtube_playlist_id: 'PLxxxxxxxxxxxxxxxx',
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["youtube"], "launch.mp4", "How we ship a release in 60 seconds",
    description="Our release checklist, start to finish.",
    thumbnail="thumbnail.jpg",
    extra={
        "tags": ["devops", "release"],
        "privacyStatus": "public",
        "categoryId": "28",
        "youtube_playlist_id": "PLxxxxxxxxxxxxxxxx",
    },
)
```

## Fields

YouTube needs a title: `youtube_title` or `title`. A request with YouTube and neither is refused with 400 before anything is uploaded.

| Field | Type | Values | What it does |
| --- | --- | --- | --- |
| `youtube_title` | string | up to 100 characters | The video's title. Falls back to `title`. |
| `youtube_description` | string | up to 5,000 characters | The description. Falls back to `description`, then `title`. |
| `tags[]` | list | repeated field | Tags for the video. `youtube_tags[]` works too; both lists are combined. |
| `privacyStatus` | string | `public` (default), `unlisted`, `private` | Who can watch it. `youtube_privacy_status` works too. |
| `youtube_publish_at` | string | ISO 8601 date and time | Uploads the video as private and lets YouTube make it public at that time. |
| `categoryId` | string | a YouTube category id, default `22` (People & Blogs) | The video's category. |
| `defaultLanguage` | string | language code, e.g. `en` | The language of the title and description. |
| `defaultAudioLanguage` | string | language code | The language spoken in the video. |
| `selfDeclaredMadeForKids` | boolean | default `false` | Marks the video as made for children. |
| `containsSyntheticMedia` | boolean | | Discloses realistic altered or AI-made content. `is_ai_generated` works too. Left unset unless you send it. |
| `embeddable` | boolean | default `true` | Whether other sites may embed the video. |
| `license` | string | `youtube` (default), `creativeCommon` | The video's license. |
| `publicStatsViewable` | boolean | default `true` | Whether the like and view counts are public. |
| `recordingDate` | string | ISO 8601 date | When the video was recorded. |
| `youtube_notify_subscribers` | boolean | default `true` | Whether subscribers are notified. |
| `youtube_playlist_id` | string | one id, or several separated by commas | Adds the video to these playlists. |
| `hasPaidProductPlacement` | boolean | | Discloses paid product placement in the video. Left unset unless you send it. |
| `thumbnail` | file | JPG or PNG | A custom thumbnail. Or send `thumbnail_url` (a public URL) or `thumbnail_media_id` (from [Upload media](/api/upload-media)). |
| `youtube_first_comment` | string | up to 10,000 characters | A comment posted under the video. Falls back to `first_comment`. |

## Limits

- **Title:** 100 characters. **Description:** 5,000 characters.
- **Shorts:** vertical (9:16) and up to 3 minutes. Longer or horizontal videos are regular videos.
- **Thumbnail:** JPG or PNG, 16:9, up to 2 MB. Custom thumbnails need a verified channel, and YouTube doesn't show them on Shorts.
- **Video size:** your plan's upload limit (see [Plans and limits](/limits/plans)).

## Good to know

- **Daily limits.** YouTube caps uploads twice: a daily API quota for the app, and a daily upload limit per channel. Either one fails the post with a code that says which (`youtube_quotaExceeded`, `youtube_uploadLimitExceeded`); both reset the next day.
- **Scheduled release vs scheduled post.** `youtube_publish_at` uploads now and YouTube releases the video later. Reelspan's `scheduled_date` waits and uploads at that time. Use one or the other.
- **Result extras:** `video_id`, `privacy_status`, and `playlists` with one entry per playlist (`success`, `playlist_id`, and an `error` when it failed).
- **Thumbnail warnings.** If YouTube refuses the thumbnail, the video stays up with a warning.
- **First comment:** Reelspan posts it as a top-level comment. If YouTube refuses it, the video stays up and the result carries `first_comment: "failed"` and a warning.
- **Analytics:** channel subscribers, views and video count; per video, views, likes, comments and favorites.

## After posting

- **Change the thumbnail** of a published video with [YouTube thumbnail](/api/youtube-thumbnail), by its video id or the `request_id` that published it.
- Videos can't be edited or deleted through Reelspan: that needs a wider YouTube permission than the upload access Reelspan asks for. Change or remove them in YouTube Studio.

## Errors

| `error_code` | What happened | What to do |
| --- | --- | --- |
| `youtube_quotaExceeded` | The daily YouTube API quota ran out | Post again tomorrow. |
| `youtube_uploadLimitExceeded` | The channel reached YouTube's daily upload limit | Post again tomorrow. |
| `youtube_youtubeSignupRequired` | The Google account has no YouTube channel | Create the channel, then reconnect. |
| `youtube_forbidden` | YouTube refused the upload for this channel | Read `error`; check the channel's standing in YouTube Studio. |
| `youtube_rejected` | YouTube rejected the video after upload (for example a duplicate or a copyright claim) | Read `error` for YouTube's reason. |
| `youtube_…` (other) | YouTube refused the request; the code carries YouTube's reason | Read `error` for YouTube's message. |
| `youtube_error` | YouTube failed without a reason | Reelspan retries server errors; otherwise post again. |
| `reauth_required` | The Google sign-in expired or was revoked | Reconnect YouTube. |

Source: https://docs.reelspan.com/networks/youtube

---

# Post to Facebook

> Publish Reels, Page videos, photo posts, Stories and text posts to your Facebook Pages through the API, choose the Page, and edit or delete posts.

Reelspan publishes to Facebook Pages with Meta's Graph API. You send the post once; Reelspan uploads it to the Page you chose, waits until Facebook reports a Reel as published, and returns its link. Posting to personal profiles and groups isn't possible through Meta's API.

## What you can post

| Post | How | Notes |
| --- | --- | --- |
| Reel | [`POST /v1/posts/video`](/api/post-video) | The default for a video |
| Page video | [`POST /v1/posts/video`](/api/post-video) with `facebook_media_type=VIDEO` | A regular Page video, any shape, with a title |
| Video Story | [`POST /v1/posts/video`](/api/post-video) with `facebook_media_type=STORIES` | No caption |
| Photo post | [`POST /v1/posts/photos`](/api/post-photos) | One photo, or up to 30 in one post |
| Photo Stories | [`POST /v1/posts/photos`](/api/post-photos) with `facebook_media_type=STORIES` | Each photo becomes its own Story, up to 10 |
| Text post | [`POST /v1/posts/text`](/api/post-text) | With an optional link preview |

Reelspan handles for you:

- **Pulling, not streaming.** Facebook fetches the video itself from a signed link, which is faster for large files.
- **Multi-photo posts.** Each photo is uploaded first, then attached to one Page post in order.
- **Waiting for the Reel.** Reelspan follows the Reel until Facebook reports it published (up to 10 minutes), so the link works when you get it.

## Connect the account

Facebook connects through Facebook Login: in the dashboard go to **Accounts → Facebook**, or send a [white-label connect link](/white-label). Sign in with a Facebook account that manages the Page, and select the Pages to share when Facebook asks.

- **One Page shared:** every post goes there.
- **Several Pages shared:** choose the default under **Accounts → Facebook → Details** or with [`POST /v1/facebook/page`](#choose-the-page), or name the Page on each post with `facebook_page_id`. Without either, the post fails with `facebook_page_required`.

To add a Page later, reconnect Facebook and select it.

## Example

A Reel to a chosen Page:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=facebook" \
  -F "facebook_page_id=104512345678901" \
  -F "facebook_title=Spring collection is live" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['facebook'],
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: { facebook_page_id: '104512345678901', facebook_title: 'Spring collection is live' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["facebook"], "launch.mp4",
    extra={"facebook_page_id": "104512345678901", "facebook_title": "Spring collection is live"},
)
```

A text post with a link preview:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user": "my-brand", "platform": ["facebook"], "title": "Our spring lookbook is out.", "facebook_link": "https://example.com/lookbook"}'
```

```javascript title="Node.js"
await reelspan.posts.text({
  user: 'my-brand',
  platforms: ['facebook'],
  title: 'Our spring lookbook is out.',
  extra: { facebook_link: 'https://example.com/lookbook' },
});
```

```python title="Python"
reelspan.posts.text("my-brand", ["facebook"], "Our spring lookbook is out.", extra={"facebook_link": "https://example.com/lookbook"})
```

## Choose the Page

`GET /v1/facebook/pages?profile=my-brand` lists the Pages shared with this profile's Facebook connection, with each Page's followers and likes. `selected` marks the Page chosen as the default, also named in `selected_page_id` and `selected_page_name`.

```bash title="cURL"
curl "https://api.reelspan.com/v1/facebook/pages?profile=my-brand" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const { pages } = await reelspan.request('GET', '/v1/facebook/pages', { query: { profile: 'my-brand' } });
```

```python title="Python"
pages = reelspan.request("GET", "/v1/facebook/pages", query={"profile": "my-brand"})["pages"]
```

```json
{
  "success": true,
  "pages": [
    { "id": "104512345678901", "name": "My Brand", "picture": "https://…", "account_id": "104512345678901", "selected": true, "followers": 18240, "likes": 17955 },
    { "id": "209876543210987", "name": "My Brand Outlet", "picture": null, "account_id": "104512345678901", "selected": false, "followers": 950, "likes": null }
  ],
  "selected_page_id": "104512345678901",
  "selected_page_name": "My Brand"
}
```

The list comes from the connection, so it shows the Pages shared when it was made. `followers` and `likes` are read live from Facebook and are `null` when it doesn't say. A profile with no Facebook account gets **404** `profile_platform_mapping_invalid`.

To make a Page the default, send its id to `POST /v1/facebook/page` (needs the `profiles` scope). A post that names no `facebook_page_id` then goes there.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/facebook/page \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile": "my-brand", "facebook_page_id": "209876543210987"}'
```

```javascript title="Node.js"
await reelspan.request('POST', '/v1/facebook/page', { json: { profile: 'my-brand', facebook_page_id: '209876543210987' } });
```

```python title="Python"
reelspan.request("POST", "/v1/facebook/page", json_body={"profile": "my-brand", "facebook_page_id": "209876543210987"})
```

```json
{ "success": true, "facebook_page_id": "209876543210987", "facebook_page_name": "My Brand Outlet" }
```

A Page that wasn't shared with Reelspan gets **404** `facebook_page_not_connected`: reconnect Facebook and select it. `DELETE /v1/facebook/page` with `{"profile": "my-brand"}` clears the choice; then each post needs `facebook_page_id`, unless only one Page is connected.

### Page details

`GET /v1/facebook/page-info?profile=my-brand` reads a Page's details from Facebook: name, username, about, description, website, phone, emails, opening hours, link, category, picture, cover, followers and likes. Send `page_id` for another of the connected Pages; without it, the chosen Page (or the only one) is used, and with several Pages and none chosen the answer is **400** `facebook_page_required`.

```bash title="cURL"
curl "https://api.reelspan.com/v1/facebook/page-info?profile=my-brand" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```json
{
  "success": true,
  "page_id": "104512345678901",
  "page": {
    "id": "104512345678901",
    "name": "My Brand",
    "username": "mybrand",
    "about": "Everyday bags, made to last.",
    "website": "https://example.com",
    "phone": "+44 20 7946 0000",
    "emails": ["hello@example.com"],
    "hours": { "mon_1_open": "09:00", "mon_1_close": "17:00" },
    "hours_list": [{ "day": "mon", "open": "09:00", "close": "17:00" }],
    "category": "Clothing store",
    "picture_url": "https://…",
    "cover_url": "https://…",
    "followers": 18240,
    "likes": 17955
  }
}
```

`hours` is Facebook's own shape; `hours_list` is the same as a list. Fields Facebook has no value for are `null`. The details are read only: Reelspan can't change them.

## Fields

| Field | Type | Values | What it does |
| --- | --- | --- | --- |
| `facebook_page_id` | string | a Page id from the list above | The Page to post to. Without it, the account's chosen Page (or its only Page). |
| `facebook_title` | string | up to 63,206 characters | The post text. Falls back to `title`. On a Reel it is also the Reel's title (first 255 characters). |
| `facebook_description` | string | | Post text that takes the place of `facebook_title` when both are sent. Falls back to `description`. |
| `facebook_media_type` | string | Video: `REELS` (default), `VIDEO`, `STORIES`. Photos: `STORIES`, otherwise a post | `VIDEO` posts a regular Page video instead of a Reel; `STORIES` a Story. |
| `video_state` | string | `PUBLISHED` (default), `DRAFT` | Reels: `DRAFT` uploads the Reel without publishing it. |
| `facebook_unpublished_content_type` | string | `SCHEDULED`, `DRAFT`, `ADS_POST` | `VIDEO` only: uploads the video without showing it on the Page, as this kind. |
| `facebook_no_story` | boolean | default `false` | `VIDEO` and photo posts: publish without a story in followers' feeds. |
| `facebook_place_id` | string | the Page id of a place | Photo, text and `VIDEO` posts: tags a place. |
| `facebook_link` | string | URL | Text posts: a link Facebook shows as a preview card. `facebook_link_url` and `link_url` work too. |
| `facebook_alt_text` | string or list | up to 1,000 characters each | Photo alt text: one for every photo, or one per photo in order. Falls back to `alt_text`. |
| `facebook_first_comment` | string | up to 8,000 characters | A comment posted under the new post. Falls back to `first_comment`. |

> [!WARNING]
> Facebook uses the description before the caption: if you send a general `description` for other networks (YouTube, LinkedIn), Facebook posts that text instead of `title`. Send `facebook_title` and leave `description` out, or send `facebook_description` with the text you want.

## Limits

- **Post text:** 63,206 characters. Stories carry no text.
- **Photos:** up to 30 in a post (more are left out), up to 10 Story photos. Each photo up to 10 MB.
- **Video size:** your plan's upload limit (see [Plans and limits](/limits/plans)).
- **Shapes:** 9:16 for Reels and Stories; 16:9 also works.

## Good to know

- **Reel or Page video.** A video is a Reel unless you send `facebook_media_type=VIDEO`. A Page video can be any shape and length; `facebook_title` is its title (first 255 characters) and the post text is its description. Reelspan doesn't wait for Facebook to finish processing a Page video.
- **A slow Reel still counts.** If Facebook is still processing after 10 minutes, Reelspan returns the Reel's link anyway; it starts working shortly after.
- **Result extras:** `page_id`, and for Reels `video_id` and `video_state`; for Page videos `video_id` and `media_type: "VIDEO"`; for multi-photo posts `photo_ids`; for several Stories `story_ids`.
- **First comment:** Reelspan posts it as the Page. If Meta refuses it (for example a missing permission on the connection), the post stays up and the result carries `first_comment: "failed"` and a warning.
- **Analytics:** Page followers and likes; per post, likes and comments.

## After posting

- **Delete** a post, Reel or video with [Unpublish](/api/unpublish).
- **Edit** a post's text with [Edit a post](/api/edit-post). On a Reel or Page video, `text` (or `description`) changes the description and `title` the title.
- Posts made outside Reelspan work too: name them with `platform`, `user` and the Facebook post id.

## Errors

| `error_code` | What happened | What to do |
| --- | --- | --- |
| `facebook_page_required` | Several Pages are connected and none was chosen | Send `facebook_page_id`, or choose the Page in the dashboard. The error lists the Pages. |
| `facebook_page_not_connected` | `facebook_page_id` names a Page that wasn't shared | Reconnect Facebook and select that Page. |
| `unsupported_media_type` | `facebook_media_type` isn't `REELS`, `VIDEO` or `STORIES` | Use one of those. |
| `facebook_processing_failed` | Facebook couldn't process the Reel | Read `error`; check the file and post again. |
| `media_required` | A Story had no photo or video | Send media with Stories. |
| `meta_permission_denied` | The connection lacks a permission, or the Page role changed | Reconnect Facebook and accept every permission. |
| `meta_rate_limited` | Meta's rate limit was hit | Reelspan retries it later. |
| `meta_error` | Meta refused the request | Read `error` for Meta's message. |
| `reauth_required` | The login expired or was revoked | Reconnect Facebook. |

Source: https://docs.reelspan.com/networks/facebook

---

# Post to X

> Post to X (Twitter) through the API: videos, up to 4 photos, text, threads and polls, with quotes, replies, link handling, and edits after posting.

Reelspan posts to X with the X API v2. You send the post once; Reelspan uploads the media in chunks, waits for X to process it, and posts it. Text longer than 280 characters becomes a thread.

## What you can post

| Post | How | Notes |
| --- | --- | --- |
| Video post | [`POST /v1/posts/video`](/api/post-video) | One video per post |
| Photo post | [`POST /v1/posts/photos`](/api/post-photos) | Up to 4 photos or GIFs |
| Text post | [`POST /v1/posts/text`](/api/post-text) | |
| Thread | Any of the above with long text | Split at 280 characters |

Reelspan handles for you:

- **Threads.** Text over 280 characters is split into posts of up to 280, on paragraph breaks first, then lines, then words. The first post carries the media; each next post replies to the one before.
- **Chunked upload** of videos and images, then a wait while X processes them (up to 10 minutes).
- **Link removal.** X charges far more for a post that contains a link, so Reelspan removes links unless you keep them (see below).

## Connect the account

X connects with an OAuth sign-in: in the dashboard go to **Accounts → X**, or send a [white-label connect link](/white-label). Any X account works.

## Example

A video post where only accounts you follow can reply:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=x" \
  -F "x_title=Shipping day. Here's the 30-second tour." \
  -F "reply_settings=following" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['x'],
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: { x_title: "Shipping day. Here's the 30-second tour.", reply_settings: 'following' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["x"], "launch.mp4",
    extra={"x_title": "Shipping day. Here's the 30-second tour.", "reply_settings": "following"},
)
```

## Fields

| Field | Type | Values | What it does |
| --- | --- | --- | --- |
| `x_title` | string | any length | The post text. Falls back to `title`. Over 280 characters it becomes a thread. |
| `x_keep_links` | boolean | default `false` | Keep links in the text. Uses your plan's monthly allowance of X posts with links. |
| `x_long_text_as_post` | boolean | default `false` | Post long text as one post instead of a thread. Needs X Premium on the account. |
| `reply_settings` | string | `following`, `mentionedUsers`, `subscribers`, `verified` | Who can reply. Leave it out for everyone; other values are ignored. |
| `reply_to_id` | string | a post id | Posts this as a reply to that post. `x_reply_to_id` works too. |
| `exclude_reply_user_ids` | list | user ids | With `reply_to_id`: leaves these users out of the reply's mentions. |
| `quote_tweet_id` | string | a post id | Quotes that post. `x_quote_tweet_id` works too. |
| `poll_options` | list | 2 to 4 options, up to 25 characters each | Adds a poll. `x_poll_options` works too. Polls can't have media (see below). |
| `poll_duration` | number | minutes, 5 to 10080 (7 days), default 1440 | How long the poll stays open. `x_poll_duration` works too. |
| `poll_reply_settings` | string | `following`, `mentionedUsers`, `subscribers`, `verified` | Who can reply to the poll post. |
| `tagged_user_ids` | list | up to 10 user ids | Tags these users in the photos or video. Ignored on a post without media. |
| `geo_place_id` | string | an X place id | Attaches a place. |
| `for_super_followers_only` | boolean | default `false` | Only the account's subscribers can see it. |
| `community_id` | string | an X Community id | Posts into that Community. |
| `share_with_followers` | boolean | default `false` | With `community_id`: also shows the post to the account's followers. |
| `card_uri` | string | an X card URI | Attaches a card. |
| `direct_message_deep_link` | string | an X DM link | Adds a button that opens a direct message. |
| `nullcast` | boolean | default `false` | Posts without showing it on the timeline (a promoted-only post). |
| `x_alt_text` | string or list | up to 1,000 characters each | Photo alt text: one for every photo, or one per photo in order. Falls back to `alt_text`. |
| `x_first_comment` | string | up to 280 characters | A reply posted under the new post. Falls back to `first_comment`. |

List fields (`poll_options`, `tagged_user_ids`, `exclude_reply_user_ids`) can be sent as repeated fields, a JSON array, or one comma-separated string.

### A poll

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "my-brand",
    "platform": ["x"],
    "title": "Which should we build next?",
    "poll_options": ["Dark mode", "CSV export", "Zapier app"],
    "poll_duration": "4320"
  }'
```

X takes polls only on posts without media: on a video or photo post the poll is left out and the result carries a warning. Fewer than 2 or more than 4 options, an option over 25 characters, or a duration outside 5 to 10080 minutes fails the post with `invalid_poll`.

## Links in X posts

X bills about $0.20 for a post with a link, against about $0.015 without. So by default Reelspan removes `http://` and `https://` links from the text and adds a warning to the result.

Send `x_keep_links=true` to keep them. Each such post uses one of your plan's X link posts for the month (see [Plans and limits](/limits/plans)). When the allowance is used up, the links are removed as usual. The same check runs when you edit a scheduled post or retry one.

## Limits

- **Post:** 280 characters (counted as people see them: an emoji is one). Longer text becomes a thread, or one long post with `x_long_text_as_post` and X Premium.
- **Media per post:** one video, or up to 4 photos and GIFs. With more photos, the first 4 are used and the result says so.
- **Video size:** your plan's upload limit (see [Plans and limits](/limits/plans)).
- **Shapes:** 16:9 or 1:1 work best.

## Good to know

- **A thread that stops halfway** keeps the posts already made: the result is a success with a warning saying where it stopped.
- **Result extras:** `media_id` (and `media_ids` for several photos), and `post_ids` for a thread, in order.
- **Alt text:** if X refuses the alt text for an image, the post still goes out with a warning.
- **First comment:** posted as a reply to the new post.
- **Analytics:** followers, following, posts and likes for the account; impressions, likes, reposts, replies, quotes and saves per post.

## After posting

- **Delete** a post with [Unpublish](/api/unpublish).
- **Edit** its text with [Edit a post](/api/edit-post). X allows edits only on accounts with X Premium, within an hour of posting and up to five times. An edit makes a **new post id**: the answer gives it as `post_id`, with `previous_post_id` and `edit_history_post_ids`. Links are removed from the new text unless `fields.x_keep_links` is `true`, as when posting.
- **Repost** any public post from the account with [Repost](/api/repost). X counts reposts against the account's daily write limit.

## Errors

| `error_code` | What happened | What to do |
| --- | --- | --- |
| `x_payment_required` | The X API account behind Reelspan is out of credits | Contact Reelspan support. |
| `x_rate_limited` | X's rate limit was hit | Reelspan retries it later. |
| `x_media_failed` | X couldn't process the video or image | Read `error`; check the file and post again. |
| `x_processing_timeout` | X took more than 10 minutes to process the media | Reelspan retries it. |
| `x_error` | X refused the post (for example a duplicate post) | Read `error` for X's message. |
| `invalid_poll` | The poll options or duration are out of range | Send 2 to 4 options of up to 25 characters and a duration of 5 to 10080 minutes. |
| `reauth_required` | The sign-in expired or was revoked | Reconnect X. |

Source: https://docs.reelspan.com/networks/x

---

# Post to Threads

> Publish to Threads through the API: text posts, polls, videos, photos and carousels of up to 20 items, with replies, quotes, topic tags and reposts.

Reelspan publishes to Threads with Meta's Threads API. You send the post once; Reelspan creates the Threads media, waits for Threads to process it, publishes it and returns the permalink.

## What you can post

| Post | How | Notes |
| --- | --- | --- |
| Text post | [`POST /v1/posts/text`](/api/post-text) | Up to 500 characters |
| Video post | [`POST /v1/posts/video`](/api/post-video) | |
| Photo post | [`POST /v1/posts/photos`](/api/post-photos) with one photo | |
| Carousel | [`POST /v1/posts/photos`](/api/post-photos) with 2 to 20 items | Photos and videos can be mixed |

Reelspan handles for you:

- **Media by link.** Threads fetches each photo and video itself from a signed link that stays valid for 6 hours.
- **Mixed carousels.** Videos sent in `photos[]` become video items of the carousel.
- **Processing.** Reelspan waits until Threads has processed the post (up to 10 minutes), then publishes it.
- **Token refresh.** Threads sign-ins last 60 days; Reelspan renews them while they are still valid, so you don't have to reconnect.

## Connect the account

Threads connects with a Threads sign-in: in the dashboard go to **Accounts → Threads**, or send a [white-label connect link](/white-label). It is separate from the Instagram connection.

## Example

A carousel with a topic tag, where only mentioned profiles can reply:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/photos \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=threads" \
  -F "threads_title=Two shots from this morning's walk" \
  -F "threads_topic_tag=Photography" \
  -F "threads_reply_control=mentioned_only" \
  -F "photos[]=@photo1.jpg" \
  -F "photos[]=@photo2.jpg" \
  -F "alt_text[]=Fog over the harbour" \
  -F "alt_text[]=A heron on the pier"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.photos({
  user: 'my-brand',
  platforms: ['threads'],
  photos: [
    { data: await readFile('photo1.jpg'), name: 'photo1.jpg', type: 'image/jpeg' },
    { data: await readFile('photo2.jpg'), name: 'photo2.jpg', type: 'image/jpeg' },
  ],
  altTexts: ['Fog over the harbour', 'A heron on the pier'],
  extra: {
    threads_title: "Two shots from this morning's walk",
    threads_topic_tag: 'Photography',
    threads_reply_control: 'mentioned_only',
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.photos(
    "my-brand", ["threads"], ["photo1.jpg", "photo2.jpg"],
    alt_texts=["Fog over the harbour", "A heron on the pier"],
    extra={
        "threads_title": "Two shots from this morning's walk",
        "threads_topic_tag": "Photography",
        "threads_reply_control": "mentioned_only",
    },
)
```

## Fields

| Field | Type | Values | What it does |
| --- | --- | --- | --- |
| `threads_title` | string | up to 500 characters | The post text. Falls back to `title`. Longer text is cut. |
| `threads_topic_tag` | string | | A topic for the post, shown as its tag. |
| `threads_reply_control` | string | `everyone`, `accounts_you_follow`, `mentioned_only` | Who can reply. Leave it out for everyone. |
| `threads_is_made_with_ai` | boolean | default `false` | Adds Threads' AI label. `is_ai_generated` works too. |
| `threads_alt_text` | string or list | up to 1,000 characters each | Photo alt text: one for every photo, or one per photo in order. Falls back to `alt_text`. |
| `threads_first_comment` | string | up to 500 characters | A reply posted under the new post. Falls back to `first_comment`. |
| `threads_reply_to_id` | string | a Threads post id | Posts this as a reply to that post. |
| `threads_quote_post_id` | string | a Threads post id | Quotes that post. |
| `threads_link_attachment` | string | a URL | Text posts: shows the link as a preview card. Ignored on posts with media. |
| `threads_poll_options` | list | 2 to 4 options | Text posts: adds a poll. Each option is cut to 25 characters. Send repeated fields, a JSON array or one comma-separated string. |

A poll on a video or photo post is left out with a warning, since Threads takes polls on text posts only. Fewer than 2 or more than 4 options fails the post with `invalid_poll`.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "my-brand",
    "platform": ["threads"],
    "title": "Coffee or tea while you work?",
    "threads_poll_options": ["Coffee", "Tea", "Neither"]
  }'
```

## Limits

- **Text:** 500 characters. Longer text is cut, not threaded.
- **Carousel:** up to 20 items; with more, the first 20 are used and the result says so.
- **Video size:** your plan's upload limit (see [Plans and limits](/limits/plans)).
- **Shapes:** 4:5 and 9:16 work best.

## Good to know

- **Result extras:** `container_id` (the Threads media container).
- **First comment:** posted as a reply to the new post.
- **Analytics:** when your Reelspan workspace has Threads statistics turned on, the account's views, likes, replies, reposts and quotes over the last 30 days, and followers (Threads shares the follower count only for profiles with at least 100 followers); per post, views, likes, replies, reposts, quotes and shares. An account connected before statistics were turned on has to be reconnected.

## After posting

- **Repost** a post (yours or any public one) from the account with [Repost](/api/repost).
- Threads posts can't be deleted or edited through Reelspan: the Threads API doesn't allow edits, and deleting needs a permission Reelspan doesn't hold.
- Threads lets an account publish 250 posts and 1,000 replies in 24 hours. [Publishing limits](/api/publishing-limits) shows how much is left.

## Errors

| `error_code` | What happened | What to do |
| --- | --- | --- |
| `threads_processing_failed` | Threads couldn't process the media | Read `error`; check the file and post again. |
| `threads_processing_timeout` | Threads took more than 10 minutes | Reelspan retries it; check Threads before posting again. |
| `threads_error` | Threads refused the request | Read `error` for Threads' message. |
| `invalid_poll` | `threads_poll_options` has fewer than 2 or more than 4 options | Send 2 to 4 options. |
| `media_required` | A video or photo post arrived without media | Send the media, or post with [`POST /v1/posts/text`](/api/post-text). |
| `reauth_required` | The sign-in expired or was revoked | Reconnect Threads. |

Source: https://docs.reelspan.com/networks/threads

---

# Post to LinkedIn

> Publish LinkedIn posts through the API, as text, video, up to 20 images or a document carousel (PDF, PowerPoint, Word), with visibility and reshare settings.

Reelspan posts to LinkedIn with LinkedIn's Posts, Videos, Images and Documents APIs, as the member who connected the account. You send the post once; Reelspan uploads the media, waits for LinkedIn to process it, and creates the post.

## What you can post

| Post | How | Notes |
| --- | --- | --- |
| Text post | [`POST /v1/posts/text`](/api/post-text) | Up to 3,000 characters |
| Video post | [`POST /v1/posts/video`](/api/post-video) | |
| Image post | [`POST /v1/posts/photos`](/api/post-photos) | One image, or up to 20 in a multi-image post |
| Document | [`POST /v1/posts/document`](/api/post-document) | A PDF, PowerPoint or Word file shown as a swipeable carousel |

Reelspan handles for you:

- **LinkedIn's text format.** LinkedIn treats characters such as `( ) [ ] { } < > @ * _ ~ |` as markup; Reelspan escapes them so your text shows as written, and turns `#hashtags` into real LinkedIn hashtags.
- **Multipart video upload** in the parts LinkedIn asks for, then a wait while LinkedIn processes the video (up to 15 minutes) or document (up to 10 minutes).
- **Images in parallel,** kept in the order you sent them.

## Connect the account

LinkedIn connects with a LinkedIn sign-in: in the dashboard go to **Accounts → LinkedIn**, or send a [white-label connect link](/white-label). Posts go to the personal profile of the member who signed in.

LinkedIn sign-ins last 60 days and LinkedIn gives no way to renew them, so the account has to be reconnected every 60 days. Reelspan marks it as needing a reconnect when it expires.

### Company pages

Posting as a LinkedIn company page needs LinkedIn's Community Management API, which Reelspan doesn't have access to yet. Until it does, `GET /v1/linkedin/pages` returns an empty list and posts go to the member's profile.

```bash title="cURL"
curl "https://api.reelspan.com/v1/linkedin/pages?profile=my-brand" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const { pages } = await reelspan.request('GET', '/v1/linkedin/pages', { query: { profile: 'my-brand' } });
```

```python title="Python"
pages = reelspan.request("GET", "/v1/linkedin/pages", query={"profile": "my-brand"})["pages"]
```

```json
{ "success": true, "pages": [] }
```

## Example

A PDF posted as a document carousel, visible to connections only:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/document \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=linkedin" \
  -F "title=2026 hiring guide" \
  -F "description=We put everything we learned about hiring engineers into 12 slides. #hiring #engineering" \
  -F "visibility=CONNECTIONS" \
  -F "document=@guide.pdf"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.document({
  user: 'my-brand',
  platforms: ['linkedin'],
  title: '2026 hiring guide',
  description: 'We put everything we learned about hiring engineers into 12 slides. #hiring #engineering',
  document: { data: await readFile('guide.pdf'), name: 'guide.pdf', type: 'application/pdf' },
  extra: { visibility: 'CONNECTIONS' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.document(
    "my-brand", "guide.pdf", "2026 hiring guide",
    description="We put everything we learned about hiring engineers into 12 slides. #hiring #engineering",
    extra={"visibility": "CONNECTIONS"},
)
```

## Fields

| Field | Type | Values | What it does |
| --- | --- | --- | --- |
| `linkedin_title` | string | up to 3,000 characters | The post text when there is no description. Falls back to `title`. On a video post it is also the video's title (first 400 characters). |
| `linkedin_description` | string | up to 3,000 characters | The post text; takes the place of `linkedin_title` when both are sent. Falls back to `description`. |
| `visibility` | string | `PUBLIC` (default), `CONNECTIONS`, `LOGGED_IN` | Who can see the post. `linkedin_visibility` works too. |
| `linkedin_disable_reshare` | boolean | default `false` | Stops others from resharing the post. |
| `document_title` | string | up to 400 characters | Documents: the document's title. Falls back to `title`, then the file name. |
| `linkedin_alt_text` | string or list | up to 4,086 characters each | Image alt text: one for every image, or one per image in order. Falls back to `alt_text`. |
| `target_linkedin_page_id` | string | an organization id | Posts as a company page. Not usable until company pages are available (see above). |
| `linkedin_first_comment` | string | up to 1,250 characters | A comment posted under the new post. Falls back to `first_comment`. |

On a document post, `title` names the document and the post text comes from `description` (or `linkedin_description`). The first two lines of the text show before "see more", so lead with the hook.

## Limits

- **Post text:** 3,000 characters.
- **Images:** up to 20 per post; more are left out.
- **Documents:** PDF, PPTX, PPT, DOCX or DOC, up to 100 MB.
- **Video size:** your plan's upload limit (see [Plans and limits](/limits/plans)).
- **Shapes:** 1:1 and 16:9 work best.

## Good to know

- **Result extras:** `video_urn`, `image_urns`, or `document_urn` with `content_type`, `file_size` and `filename`.
- **First comment:** posted under the new post as the member.
- **Analytics:** the member's follower count, when your Reelspan workspace has LinkedIn statistics turned on (an account connected before that has to be reconnected). There are no per-post numbers.

## Errors

| `error_code` | What happened | What to do |
| --- | --- | --- |
| `reauth_required` | The 60-day sign-in expired or was revoked | Reconnect LinkedIn. |
| `linkedin_upload_failed` | LinkedIn refused an uploaded part of the video, image or document | Reelspan retries server errors; otherwise post again. |
| `linkedin_processing_failed` | LinkedIn couldn't process the video or document | Check the file and post again. |
| `linkedin_processing_timeout` | LinkedIn took more than 15 minutes (10 for documents) | Reelspan retries it. |
| `linkedin_version_sunset` | LinkedIn stopped accepting the API version Reelspan uses | Contact Reelspan support. |
| `linkedin_error` | LinkedIn refused the post | Read `error` for LinkedIn's message. |
| `media_required` | A video or photo post arrived without media | Send the media, or post with [`POST /v1/posts/text`](/api/post-text). |

Source: https://docs.reelspan.com/networks/linkedin

---

# Post to Pinterest

> Create Pinterest video, image and carousel Pins through the API on the board and section you choose, save Pins to boards, and edit or delete them.

Reelspan creates Pins with the Pinterest API v5. You send the media once with a board; Reelspan uploads it, waits for Pinterest to process a video, and creates the Pin with its title, description and link.

## What you can post

| Post | How | Notes |
| --- | --- | --- |
| Video Pin | [`POST /v1/posts/video`](/api/post-video) | Needs a cover: an image or a frame of the video |
| Image Pin | [`POST /v1/posts/photos`](/api/post-photos) with one photo | |
| Carousel Pin | [`POST /v1/posts/photos`](/api/post-photos) with 2 to 5 photos | |

Pinterest has no text-only Pins. Reelspan handles for you:

- **The video upload:** Reelspan registers the video with Pinterest, uploads it, and waits until Pinterest has processed it (up to 10 minutes) before making the Pin.
- **The cover:** a video Pin needs one. Reelspan uses your cover image if you send one, otherwise a frame of the video (1 second in, unless you pick another).
- **Boards and sections:** list the account's boards and their sections, or create them, through the API.

## Connect the account

Pinterest connects with a Pinterest sign-in: in the dashboard go to **Accounts → Pinterest**, or send a [white-label connect link](/white-label). Any Pinterest account works.

## Pick a board

Every Pin goes to a board, so a Pinterest post needs `pinterest_board_id`. List the boards to find the id:

```bash title="cURL"
curl "https://api.reelspan.com/v1/pinterest/boards?profile=my-brand" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const { boards } = await reelspan.request('GET', '/v1/pinterest/boards', { query: { profile: 'my-brand' } });
```

```python title="Python"
boards = reelspan.request("GET", "/v1/pinterest/boards", query={"profile": "my-brand"})["boards"]
```

```json
{
  "success": true,
  "boards": [
    { "id": "1029876543210987654", "name": "Spring recipes" },
    { "id": "1029876543210987655", "name": "Kitchen ideas" }
  ],
  "pinterest_account_used": "mybrand"
}
```

The list is read live from Pinterest, so boards made in the Pinterest app show up. If Pinterest doesn't answer, you get the list saved when the account was connected.

To make a new board, send its name (up to 50 characters), and optionally a `description` (up to 500 characters) and `privacy`: `PUBLIC` (the default) or `PROTECTED`. A protected board is hidden from others but can still be posted to; secret boards can't be posted to, so `SECRET` isn't one of the choices.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/pinterest/boards \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile": "my-brand", "name": "Weeknight dinners"}'
```

```javascript title="Node.js"
const { board } = await reelspan.pinterest.createBoard('my-brand', 'Weeknight dinners');
```

```python title="Python"
board = reelspan.pinterest.create_board("my-brand", "Weeknight dinners")["board"]
```

With a description and privacy (the SDKs' `createBoard` / `create_board` take a name only, so use `request`):

```javascript title="Node.js"
await reelspan.request('POST', '/v1/pinterest/boards', {
  json: { profile: 'my-brand', name: 'Drafts', description: 'Pins waiting for review', privacy: 'PROTECTED' },
});
```

```python title="Python"
reelspan.request("POST", "/v1/pinterest/boards", json_body={"profile": "my-brand", "name": "Drafts", "description": "Pins waiting for review", "privacy": "PROTECTED"})
```

### Board sections

A board can be split into sections; send a section's id as `pinterest_board_section_id` to put the Pin there. List a board's sections, read live from Pinterest:

```bash title="cURL"
curl "https://api.reelspan.com/v1/pinterest/boards/1029876543210987654/sections?profile=my-brand" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const { sections } = await reelspan.request('GET', '/v1/pinterest/boards/1029876543210987654/sections', { query: { profile: 'my-brand' } });
```

```python title="Python"
sections = reelspan.request("GET", "/v1/pinterest/boards/1029876543210987654/sections", query={"profile": "my-brand"})["sections"]
```

```json
{ "success": true, "board_id": "1029876543210987654", "sections": [{ "id": "5012345678901234567", "name": "Pasta" }] }
```

Create one with a `POST` to the same path and a `name` (up to 180 characters); the answer is **201** with the new `section`. Creating a section needs the `publish` scope.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/pinterest/boards/1029876543210987654/sections \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile": "my-brand", "name": "Soups"}'
```

## Example

A video Pin with a link and a cover picked 3 seconds in:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=pinterest" \
  -F "pinterest_board_id=1029876543210987654" \
  -F "pinterest_title=15-minute lemon pasta" \
  -F "pinterest_description=A weeknight pasta with lemon, garlic and parmesan. Full recipe on the blog." \
  -F "pinterest_link=https://example.com/lemon-pasta" \
  -F "pinterest_cover_image_key_frame_time=3" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['pinterest'],
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: {
    pinterest_board_id: '1029876543210987654',
    pinterest_title: '15-minute lemon pasta',
    pinterest_description: 'A weeknight pasta with lemon, garlic and parmesan. Full recipe on the blog.',
    pinterest_link: 'https://example.com/lemon-pasta',
    pinterest_cover_image_key_frame_time: 3,
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["pinterest"], "launch.mp4",
    extra={
        "pinterest_board_id": "1029876543210987654",
        "pinterest_title": "15-minute lemon pasta",
        "pinterest_description": "A weeknight pasta with lemon, garlic and parmesan. Full recipe on the blog.",
        "pinterest_link": "https://example.com/lemon-pasta",
        "pinterest_cover_image_key_frame_time": 3,
    },
)
```

## Fields

| Field | Type | Values | What it does |
| --- | --- | --- | --- |
| `pinterest_board_id` | string | a board id | Required. The board the Pin goes to. |
| `pinterest_board_section_id` | string | a section id | A section of that board. |
| `pinterest_title` | string | up to 100 characters | The Pin's title. Falls back to `title`. |
| `pinterest_description` | string | up to 800 characters | The Pin's description (the API takes 800; the Pinterest app shows about 500 before "more"). Falls back to `description` (not to `title`). |
| `pinterest_link` | string | URL | Where the Pin leads when tapped. |
| `pinterest_cover_image_url` | string | public image URL | Video Pins: the cover image. You can also send a `cover` file, `cover_url` or `cover_media_id`. |
| `pinterest_cover_image_key_frame_time` | number | seconds, default `1` | Video Pins without a cover image: the frame used as the cover. |
| `pinterest_carousel_index` | number | 0-based, default `0` | Carousel Pins: passed to Pinterest as the carousel's `index`. |
| `pinterest_alt_text` | string | up to 500 characters | Alt text for the Pin (the first image's, on a carousel). Falls back to `alt_text`. |

## Limits

- **Title:** 100 characters. **Description:** 800 characters (longer is cut).
- **Carousel:** 2 to 5 photos, all in the same shape; with more, the first 5 are used and the result says so.
- **Photos:** JPEG or PNG, up to 20 MB each.
- **Video size:** your plan's upload limit (see [Plans and limits](/limits/plans)).
- **Shapes:** 2:3 and 9:16 work best.

## Save a Pin to a board

`POST /v1/posts/save` saves (repins) an existing Pin, yours or anyone's, to one of the account's boards, optionally into a section:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/save \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user": "my-brand", "post_id": "987654321098765432", "pinterest_board_id": "1029876543210987654", "pinterest_board_section_id": "5012345678901234567"}'
```

```javascript title="Node.js"
await reelspan.request('POST', '/v1/posts/save', {
  json: { user: 'my-brand', post_id: '987654321098765432', pinterest_board_id: '1029876543210987654' },
});
```

```python title="Python"
reelspan.request("POST", "/v1/posts/save", json_body={"user": "my-brand", "post_id": "987654321098765432", "pinterest_board_id": "1029876543210987654"})
```

```json
{
  "success": true,
  "post_id": "1122334455667788990",
  "url": "https://www.pinterest.com/pin/1122334455667788990/",
  "board_id": "1029876543210987654",
  "board_section_id": "5012345678901234567",
  "parent_pin_id": "987654321098765432"
}
```

`post_id` in the answer is the new saved Pin; `parent_pin_id` is the one you saved.

## After posting

- **Delete** a Pin with [Unpublish](/api/unpublish).
- **Edit** a Pin with [Edit a post](/api/edit-post): `title` (up to 100 characters), `description` or `text` (up to 800), and in `fields` the `pinterest_link`, `pinterest_alt_text` (up to 500), `pinterest_board_id` and `pinterest_board_section_id` (to move it). The image or video can't change.

## Good to know

- **Trial access.** While Reelspan's Pinterest app is on Pinterest's Trial access, Pins are made in Pinterest's sandbox and only you can see them; the result says so in `warnings`.
- **Pinterest's filters.** Pinterest blocks Pins whose words touch topics it treats as spam or unsafe (hacking, passwords, crypto, giveaways) or that link to a blocked site. That fails with `pinterest_blocked_content`; retrying the same text won't help.
- **Result extras:** `board_id`, and `media_id` for video Pins.
- **First comment:** Pinterest's API has no comments, so `first_comment` isn't posted; the result says `first_comment: "unsupported"`.
- **Analytics:** followers, following, Pin count and monthly views for the account. There are no per-Pin numbers.

## Errors

| `error_code` | What happened | What to do |
| --- | --- | --- |
| `pinterest_blocked_content` | Pinterest's spam and safety filter blocked the Pin | Change the title, description or link, then retry. |
| `pinterest_upload_failed` | The video upload to Pinterest failed | Reelspan retries server errors; otherwise post again. |
| `pinterest_processing_failed` | Pinterest couldn't process the video | Check the file and post again. |
| `pinterest_processing_timeout` | Pinterest took more than 10 minutes | Reelspan retries it. |
| `pinterest_error` | Pinterest refused the request, for example an unknown board | Read `error` for Pinterest's message. |
| `reauth_required` | The sign-in expired, or the connection predates a permission Reelspan now needs | Reconnect Pinterest. |
| `media_required` | The post had no photo or video | Send media: Pinterest has no text Pins. |

A request that names Pinterest without a board is refused with 400 before anything is uploaded.

Source: https://docs.reelspan.com/networks/pinterest

---

# Post to Bluesky

> Post to Bluesky through the API with videos, up to 4 images or text, as threads, replies or quotes, with labels, reply and quote controls, and reposts.

Reelspan posts to Bluesky through the AT Protocol, signed in with an app password. You send the post once; Reelspan uploads the media, sends videos through Bluesky's video service so they play, and creates the post. Text longer than 300 characters becomes a thread.

## What you can post

| Post | How | Notes |
| --- | --- | --- |
| Video post | [`POST /v1/posts/video`](/api/post-video) | Up to 100 MB, or compressed for you |
| Image post | [`POST /v1/posts/photos`](/api/post-photos) | Up to 4 images |
| Text post | [`POST /v1/posts/text`](/api/post-text) | |
| Thread | Any of the above with long text | Split at 300 characters |

Reelspan handles for you:

- **Video processing.** Videos go through Bluesky's video service, which transcodes them for playback; Reelspan waits until it is done (up to 10 minutes). The player gets the video's real aspect ratio.
- **Image size.** Bluesky takes images up to 1 MB. Larger images, and formats other than JPEG, PNG and WebP, are re-encoded as JPEG under 1 MB.
- **Clickable links and hashtags.** URLs and `#hashtags` in the text are turned into links and tags.
- **Threads.** Text over 300 characters is split on paragraph breaks, then lines, then words. The first post carries the media; each next post replies to the one before.

## Connect the account

Bluesky connects with your handle and an **app password**, never your main password.

1. In Bluesky, open **Settings → Privacy and security → App passwords** and create one. It looks like `xxxx-xxxx-xxxx-xxxx`.
2. In Reelspan, go to **Accounts → Bluesky** and enter your handle (or email) and the app password, or connect through the API with [Connect with credentials](/api/connect-credentials):

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/bluesky \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "identifier": "mybrand.bsky.social", "app_password": "abcd-efgh-ijkl-mnop"}'
```

```javascript title="Node.js"
await reelspan.request('POST', '/v1/accounts/bluesky', {
  json: { profile_username: 'my-brand', identifier: 'mybrand.bsky.social', app_password: 'abcd-efgh-ijkl-mnop' },
});
```

```python title="Python"
reelspan.accounts.connect("my-brand", "bluesky", identifier="mybrand.bsky.social", app_password="abcd-efgh-ijkl-mnop")
```

Reelspan checks the app password with Bluesky before saving it, encrypted. To post videos, the Bluesky account's email address must be confirmed.

## Example

A video post in English and German, compressed if it is over 100 MB:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=bluesky" \
  -F "bluesky_title=Our new studio, in one take. https://example.com/studio #design" \
  -F "bluesky_langs=en,de" \
  -F "bluesky_compress=true" \
  -F "bluesky_alt_text=A walk through a bright studio with plants and desks" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['bluesky'],
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: {
    bluesky_title: 'Our new studio, in one take. https://example.com/studio #design',
    bluesky_langs: 'en,de',
    bluesky_compress: true,
    bluesky_alt_text: 'A walk through a bright studio with plants and desks',
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["bluesky"], "launch.mp4",
    extra={
        "bluesky_title": "Our new studio, in one take. https://example.com/studio #design",
        "bluesky_langs": "en,de",
        "bluesky_compress": True,
        "bluesky_alt_text": "A walk through a bright studio with plants and desks",
    },
)
```

## Fields

| Field | Type | Values | What it does |
| --- | --- | --- | --- |
| `bluesky_title` | string | any length | The post text. Falls back to `title`. Over 300 characters it becomes a thread. |
| `bluesky_langs` | string | language codes separated by commas, up to 3 | The post's languages, e.g. `en,de`. |
| `bluesky_compress` | boolean | default `false` | Videos over 100 MB: compress them so Bluesky takes them, instead of failing. |
| `bluesky_alt_text` | string or list | up to 1,000 characters each | Alt text: for the video, or for each image (one for every image, or one per image in order). Falls back to `alt_text`. |
| `bluesky_first_comment` | string | up to 300 characters | A reply posted under the new post. Falls back to `first_comment`. |
| `bluesky_reply_to_id` | string | an `at://` post URI | Posts this as a reply to that post, in its thread. |
| `bluesky_quote_uri` | string | an `at://` post URI | Quotes that post, with or without media of your own. |
| `bluesky_labels` | string | `sexual`, `nudity`, `porn`, `graphic-media`, separated by commas | Content warnings on the post. Other values are ignored. |
| `bluesky_threadgate` | string | `nobody`, or any of `mention`, `following`, `followers` separated by commas | Who can reply. Leave it out for everyone. |
| `bluesky_postgate` | string | `no_quotes` | Nobody can quote the post. |

A reply or quote to a post Bluesky can't find fails with `bluesky_post_not_found`. If Bluesky doesn't take the reply or quote setting, the post still goes out, with a warning.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "my-brand",
    "platform": ["bluesky"],
    "title": "This is the best write-up of the launch so far.",
    "bluesky_quote_uri": "at://did:plc:abc123/app.bsky.feed.post/3kxyz",
    "bluesky_threadgate": "following"
  }'
```

## Limits

- **Post:** 300 characters (counted as people see them: an emoji is one). Longer text becomes a thread.
- **Video:** up to 100 MB. Bigger videos fail unless you send `bluesky_compress=true`; then Reelspan re-encodes them (H.264, at most 1080p) to fit.
- **Images:** up to 4 per post, 1 MB each after re-encoding. With more, the first 4 are used and the result says so.
- **Shapes:** 16:9 works best; other shapes keep their own ratio.

## Good to know

- **Confirmed email for video.** Bluesky only takes videos from accounts with a confirmed email, and has a daily video limit per account. Reelspan checks both before uploading.
- **No link cards.** Links are clickable in the text, but no preview card is attached.
- **A thread that stops halfway** keeps the posts already made: the result is a success with a warning saying where it stopped.
- **Result extras:** `cid` (the post's content id). `post_id` is the post's `at://` URI.
- **First comment:** posted as a reply to the new post.
- **Analytics:** followers, following and post count for the account; likes, reposts, replies and quotes per post.

## After posting

- **Delete** a post with [Unpublish](/api/unpublish). Only the connected account's own posts can be deleted.
- **Repost** any post from the account with [Repost](/api/repost).
- Bluesky posts can't be edited.

For both, `post_id` can be the post's `at://` URI or its `bsky.app/profile/…/post/…` link.

## Errors

| `error_code` | What happened | What to do |
| --- | --- | --- |
| `bluesky_email_unconfirmed` | The account's email isn't confirmed, so Bluesky refuses videos | In Bluesky open Settings → Account, confirm the email, then retry. |
| `bluesky_video_limit` | The account used up Bluesky's daily video limit | Retry tomorrow. |
| `bluesky_video_too_large` | The video is over 100 MB (and `bluesky_compress` wasn't set, or it is still too big after compressing) | Retry with `bluesky_compress=true`, or send a smaller file. |
| `bluesky_upload_failed` | Bluesky refused the video or image upload | Read `error`; Reelspan retries server errors. |
| `bluesky_processing_failed` | Bluesky's video service couldn't process the video | Check the file and post again. |
| `bluesky_processing_timeout` | Bluesky took more than 10 minutes | Reelspan retries it. |
| `bluesky_error` | Bluesky refused the post | Read `error` for Bluesky's message. |
| `bluesky_post_not_found` | The post in `bluesky_reply_to_id` or `bluesky_quote_uri` doesn't exist | Check the `at://` URI. |
| `reauth_required` | The handle or app password no longer works (for example the app password was revoked) | Create a new app password and connect again. |
| `invalid_app_password` | When connecting: the password isn't in app-password format | Create an app password in Bluesky and use that. |

Source: https://docs.reelspan.com/networks/bluesky

---

# Post to Reddit

> Submit video, image and text posts to a subreddit through the API, with a title, flair, NSFW and spoiler tags, and list the account's posts with their scores.

Reelspan submits posts to Reddit with Reddit's API, as the account you connect. You name the subreddit; Reelspan uploads the media to Reddit, submits the post and returns its link.

## What you can post

| Post | How | Notes |
| --- | --- | --- |
| Text post | [`POST /v1/posts/text`](/api/post-text) | A title and a body |
| Image post | [`POST /v1/posts/photos`](/api/post-photos) | One image |
| Video post | [`POST /v1/posts/video`](/api/post-video) | With a poster image |

Reelspan handles for you:

- **Uploads to Reddit.** Images and videos go to Reddit's own media storage first, as Reddit requires.
- **The video poster.** Reddit wants a poster image for a video: Reelspan uses your cover image, or takes a frame from the video.
- **Finding the post.** Reddit processes image and video posts before they appear. Reelspan looks for the new post on the account for about 30 seconds so it can return the link.

## Connect the account

Reddit connects with a Reddit sign-in: in the dashboard go to **Accounts → Reddit**, or send a [white-label connect link](/white-label).

> [!NOTE]
> Reddit posting needs a Reddit developer app on Reelspan's side. Until it is set up, connecting Reddit fails with a message saying Reddit isn't set up yet, so Reddit may not be available to you yet.

Read the subreddit's rules before posting: many remove self-promotion, require a flair, or limit new accounts.

## Example

A video post in r/videos with a flair:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=reddit" \
  -F "reddit_subreddit=videos" \
  -F "reddit_title=I timed every step of making espresso by hand" \
  -F "reddit_flair_id=a1b2c3d4-0000-1111-2222-333344445555" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['reddit'],
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: {
    reddit_subreddit: 'videos',
    reddit_title: 'I timed every step of making espresso by hand',
    reddit_flair_id: 'a1b2c3d4-0000-1111-2222-333344445555',
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["reddit"], "launch.mp4",
    extra={
        "reddit_subreddit": "videos",
        "reddit_title": "I timed every step of making espresso by hand",
        "reddit_flair_id": "a1b2c3d4-0000-1111-2222-333344445555",
    },
)
```

A text post uses `reddit_title` for the title and `reddit_description` for the body:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user": "my-brand", "platform": ["reddit"], "title": "What we learned shipping 100 releases", "reddit_subreddit": "devops", "reddit_description": "A few notes from five years of weekly releases…"}'
```

```javascript title="Node.js"
await reelspan.posts.text({
  user: 'my-brand',
  platforms: ['reddit'],
  title: 'What we learned shipping 100 releases',
  extra: { reddit_subreddit: 'devops', reddit_description: 'A few notes from five years of weekly releases…' },
});
```

```python title="Python"
reelspan.posts.text(
    "my-brand", ["reddit"], "What we learned shipping 100 releases",
    extra={"reddit_subreddit": "devops", "reddit_description": "A few notes from five years of weekly releases…"},
)
```

## Fields

| Field | Type | Values | What it does |
| --- | --- | --- | --- |
| `reddit_subreddit` | string | a subreddit name, e.g. `videos` | Required. Where to post. A leading `r/` is removed. `subreddit` works too. |
| `reddit_title` | string | up to 300 characters | The post's title. Without it, the first line of `title` is used. |
| `reddit_description` | string | up to 40,000 characters | Text posts: the body. Without it, the body is `reddit_title` or `title`. |
| `reddit_flair_id` | string | a flair template id | The post's flair. Some subreddits require one. |
| `reddit_nsfw` | boolean | default `false` | Marks the post NSFW. |
| `reddit_spoiler` | boolean | default `false` | Marks the post as a spoiler. |
| `reddit_first_comment` | string | | A comment posted under the new post. Falls back to `first_comment`. |

A request that names Reddit without a subreddit is refused with 400 before anything is uploaded.

## Limits

- **Title:** 300 characters. **Body:** 40,000 characters.
- **Images:** one per post; only the first photo is used.
- **Media size:** your plan's upload limit, and at most 1 GB.

## List the account's posts

`GET /v1/reddit/posts?profile=my-brand` lists the account's Reddit posts with their score, comment count, views and media:

```bash title="cURL"
curl "https://api.reelspan.com/v1/reddit/posts?profile=my-brand&limit=25"   -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const { posts, after } = await reelspan.request('GET', '/v1/reddit/posts', { query: { profile: 'my-brand', limit: 25 } });
```

```python title="Python"
page = reelspan.request("GET", "/v1/reddit/posts", query={"profile": "my-brand", "limit": 25})
```

```json
{
  "success": true,
  "source": "reelspan",
  "posts": [
    {
      "id": "1h2k3m4",
      "title": "We built a tiny studio in a shipping container",
      "subreddit": "InteriorDesign",
      "body": "",
      "likes": 412,
      "upvote_ratio": 0.97,
      "comments": 38,
      "impressions": null,
      "has_image": true,
      "has_video": false,
      "nsfw": false,
      "media": [{ "type": "image", "url": "https://i.redd.it/…", "width": 1920, "height": 1080 }],
      "url": "https://www.reddit.com/r/InteriorDesign/comments/1h2k3m4/…",
      "created_at": "2026-11-02T14:05:11.000Z",
      "thumbnail": "https://b.thumbs.redditmedia.com/…"
    }
  ],
  "after": null
}
```

- `source` says where the list came from. With `account`, it is every post the account submitted, newest first, and you page with `limit` (1 to 100, default 25) and the `after` value from the previous answer. When Reddit won't list the account's own submissions to Reelspan, the answer is `reelspan`: the posts Reelspan published for this profile, with their current numbers, and `after` is `null`.
- `likes` is the post's score. `impressions` is the view count, which Reddit shares with only some apps; otherwise `null`.
- `media` lists images (galleries too), Reddit-hosted videos, and embedded videos from other sites (`external_video`).

Reddit posts can't be edited, deleted or reposted through Reelspan.

## Good to know

- **Slow processing.** If Reddit hasn't shown the image or video post after about 30 seconds, the result links to the subreddit's new posts, has no `post_id`, and says Reddit is still processing. A first comment can't be posted in that case.
- **Same link twice.** Reelspan allows resubmitting a link Reddit has seen before, and turns on reply notifications for the post.
- **First comment:** posted under the new post as the account.
- **Analytics:** per post, upvotes (`likes`), comments and score. There are no account numbers.

## Errors

| `error_code` | What happened | What to do |
| --- | --- | --- |
| `subreddit_not_found` | The subreddit doesn't exist | Check the name in `reddit_subreddit`. |
| `reddit_error` | Reddit refused the post: a missing flair, a subreddit rule, a rate limit, or a banned account; `error` carries Reddit's message and code | Read `error`. A rate limit (`RATELIMIT`) is retried automatically. |
| `reauth_required` | The sign-in expired or was revoked | Reconnect Reddit. |

Source: https://docs.reelspan.com/networks/reddit

---

# Post to Google Business

> Publish updates, events and offers to your Google Business Profile through the API, with a photo, a button, and the location you choose.

Reelspan publishes updates, events and offers (Google's "local posts") to a Google Business Profile location. You send the text and, if you like, a photo; Reelspan creates the post with an optional button and returns its link on Google.

## What you can post

| Post | How | Notes |
| --- | --- | --- |
| Text update | [`POST /v1/posts/text`](/api/post-text) | Up to 1,500 characters |
| Update with a photo | [`POST /v1/posts/photos`](/api/post-photos) | One photo |

A post is a standard "What's new" update unless you make it an [event or an offer](#events-and-offers) with `gbp_topic_type`. Videos and photos for the profile's gallery aren't supported. Reelspan handles for you:

- **The photo.** Google fetches it from a short-lived signed link while the update is made.
- **The button.** Add a call-to-action button with a link, such as "Book" or "Order online".

## Connect the account

Google Business connects with a Google sign-in: in the dashboard go to **Accounts → Google Business**, or send a [white-label connect link](/white-label). Sign in with a Google account that manages the Business Profile.

> [!NOTE]
> Google Business posting needs a Google Cloud project on Reelspan's side with Google's Business Profile APIs approved. Until it is set up, connecting fails with a message saying Google Business isn't set up yet, so it may not be available to you yet.

## Choose the location

When you connect, the account's first location becomes the one posts go to. List the locations, with the chosen one marked, with `GET /v1/google-business/locations`:

```bash title="cURL"
curl "https://api.reelspan.com/v1/google-business/locations?profile=my-brand" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const { locations } = await reelspan.request('GET', '/v1/google-business/locations', { query: { profile: 'my-brand' } });
```

```python title="Python"
locations = reelspan.request("GET", "/v1/google-business/locations", query={"profile": "my-brand"})["locations"]
```

```json
{
  "success": true,
  "locations": [
    { "id": "accounts/1122334455/locations/998877", "name": "locations/998877", "title": "My Brand Soho", "account_id": "accounts/1122334455", "selected": true },
    { "id": "accounts/1122334455/locations/998878", "name": "locations/998878", "title": "My Brand Camden", "account_id": "accounts/1122334455", "selected": false }
  ],
  "selected_location_id": "accounts/1122334455/locations/998877",
  "selected_location_name": "My Brand Soho"
}
```

The list is the one saved when the account was connected. Add `refresh=true` to read it again from Google (and save it), for example after adding a location; if the chosen location is gone, the choice is cleared.

To send posts to another location, choose it with `POST /v1/google-business/location` (needs the `profiles` scope). `location_id` can be the full id, `locations/…`, or the bare number:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/google-business/location \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile": "my-brand", "location_id": "998878"}'
```

```json
{ "success": true, "location_id": "accounts/1122334455/locations/998878", "location_name": "My Brand Camden" }
```

A location that isn't on the account gets **404** `location_not_found`, with the available ones in the message. `DELETE /v1/google-business/location` with `{"profile": "my-brand"}` clears the choice: then each post needs `google_business_location_id`, unless the account has one location.

To post to another location just once, send it in `google_business_location_id` on the post, in any of the same three forms.

## Example

An update with a photo and a "Book" button:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/photos \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=google_business" \
  -F "google_business_title=Spring menu is here: wild garlic risotto and rhubarb tart, from this Friday." \
  -F "google_business_cta=BOOK" \
  -F "google_business_cta_url=https://example.com/book" \
  -F "photos[]=@photo1.jpg"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.photos({
  user: 'my-brand',
  platforms: ['google_business'],
  photos: [{ data: await readFile('photo1.jpg'), name: 'photo1.jpg', type: 'image/jpeg' }],
  extra: {
    google_business_title: 'Spring menu is here: wild garlic risotto and rhubarb tart, from this Friday.',
    google_business_cta: 'BOOK',
    google_business_cta_url: 'https://example.com/book',
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.photos(
    "my-brand", ["google_business"], ["photo1.jpg"],
    extra={
        "google_business_title": "Spring menu is here: wild garlic risotto and rhubarb tart, from this Friday.",
        "google_business_cta": "BOOK",
        "google_business_cta_url": "https://example.com/book",
    },
)
```

The network's id in `platform[]` is `google_business`.

## Fields

| Field | Type | Values | What it does |
| --- | --- | --- | --- |
| `google_business_title` | string | up to 1,500 characters | The update's text. Falls back to `title`. Longer text is cut, with a warning. |
| `google_business_cta_url` | string | URL | Adds a button that opens this link. Without it there is no button. |
| `google_business_cta` | string | `LEARN_MORE` (default), `BOOK`, `ORDER`, `SHOP`, `SIGN_UP` | The button's label: Learn more, Book, Order online, Buy, Sign up. Used only with `google_business_cta_url`. |
| `google_business_language` | string | language code, default `en` | The language of the update. |
| `google_business_location_id` | string | `accounts/…/locations/…`, `locations/…` or the bare id | The location to post to, instead of the chosen one. |
| `gbp_topic_type` | string | `STANDARD` (default), `EVENT`, `OFFER` | An update, an event or an offer. |
| `gbp_event_title` | string | up to 58 characters | Events and offers: the title. Falls back to the first line of `title`. |
| `gbp_event_start`, `gbp_event_end` | string | ISO 8601 date (`2026-12-05`) or date and time (`2026-12-05T18:00:00Z`) | Events and offers: when it runs. Both are required. A date and time is read in UTC. |
| `gbp_coupon_code` | string | | Offers: a code to show. |
| `gbp_redeem_url` | string | URL | Offers: where to redeem it online. |
| `gbp_terms` | string | | Offers: the terms and conditions. |

The `gbp_*` names from Upload-Post work for the other fields too: `gbp_location_id`, `gbp_cta_type`, `gbp_cta_url` and `gbp_language_code` do the same as `google_business_location_id`, `google_business_cta`, `google_business_cta_url` and `google_business_language`. The `google_business_*` name wins when both are sent.

## Events and offers

An event has a title and a start and end; an offer has the same plus an optional coupon code, redeem link and terms. Offers bring their own redeem link, so a call-to-action button is left off an offer.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/photos \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=google_business" \
  -F "google_business_title=20% off every tart this weekend. Show the code at the counter." \
  -F "gbp_topic_type=OFFER" \
  -F "gbp_event_title=Weekend tart sale" \
  -F "gbp_event_start=2026-12-05" \
  -F "gbp_event_end=2026-12-07" \
  -F "gbp_coupon_code=TART20" \
  -F "gbp_terms=One per customer." \
  -F "photos[]=@photo1.jpg"
```

A missing title, start or end fails the post with `event_required`, and so does a date that can't be read.

## Limits

- **Text:** 1,500 characters.
- **Photos:** one per update; with more, the first is used and the result says so.
- **Shapes:** 4:3 and 1:1 work best.

## Good to know

- **The link** in the result is the update on Google Search, when Google returns one; `post_id` is the update's full resource name.
- **First comment:** Google Business updates have no comments, so `first_comment` isn't posted; the result says `first_comment: "unsupported"`.
- **Analytics:** none for Google Business yet.

## After posting

- **Delete** an update, event or offer with [Unpublish](/api/unpublish).
- **Edit** its text, or its button with `fields.google_business_cta_url` (and `fields.google_business_cta`), with [Edit a post](/api/edit-post).

For a post made outside Reelspan, `post_id` is the post's full name: `accounts/…/locations/…/localPosts/…`.

## Errors

| `error_code` | What happened | What to do |
| --- | --- | --- |
| `location_required` | Several locations are connected and none is chosen | [Choose one](#choose-the-location), or send `google_business_location_id`. The error lists the locations. |
| `invalid_topic_type` | `gbp_topic_type` isn't `STANDARD`, `EVENT` or `OFFER` | Use one of those. |
| `event_required` | An event or offer without a title, start or end, or with a date that can't be read | Send `gbp_event_title` (or a `title`), `gbp_event_start` and `gbp_event_end`. |
| `google_business_error` | Google refused the update | Read `error` for Google's message. Reelspan retries server errors and rate limits. |
| `reauth_required` | The Google sign-in expired or was revoked | Reconnect Google Business. |

Source: https://docs.reelspan.com/networks/google-business

---

# Post to Telegram

> Publish videos, photo albums and text to a Telegram channel or group through your own bot, connected with a bot token and the chat.

Reelspan posts to a Telegram channel or group through a bot you create with @BotFather and add to the chat. Posts appear under the channel's name, as if you had sent them yourself.

## What you can post

| Post | How it appears |
| --- | --- |
| Video | A streamable video message, with the caption under it |
| Photos | One photo, or an album of up to 10. The caption sits under the first item. `photos[]` can mix photos and videos in one album |
| Text | A plain text message |

Captions under a video or photos hold 1,024 characters and text messages 4,096. Longer text is cut to fit, ending in `…`, and the result carries a warning.

A post in a public channel answers with its link (`https://t.me/yourchannel/42`). A private channel or a group has no public link, so `url` is `null`; `post_id` is the message id.

## Connect your channel

You need a bot token and the chat. Setup takes about two minutes.

1. Open [@BotFather](https://t.me/BotFather) in Telegram and send `/newbot`. Pick a name; it replies with your bot token.
2. Add the bot to your channel or group as an admin that can post messages.
3. In the dashboard, open **Accounts → Connect account**, choose the profile and Telegram, then paste the token and the chat. A public channel is its `@name`; a private one is its numeric id, which starts with `-100`.

> [!TIP]
> To find a private channel's id, forward one of its posts to @userinfobot.

Reelspan checks both with Telegram before saving: the token must be valid, the bot must see the chat, and in a channel the bot must be an admin. The token is stored encrypted.

### With the API

Send the same values to `POST /v1/accounts/telegram`. The chat can be `@name`, the numeric id, or a `https://t.me/name` link.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/telegram \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "bot_token": "123456789:AAH...", "chat": "@yourchannel"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.accounts.connect('my-brand', 'telegram', {
  bot_token: process.env.TELEGRAM_BOT_TOKEN,
  chat: '@yourchannel',
});
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.accounts.connect("my-brand", "telegram", bot_token=os.environ["TELEGRAM_BOT_TOKEN"], chat="@yourchannel")
```

```json
{ "success": true, "platform": "telegram", "account": "@yourchannel", "reconnected": false }
```

| Field | Required | Also accepted (Upload-Post) |
| --- | --- | --- |
| `bot_token` | Yes | |
| `chat` | Yes | `chat_id` |

Connecting again replaces the Telegram account on that profile. See [Connect with credentials](/api/connect-credentials) for the endpoint itself.

## Example post

A video to the channel, with its own caption for Telegram:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=telegram" \
  -F "title=Launch day" \
  -F "telegram_title=Launch day. Watch the 60-second tour, then tell us what you think." \
  -F "first_comment=Questions? Reply here." \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['telegram'],
  title: 'Launch day',
  firstComment: 'Questions? Reply here.',
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: { telegram_title: 'Launch day. Watch the 60-second tour, then tell us what you think.' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["telegram"], "launch.mp4", "Launch day",
    first_comment="Questions? Reply here.",
    extra={"telegram_title": "Launch day. Watch the 60-second tour, then tell us what you think."},
)
```

```json
{
  "success": true,
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "results": {
    "telegram": { "success": true, "url": "https://t.me/yourchannel/42", "post_id": "42", "first_comment": "posted" }
  }
}
```

## Fields

| Field | Meaning |
| --- | --- |
| `telegram_title` | The message text or caption on Telegram. Falls back to `title`. |
| `title` | The caption every network uses, when `telegram_title` isn't sent. |
| `telegram_first_comment` | Sent as a reply to the post in the same chat. Falls back to `first_comment`. |
| `first_comment` | The first comment for every network that takes one. |
| `telegram_parse_mode` | `HTML`, `MarkdownV2` or `Markdown`: how Telegram reads formatting in the text. Leave it out for plain text. |
| `telegram_disable_notification` | `true` posts silently: subscribers get no sound. |
| `telegram_protect_content` | `true` stops the post being forwarded or saved. |
| `telegram_has_spoiler` | `true` blurs the photos or video until tapped. |
| `telegram_as_document` | `true` sends the files uncompressed, as documents, instead of as photos or a playable video. |

Telegram has no options of its own in the dashboard composer.

## Limits and behaviour

- **Files:** up to 50 MB each, the most a bot may send. A larger file fails the Telegram post with `file_too_large`; other networks in the request are not affected.
- **Albums:** up to 10 items. With more photos, the first 10 are sent and the result carries a warning.
- **Text:** captions 1,024 characters, messages 4,096. Longer text is cut with a warning.
- **Formatting:** text is sent as plain text unless you set `telegram_parse_mode`. With a parse mode, the text must follow Telegram's rules for it (MarkdownV2 needs characters such as `.` and `!` escaped), or Telegram refuses the message.
- **Links:** only public channels have post links. Elsewhere `url` is `null`.

## After posting

The bot can change the messages it sent:

- **Delete** a message with [Unpublish](/api/unpublish). Telegram lets bots delete messages only for 48 hours after sending.
- **Edit** its text or caption with [Edit a post](/api/edit-post). Send `fields.telegram_parse_mode` again if the new text uses formatting.

## Common errors

| Code | When | Fix |
| --- | --- | --- |
| `INVALID_TOKEN` | Connecting: the token isn't shaped like `123456:ABC…` | Copy the whole token from @BotFather. |
| `INVALID_CHAT` | Connecting: the chat isn't `@name` or a numeric id | Use `@yourchannel`, or the `-100…` id of a private channel. |
| `BOT_NOT_ADMIN` | Connecting: the bot isn't an admin of the channel | Make the bot an admin that can post messages, then connect again. |
| `TELEGRAM_ERROR` | Telegram refused a call; the message is Telegram's own (for example "chat not found") | Check the chat, and that the bot is still in it. |
| `reauth_required` | Telegram answered 401 or 403: the token was revoked, or the bot was removed | Connect again with a working token. When connecting, this shows as `REAUTH_REQUIRED`. |
| `file_too_large` | A file is over 50 MB | Send a smaller file to Telegram. |
| `telegram_error` | Telegram refused the post. Retried automatically on 429 and 5xx | Read `error` for Telegram's reason. |
| `MISSING_FIELD` | Connecting without `bot_token` or `chat` | Send both. |

Errors when connecting come back as a 400 with the code in `error_code`. Errors when posting are in that network's result. See [Errors](/errors).

Source: https://docs.reelspan.com/networks/telegram

---

# Post to Discord

> Publish messages with videos, photos or text to a Discord channel through a channel webhook, connected by pasting its URL.

Reelspan posts to a Discord channel through a webhook you make in the channel's settings. Messages show the webhook's name and picture as the author, with the video or photos attached as files.

## What you can post

| Post | How it appears |
| --- | --- |
| Video | A message with the video attached as a file, which Discord plays inline |
| Photos | A message with up to 10 photos attached. `photos[]` can mix photos and videos |
| Text | A plain message |

Messages hold 2,000 characters. Longer text is cut to fit, ending in `…`, and the result carries a warning.

The result's `url` links to the message (`https://discord.com/channels/…`) when the webhook belongs to a server, and `post_id` is the message id.

## Connect your channel

All you need is the webhook URL. Setup takes about a minute.

1. In Discord, open the channel's settings (the gear by its name) → **Integrations → Webhooks → New Webhook**.
2. Give it the name and picture posts should show, then click **Copy Webhook URL**.
3. In the Reelspan dashboard, open **Accounts → Connect account**, choose the profile and Discord, and paste the URL.

Reelspan checks the webhook with Discord before saving it, encrypted. Only `discord.com` (and `discordapp.com`, `ptb.` and `canary.`) webhook URLs are accepted, and anything after `?` is dropped.

### With the API

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/discord \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "webhook_url": "https://discord.com/api/webhooks/123456789/abcdef..."}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.accounts.connect('my-brand', 'discord', {
  webhook_url: process.env.DISCORD_WEBHOOK_URL,
});
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.accounts.connect("my-brand", "discord", webhook_url=os.environ["DISCORD_WEBHOOK_URL"])
```

```json
{ "success": true, "platform": "discord", "account": "Reelspan", "reconnected": false }
```

`account` is the webhook's name.

| Field | Required | Also accepted (Upload-Post) |
| --- | --- | --- |
| `webhook_url` | Yes | The same name |

Connecting again replaces the Discord account on that profile. See [Connect with credentials](/api/connect-credentials).

## Example post

Photos to the channel, with a Discord-only message:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/photos \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=discord" \
  -F "title=New in the app this week" \
  -F "discord_title=New this week: dark mode and faster exports. Screens below." \
  -F "photos[]=@photo1.jpg" \
  -F "photos[]=@photo2.jpg"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.photos({
  user: 'my-brand',
  platforms: ['discord'],
  title: 'New in the app this week',
  photos: [
    { data: await readFile('photo1.jpg'), name: 'photo1.jpg', type: 'image/jpeg' },
    { data: await readFile('photo2.jpg'), name: 'photo2.jpg', type: 'image/jpeg' },
  ],
  extra: { discord_title: 'New this week: dark mode and faster exports. Screens below.' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.photos(
    "my-brand", ["discord"], ["photo1.jpg", "photo2.jpg"], "New in the app this week",
    extra={"discord_title": "New this week: dark mode and faster exports. Screens below."},
)
```

## Fields

| Field | Meaning |
| --- | --- |
| `discord_title` | The message text on Discord. Falls back to `title`. |
| `title` | The caption every network uses, when `discord_title` isn't sent. |
| `discord_thread_id` | Posts into this thread of the webhook's channel (or into an existing forum post). |
| `discord_thread_name` | In a forum channel, starts a new forum post with this title (up to 100 characters). |
| `discord_flags` | `suppress_embeds` (no link previews) and/or `suppress_notifications` (a silent message), separated by commas. |
| `discord_max_file_mb` | The file limit of a boosted server, in MB: 10 to 100, default 10. |

Discord has no options of its own in the dashboard composer. A webhook can't comment, so a `first_comment` isn't posted on Discord; the result says `"first_comment": "unsupported"` with a warning.

## Limits and behaviour

- **Files:** up to 10 MB each, Discord's limit for webhooks on servers without boosts. On a boosted server, send `discord_max_file_mb` (up to 100) to allow larger files. A file over the limit fails the Discord post with `file_too_large`; Reelspan doesn't shrink it.
- **Attachments:** up to 10 per message. With more photos, the first 10 are sent.
- **Text:** 2,000 characters, cut with a warning.
- **Author:** the webhook's name and picture, set in Discord. Change them there.

## After posting

The webhook can change only the messages it sent itself:

- **Delete** a message with [Unpublish](/api/unpublish).
- **Edit** its text with [Edit a post](/api/edit-post). Attachments stay as they are; text over 2,000 characters is cut with a warning.

## Common errors

| Code | When | Fix |
| --- | --- | --- |
| `INVALID_WEBHOOK` | Connecting: the URL isn't a Discord webhook, or Discord doesn't know it | Copy the URL again from Integrations → Webhooks. |
| `reauth_required` | Discord answered 401 or 404: the webhook was deleted | Make a new webhook and connect again. |
| `file_too_large` | A file is over the limit (10 MB, or `discord_max_file_mb`) | Send a smaller file, or raise `discord_max_file_mb` if the server is boosted. |
| `discord_error` | Discord refused the message. Retried automatically on 429 and 5xx | Read `error` for Discord's reason. |
| `MISSING_FIELD` | Connecting without `webhook_url` | Send it. |

Errors when connecting come back as a 400 with the code in `error_code`. Errors when posting are in that network's result. See [Errors](/errors).

Source: https://docs.reelspan.com/networks/discord

---

# Post to Slack

> Publish messages, photos, videos and files to a Slack channel, through an Incoming Webhook or a bot token that uploads files into the channel.

Reelspan posts to a Slack channel through a Slack app of your own. You connect it one of two ways, and the way decides what a post can carry.

## What you can post

| Post | With a webhook | With a bot token |
| --- | --- | --- |
| Text | A message | A message, with links unfurled |
| Photos | A message with up to 10 images, which Slack fetches and keeps | Up to 10 photos uploaded into the channel, with the text as their message |
| Video | A message with a link to the video, valid for 7 days, and a warning | The video uploaded into the channel, with the text as its message |

Use a **webhook** when you post text and photos and want the quickest setup. Use a **bot token** when you post videos, or want files to live in Slack.

With a bot token, the result's `url` is the message or file's permalink, and `file_ids` lists the uploaded files. A webhook doesn't answer with the message, so `url` and `post_id` are `null`.

## Connect your channel

### With a webhook

Setup takes about three minutes.

1. [Create a Slack app](https://api.slack.com/apps?new_app=1) for your workspace: **Create New App → From scratch**.
2. In the app, open **Incoming Webhooks** and turn them on.
3. Click **Add New Webhook**, pick the channel and allow. Copy the webhook URL.
4. In the Reelspan dashboard, open **Accounts → Connect account**, choose the profile and Slack, pick **Webhook**, and paste the URL. Add the channel's name if you want it shown in Reelspan.

Reelspan checks the webhook without posting anything: Slack answers an empty message with `no_text` when the hook is live.

### With a bot token

1. [Create a Slack app](https://api.slack.com/apps?new_app=1) for your workspace: **Create New App → From scratch**.
2. Under **OAuth & Permissions**, add the bot scopes `chat:write`, `files:write`, `channels:read` and `channels:join`, then **Install to Workspace**.
3. Copy the **Bot User OAuth Token** (`xoxb-…`). For a private channel, invite the bot there first: `/invite @yourbot`.
4. In the Reelspan dashboard, choose **Bot token** and paste the token and the channel: its name (`#announcements`) or its id (`C…`) from the channel details.

Reelspan checks the token, finds the channel, and joins it if it's public and the bot isn't in it yet. Credentials are stored encrypted.

### With the API

Send either pair to `POST /v1/accounts/slack`. When both are present, the webhook is used.

```bash title="cURL"
# a webhook
curl -X POST https://api.reelspan.com/v1/accounts/slack \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX", "name": "#announcements"}'

# or a bot token
curl -X POST https://api.reelspan.com/v1/accounts/slack \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "bot_token": "xoxb-...", "channel": "#announcements"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
// a webhook
await reelspan.accounts.connect('my-brand', 'slack', {
  webhook_url: process.env.SLACK_WEBHOOK_URL,
  name: '#announcements',
});
// or a bot token
await reelspan.accounts.connect('my-brand', 'slack', {
  bot_token: process.env.SLACK_BOT_TOKEN,
  channel: '#announcements',
});
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
# a webhook
reelspan.accounts.connect("my-brand", "slack", webhook_url=os.environ["SLACK_WEBHOOK_URL"], name="#announcements")
# or a bot token
reelspan.accounts.connect("my-brand", "slack", bot_token=os.environ["SLACK_BOT_TOKEN"], channel="#announcements")
```

```json
{ "success": true, "platform": "slack", "account": "#announcements", "reconnected": false }
```

| Field | Method | Meaning |
| --- | --- | --- |
| `webhook_url` | Webhook | The Incoming Webhook URL (`https://hooks.slack.com/services/…`) |
| `name` | Webhook | Optional. How the channel shows in Reelspan |
| `bot_token` | Bot token | The bot token (`xoxb-…`) |
| `channel` | Bot token | The channel's name or id. `name` is used when `channel` is empty |

The field names are the same as Upload-Post's. Connecting again replaces the Slack account on that profile. See [Connect with credentials](/api/connect-credentials).

## Example post

A video, uploaded into the channel (bot token):

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=slack" \
  -F "title=Launch day" \
  -F "slack_title=The launch video is ready. Share it with your teams." \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['slack'],
  title: 'Launch day',
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: { slack_title: 'The launch video is ready. Share it with your teams.' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["slack"], "launch.mp4", "Launch day",
    extra={"slack_title": "The launch video is ready. Share it with your teams."},
)
```

## Fields

| Field | Meaning |
| --- | --- |
| `slack_title` | The message text on Slack. Falls back to `title`. |
| `title` | The caption every network uses, when `slack_title` isn't sent. |
| `slack_alt_text` | Webhook only: alt text for the images. One text for all, or one per image. Falls back to `alt_text`. |
| `alt_text` | The alt text for every network that takes it. |

Slack has no options of its own in the dashboard composer. Slack posts can't take a first comment; a `first_comment` comes back as `"first_comment": "unsupported"` with a warning.

## Limits and behaviour

- **Text:** up to 40,000 characters; anything longer is dropped without a warning. With a webhook, the message block shows the first 3,000.
- **Files (bot token):** up to 1 GB each, and up to 10 per post.
- **Images (webhook):** up to 10. Slack fetches each from a link that works for 7 days and keeps its own copy.
- **Videos (webhook):** a webhook can't carry files, so the video goes as a link that works for 7 days, and the result carries a warning. Connect with a bot token to upload it.
- **Formatting:** webhook messages use Slack's `mrkdwn`.

## Common errors

| Code | When | Fix |
| --- | --- | --- |
| `INVALID_WEBHOOK` | Connecting: the URL isn't a Slack Incoming Webhook, or Slack doesn't accept it | Copy it again from the app's Incoming Webhooks page. Check the channel still exists. |
| `INVALID_TOKEN` | Connecting: the token doesn't start with `xoxb-` | Use the Bot User OAuth Token, not a user token. |
| `CHANNEL_NOT_FOUND` | Connecting: the bot can't see a channel by that name | Check the name, or use the channel's id. Invite the bot to a private channel. |
| `NOT_IN_CHANNEL` | Connecting: the bot isn't in a private channel, or couldn't join a public one | `/invite @yourbot` in the channel, or add the `channels:join` scope. |
| `MISSING_FIELD` | Connecting with neither a webhook URL nor a bot token | Send `webhook_url`, or `bot_token` and `channel`. |
| `reauth_required` | The token was revoked, or the webhook removed or its channel archived | Connect again. When connecting, this shows as `REAUTH_REQUIRED`. |
| `file_too_large` | A file is over 1 GB | Send a smaller file. |
| `slack_error` | Slack refused the call. Its reason is in `error`, with a hint for `not_in_channel`, `channel_not_found` and `missing_scope`. Retried automatically on 429 and 5xx | Follow the hint, then [retry](/api/retry). |

Errors when connecting come back as a 400 with the code in `error_code`. Errors when posting are in that network's result. See [Errors](/errors).

Source: https://docs.reelspan.com/networks/slack

---

# Post to Mastodon

> Publish posts with a video, up to 4 images, or text to any Mastodon server, with visibility, content warnings and alt text.

Reelspan posts to your Mastodon account on any server, with an access token you make in the server's settings. Servers that offer Mastodon's API, such as GoToSocial, work the same way.

## What you can post

| Post | How it appears |
| --- | --- |
| Video | A post with the video attached |
| Photos | A post with up to 4 images, each with its alt text. `photos[]` can mix images and a video |
| Text | A plain post |

Media is uploaded to your server first. Servers process video in the background, so Reelspan waits until it's ready before posting. The result's `url` is the post on your server and `post_id` its id.

## Connect your account

You need your server's address and an access token. Setup takes about two minutes.

1. On your server, open **Preferences → Development → New application** (on mastodon.social: [mastodon.social/settings/applications](https://mastodon.social/settings/applications)).
2. Name it Reelspan, keep the `read` and `write` scopes, and save.
3. Open the application and copy **Your access token**.
4. In the Reelspan dashboard, open **Accounts → Connect account**, choose the profile and Mastodon, and paste the token with your server (`mastodon.social`).

Reelspan checks the token with your server before saving it, encrypted.

### With the API

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/mastodon \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "server": "mastodon.social", "access_token": "..."}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.accounts.connect('my-brand', 'mastodon', {
  server: 'mastodon.social',
  access_token: process.env.MASTODON_TOKEN,
});
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.accounts.connect("my-brand", "mastodon", server="mastodon.social", access_token=os.environ["MASTODON_TOKEN"])
```

```json
{ "success": true, "platform": "mastodon", "account": "@yourname@mastodon.social", "reconnected": false }
```

| Field | Required | Also accepted (Upload-Post) |
| --- | --- | --- |
| `server` | Yes | `instance_url` |
| `access_token` | Yes | |

`server` can be `mastodon.social` or `https://mastodon.social`; Reelspan always talks to it over https. Connecting again replaces the Mastodon account on that profile. See [Connect with credentials](/api/connect-credentials).

## Example post

Two images behind a content warning, visible to followers only:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/photos \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=mastodon" \
  -F "title=First look at the new dashboard #design" \
  -F "mastodon_visibility=private" \
  -F "mastodon_spoiler_text=Product screenshots" \
  -F "alt_text[]=The dashboard in light mode" \
  -F "alt_text[]=The dashboard in dark mode" \
  -F "photos[]=@photo1.jpg" \
  -F "photos[]=@photo2.jpg"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.photos({
  user: 'my-brand',
  platforms: ['mastodon'],
  title: 'First look at the new dashboard #design',
  photos: [
    { data: await readFile('photo1.jpg'), name: 'photo1.jpg', type: 'image/jpeg' },
    { data: await readFile('photo2.jpg'), name: 'photo2.jpg', type: 'image/jpeg' },
  ],
  altTexts: ['The dashboard in light mode', 'The dashboard in dark mode'],
  extra: { mastodon_visibility: 'private', mastodon_spoiler_text: 'Product screenshots' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.photos(
    "my-brand", ["mastodon"], ["photo1.jpg", "photo2.jpg"], "First look at the new dashboard #design",
    alt_texts=["The dashboard in light mode", "The dashboard in dark mode"],
    extra={"mastodon_visibility": "private", "mastodon_spoiler_text": "Product screenshots"},
)
```

## Fields

| Field | Meaning |
| --- | --- |
| `mastodon_title` | The post's text on Mastodon. Falls back to `title`. |
| `title` | The caption every network uses, when `mastodon_title` isn't sent. |
| `mastodon_visibility` | Who sees it: `public` (the default), `unlisted`, or `private` (followers only). Sent to your server as given. |
| `mastodon_spoiler_text` | A content warning shown before the post. |
| `mastodon_sensitive` | `true` marks the media as sensitive. Default `false`. |
| `mastodon_alt_text` | Alt text for the media: one text for all, or one per image. Falls back to `alt_text`. Up to 1,500 characters each. |
| `alt_text` | The alt text for every network that takes it. |
| `mastodon_first_comment` | Posted as an unlisted reply to the post. Falls back to `first_comment`. |

In the dashboard composer, the Mastodon tab has **Visibility**, **Content warning** and **Mark media as sensitive**.

## Limits and behaviour

- **Images:** up to 4 per post. With more, the first 4 are sent and the result carries a warning.
- **Files:** up to 99 MB each; your server may allow less.
- **Video processing:** Reelspan waits up to about 3 minutes for the server to process a video, then fails with `processing_timeout`, which is retried.
- **Text length:** set by your server (500 characters on most). Reelspan sends the text as it is.
- **No duplicates:** each post is sent with the request's id as Mastodon's idempotency key, so a retry doesn't post twice.
- **Analytics:** likes, boosts and replies per post, and followers, following and post counts for the account. See [Analytics](/api/analytics).
- **Your server only:** calls go only to the server you named, and never to private network addresses.

## Common errors

| Code | When | Fix |
| --- | --- | --- |
| `INVALID_SERVER` | Connecting: the server isn't an address like `mastodon.social` | Enter just the server's address. |
| `INVALID_TOKEN` | Connecting: the server didn't accept the token | Make a token with `read` and `write` under Preferences → Development. |
| `reauth_required` | The server answered 401 or 403: the token was revoked | Make a new token and connect again. |
| `file_too_large` | A file is over 99 MB | Send a smaller file. |
| `processing_timeout` | The server took too long to process the video | Reelspan retries; if it keeps failing, try a shorter or smaller video. |
| `mastodon_error` | The server refused the post, for example text over its limit. Retried automatically on 429 and 5xx | Read `error` for the server's reason. |
| `MISSING_FIELD` | Connecting without `server` or `access_token` | Send both. |

Errors when connecting come back as a 400 with the code in `error_code`. Errors when posting are in that network's result. See [Errors](/errors).

Source: https://docs.reelspan.com/networks/mastodon

---

# Post to Nostr

> Publish signed Nostr notes with video, photos or text to your relays, with media hosted on nostr.build and shown inline by most clients.

Reelspan signs a note with your Nostr key and sends it to your relays. Videos and photos go to nostr.build first, and their links go in the note, where most clients show them inline.

## What you can post

| Post | How it appears |
| --- | --- |
| Text | A note (kind 1) |
| Photos | A note with up to 10 photos or videos, their links added after the text |
| Video | A note with the video's link added after the text |

Each media link is also tagged in the note (`imeta`), and every `#hashtag` in the text becomes a topic tag, so clients can find the note by it.

The result's `url` opens the note on njump.me, `post_id` is the note's event id, and `relays` lists the relays that took it.

## Connect your key

You need your private key. Setup takes about a minute.

1. Copy your private key (`nsec1…`) from your Nostr app's key or account settings.
2. In the Reelspan dashboard, open **Accounts → Connect account**, choose the profile and Nostr, and paste the key.
3. Name the relays to publish to, or leave them empty for `wss://relay.damus.io`, `wss://nos.lol` and `wss://relay.primal.net`.

> [!IMPORTANT]
> Your private key is stored encrypted and only signs the notes you send through Reelspan, plus the upload authorisation nostr.build asks for. If you'd rather not share your main key, make a separate key for the account you post from.

### With the API

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/nostr \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "nsec": "nsec1...", "relays": ["wss://relay.damus.io", "wss://nos.lol"]}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.accounts.connect('my-brand', 'nostr', {
  nsec: process.env.NOSTR_NSEC,
  relays: ['wss://relay.damus.io', 'wss://nos.lol'],
});
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.accounts.connect("my-brand", "nostr", nsec=os.environ["NOSTR_NSEC"], relays=["wss://relay.damus.io", "wss://nos.lol"])
```

```json
{ "success": true, "platform": "nostr", "account": "npub1abcdefghijk…", "reconnected": false }
```

| Field | Required | Also accepted (Upload-Post) |
| --- | --- | --- |
| `nsec` | Yes. `nsec1…`, or the key as 64 hex characters | `private_key` |
| `relays` | No. A list, or one string separated by spaces or commas. Up to 10 are used | |

Connecting again replaces the Nostr account on that profile. See [Connect with credentials](/api/connect-credentials).

## Example post

A video note:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=nostr" \
  -F "title=Launch day" \
  -F "nostr_title=We shipped. Here's the 60-second tour #launch #buildinpublic" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['nostr'],
  title: 'Launch day',
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: { nostr_title: "We shipped. Here's the 60-second tour #launch #buildinpublic" },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["nostr"], "launch.mp4", "Launch day",
    extra={"nostr_title": "We shipped. Here's the 60-second tour #launch #buildinpublic"},
)
```

```json
{
  "success": true,
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "results": {
    "nostr": {
      "success": true,
      "url": "https://njump.me/note1…",
      "post_id": "5c83da77…",
      "relays": ["wss://relay.damus.io", "wss://nos.lol"]
    }
  }
}
```

## Fields

| Field | Meaning |
| --- | --- |
| `nostr_title` | The note's text. Falls back to `title`. |
| `title` | The caption every network uses, when `nostr_title` isn't sent. |

Nostr has no options of its own in the dashboard composer. A `first_comment` isn't posted on Nostr; the result says `"first_comment": "unsupported"` with a warning.

## Limits and behaviour

- **Media:** up to 10 items per note, each up to 100 MB, uploaded to nostr.build (a NIP-96 server, authorised with a NIP-98 signature from your key). The media server can't be changed today.
- **Relays:** the note goes to every relay at once, and each has 10 seconds to accept it. The post succeeds when at least one relay takes it; each relay that didn't is named in a warning.
- **Text:** no limit is applied by Reelspan. The dashboard composer stops at 10,000 characters.
- **Signing:** each note is signed with your key on Reelspan's servers; the key never leaves them.

## Common errors

| Code | When | Fix |
| --- | --- | --- |
| `INVALID_KEY` | Connecting: the key isn't `nsec1…` or 64 hex characters | Copy the private key (`nsec1…`), not the public one (`npub1…`). |
| `INVALID_RELAY` | Connecting: a relay isn't a `wss://` address | Use `wss://` addresses only. |
| `nostr_relays_failed` | No relay accepted the note; each relay's answer is in `error`. Retried automatically | Check the relays still accept your notes, or connect again with others. |
| `nostr_media_error` | nostr.build didn't take the file. Retried automatically on 5xx | Read `error` for the server's reason. |
| `file_too_large` | A file is over 100 MB | Send a smaller file. |
| `MISSING_FIELD` | Connecting without `nsec` | Send it. |

Errors when connecting come back as a 400 with the code in `error_code`. Errors when posting are in that network's result. See [Errors](/errors).

Source: https://docs.reelspan.com/networks/nostr

---

# Post to Lemmy

> Publish posts with an image, a video or text to a Lemmy community on any server, with a title, a body and an NSFW flag.

Reelspan posts to one community on your Lemmy server, as your account. Each post has a title, an optional body, and optionally one image or video, which is uploaded to the server's image host and linked from the post.

## What you can post

| Post | How it appears |
| --- | --- |
| Text | A post with a title and a body |
| Photos | A post linking one image. Only the first photo is used |
| Video | A post linking the video |

The **title** is `lemmy_title`, else the first line of the caption (up to 200 characters), else "Untitled". The **body** is `lemmy_description`, else `description`, else the caption when it says more than the title.

The result's `url` is the post on your server (`https://lemmy.world/post/123`), and `post_id` its id.

## Connect a community

You need an account on the server that may post in the community. Setup takes about a minute.

1. Use an account on your Lemmy server that may post in the community.
2. In the Reelspan dashboard, open **Accounts → Connect account**, choose the profile and Lemmy.
3. Enter the server (`lemmy.world`), the community, and the account's username and password.

The community is its name as in `lemmy.world/c/technology`. One on another server is `name@server`. A `!name` or a full community link works too.

> [!NOTE]
> Reelspan signs in once to get a token and keeps only the token. Your password isn't stored. An account with two-factor sign-in needs it turned off for this.

### With the API

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/lemmy \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "server": "lemmy.world", "community": "technology", "username": "yourname", "password": "..."}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.accounts.connect('my-brand', 'lemmy', {
  server: 'lemmy.world',
  community: 'technology',
  username: 'yourname',
  password: process.env.LEMMY_PASSWORD,
});
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.accounts.connect(
    "my-brand", "lemmy",
    server="lemmy.world", community="technology", username="yourname", password=os.environ["LEMMY_PASSWORD"],
)
```

```json
{ "success": true, "platform": "lemmy", "account": "!technology@lemmy.world", "reconnected": false }
```

| Field | Required | Also accepted (Upload-Post) |
| --- | --- | --- |
| `server` | Yes | `instance_url` |
| `community` | Yes | |
| `username` | Yes. The username or email | |
| `password` | Yes. Used once, not kept | |

Connecting again replaces the Lemmy account on that profile. See [Connect with credentials](/api/connect-credentials).

## Example post

An image post with a title and a body:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/photos \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=lemmy" \
  -F "title=New dashboard" \
  -F "lemmy_title=We rebuilt our dashboard around keyboard shortcuts" \
  -F "lemmy_description=Every action now has a shortcut. Here is what changed and why." \
  -F "photos[]=@photo1.jpg"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.photos({
  user: 'my-brand',
  platforms: ['lemmy'],
  title: 'New dashboard',
  photos: [{ data: await readFile('photo1.jpg'), name: 'photo1.jpg', type: 'image/jpeg' }],
  extra: {
    lemmy_title: 'We rebuilt our dashboard around keyboard shortcuts',
    lemmy_description: 'Every action now has a shortcut. Here is what changed and why.',
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.photos(
    "my-brand", ["lemmy"], ["photo1.jpg"], "New dashboard",
    extra={
        "lemmy_title": "We rebuilt our dashboard around keyboard shortcuts",
        "lemmy_description": "Every action now has a shortcut. Here is what changed and why.",
    },
)
```

## Fields

| Field | Meaning |
| --- | --- |
| `lemmy_title` | The post's title, up to 200 characters in the composer. Falls back to the caption's first line. |
| `lemmy_description` | The post's body. Falls back to `description`. |
| `description` | The body, when `lemmy_description` isn't sent. |
| `title` | The caption: its first line is the title and the whole of it the body, when the fields above aren't sent. |
| `lemmy_nsfw` | `true` marks the post NSFW. Default `false`. |
| `lemmy_first_comment` | Posted as a comment on the post. Falls back to `first_comment`. |

> [!TIP]
> When you send `lemmy_title`, the caption becomes that title too, so send the body in `lemmy_description` or `description`.

In the dashboard composer, the Lemmy tab has an **NSFW** switch.

## Limits and behaviour

- **One image or video per post.** With several photos, the first is used and the result carries a warning. Videos in `photos[]` are left out, with a warning.
- **Files:** up to 100 MB; your server's image host may allow less, or refuse video.
- **Token:** the token from signing in is kept, encrypted. If the server ends it, posts fail with `reauth_required`; connect again.
- **Your server only:** calls go only to the server you named, and never to private network addresses.

## Common errors

| Code | When | Fix |
| --- | --- | --- |
| `INVALID_SERVER` | Connecting: the server isn't an address like `lemmy.world` | Enter just the server's address. |
| `INVALID_CREDENTIALS` | Connecting: the server refused the login, two-factor sign-in is on, or the account still needs its email confirmed or approval | Check the login, turn off two-factor sign-in, or finish the account's setup. |
| `COMMUNITY_NOT_FOUND` | Connecting: no community by that name on the server | Check the name; use `name@server` for one on another server. |
| `reauth_required` | The server no longer accepts the token | Connect again. |
| `file_too_large` | The file is over 100 MB | Send a smaller file. |
| `lemmy_error` | The server refused the post or the upload. Retried automatically on 429 and 5xx | Read `error` for the server's reason. |
| `MISSING_FIELD` | Connecting without one of the four fields | Send all four. |

Errors when connecting come back as a 400 with the code in `error_code`. Errors when posting are in that network's result. See [Errors](/errors).

Source: https://docs.reelspan.com/networks/lemmy

---

# Post to Dev.to

> Publish Markdown articles to Dev.to with tags and a canonical URL, published at once or saved as a draft, connected with an API key.

Reelspan publishes articles to your Dev.to account from Markdown. Dev.to takes text posts only: send them with [Post text](/api/post-text).

## What you can post

| Post | How it appears |
| --- | --- |
| Text | An article: a title, a Markdown body, up to 4 tags and an optional canonical URL |

The **title** is `devto_title`, else the first line of the caption, up to 250 characters. The **body** is `devto_description`, else `description`, else the whole caption (its first line included).

> [!TIP]
> The cleanest request sends the article's title as `title` and the Markdown body as `description`. If you send `devto_title`, the caption becomes that title too, so the body must come from `devto_description` or `description`.

Videos and photos can't be sent: Dev.to's API takes no uploads, and the request is refused with `UNSUPPORTED_POST_TYPE`. To show an image, link one already online in the Markdown.

The result's `url` is the article on dev.to and `post_id` its id.

## Connect your account

You need an API key. Setup takes about a minute.

1. On dev.to, open [Settings → Extensions](https://dev.to/settings/extensions) and scroll to **DEV Community API Keys**.
2. Describe it as Reelspan and click **Generate API Key**.
3. In the Reelspan dashboard, open **Accounts → Connect account**, choose the profile and Dev.to, and paste the key.

Reelspan checks the key with Dev.to before saving it, encrypted.

### With the API

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/devto \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "api_key": "..."}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.accounts.connect('my-brand', 'devto', { api_key: process.env.DEVTO_API_KEY });
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.accounts.connect("my-brand", "devto", api_key=os.environ["DEVTO_API_KEY"])
```

```json
{ "success": true, "platform": "devto", "account": "@yourname", "reconnected": false }
```

| Field | Required | Also accepted (Upload-Post) |
| --- | --- | --- |
| `api_key` | Yes | The same name |

Connecting again replaces the Dev.to account on that profile. See [Connect with credentials](/api/connect-credentials).

## Example post

An article with tags and a canonical URL:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "my-brand",
    "platform": ["devto"],
    "title": "How we cut our build time in half",
    "description": "## The problem\n\nOur CI took 14 minutes...\n\n## What we changed\n\n...",
    "devto_tags": "devops, ci, webdev",
    "devto_canonical_url": "https://example.com/blog/faster-builds"
  }'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.text({
  user: 'my-brand',
  platforms: ['devto'],
  title: 'How we cut our build time in half',
  description: await readFile('faster-builds.md', 'utf8'),
  extra: { devto_tags: 'devops, ci, webdev', devto_canonical_url: 'https://example.com/blog/faster-builds' },
});
```

```python title="Python"
from pathlib import Path
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.text(
    "my-brand", ["devto"], "How we cut our build time in half",
    description=Path("faster-builds.md").read_text(),
    extra={"devto_tags": "devops, ci, webdev", "devto_canonical_url": "https://example.com/blog/faster-builds"},
)
```

## Fields

| Field | Meaning |
| --- | --- |
| `devto_title` | The article's title. Falls back to the caption's first line. |
| `devto_description` | The article's Markdown body. Falls back to `description`. |
| `description` | The body, when `devto_description` isn't sent. |
| `title` | The caption: its first line is the title and the whole of it the body, when the fields above aren't sent. |
| `devto_tags` | Tags, separated by commas. Each is lowercased and keeps only letters, digits and `-`. The first 4 are used. |
| `devto_canonical_url` | Where the article was first published, for search engines. |
| `devto_published` | `false` saves the article as a draft on Dev.to. Default: published. |

In the dashboard composer, the Dev.to tab has **Tags**, **Canonical URL** and **Save as a draft**.

## Limits and behaviour

- **Tags:** 4 per article. With more, the first 4 are used and the result carries a warning.
- **Title:** up to 250 characters; longer is cut.
- **Drafts:** a draft answers with a warning, "Saved as a draft on Dev.to".
- **No first comment:** a `first_comment` isn't posted; the result says `"first_comment": "unsupported"` with a warning.
- **Analytics:** reactions, comments and, when Dev.to returns them, page views per article. See [Analytics](/api/analytics).

## Common errors

| Code | When | Fix |
| --- | --- | --- |
| `INVALID_TOKEN` | Connecting: Dev.to didn't accept the key | Generate a new key under Settings → Extensions. |
| `UNSUPPORTED_POST_TYPE` | The request is a video or photo post | Send articles with `POST /v1/posts/text`. |
| `title_required` | The title came out empty | Send a `title` (or `devto_title`) with text on its first line. |
| `reauth_required` | Dev.to answered 401: the key was revoked | Generate a new key and connect again. |
| `devto_error` | Dev.to refused the article. Retried automatically on 429 and 5xx | Read `error` for Dev.to's reason. |
| `MISSING_FIELD` | Connecting without `api_key` | Send it. |

Errors when connecting come back as a 400 with the code in `error_code`. `UNSUPPORTED_POST_TYPE` refuses the whole request with a 400. Errors when posting are in that network's result. See [Errors](/errors).

Source: https://docs.reelspan.com/networks/devto

---

# Post to Hashnode

> Publish Markdown articles to your Hashnode blog with tags and a canonical URL, connected with a personal access token.

Reelspan publishes articles to one of your Hashnode blogs from Markdown. Hashnode takes text posts only: send them with [Post text](/api/post-text).

## What you can post

| Post | How it appears |
| --- | --- |
| Text | An article on your blog: a title, a Markdown body, up to 5 tags and an optional canonical URL |

The **title** is `hashnode_title`, else the first line of the caption, up to 250 characters. The **body** is `hashnode_description`, else `description`, else the whole caption (its first line included).

> [!TIP]
> The cleanest request sends the article's title as `title` and the Markdown body as `description`. If you send `hashnode_title`, the caption becomes that title too, so the body must come from `hashnode_description` or `description`.

Videos and photos can't be sent: the request is refused with `UNSUPPORTED_POST_TYPE`. To show an image, link one already online in the Markdown.

Articles are always published; Hashnode has no draft option in Reelspan. The result's `url` is the article on your blog and `post_id` its id.

## Connect your blog

You need a personal access token. Setup takes about a minute.

1. On Hashnode, open [Account settings → Developer](https://hashnode.com/settings/developer) and click **Generate new token**.
2. In the Reelspan dashboard, open **Accounts → Connect account**, choose the profile and Hashnode, and paste the token.
3. With more than one blog, add the one to post to: its address (`yourblog.hashnode.dev`) or its publication id. With one blog, leave it empty.

Reelspan checks the token with Hashnode and finds the blog before saving, encrypted.

### With the API

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/hashnode \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "token": "...", "blog": "yourblog.hashnode.dev"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.accounts.connect('my-brand', 'hashnode', {
  token: process.env.HASHNODE_TOKEN,
  blog: 'yourblog.hashnode.dev',
});
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.accounts.connect("my-brand", "hashnode", token=os.environ["HASHNODE_TOKEN"], blog="yourblog.hashnode.dev")
```

```json
{ "success": true, "platform": "hashnode", "account": "yourblog.hashnode.dev", "reconnected": false }
```

| Field | Required | Also accepted (Upload-Post) |
| --- | --- | --- |
| `token` | Yes | `pat` |
| `blog` | With more than one blog. Its address or publication id | `publication_id` |

Connecting again replaces the Hashnode account on that profile. See [Connect with credentials](/api/connect-credentials).

## Example post

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "my-brand",
    "platform": ["hashnode"],
    "title": "How we cut our build time in half",
    "description": "## The problem\n\nOur CI took 14 minutes...\n\n## What we changed\n\n...",
    "hashnode_tags": "devops, ci, webdev",
    "hashnode_canonical_url": "https://example.com/blog/faster-builds"
  }'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.text({
  user: 'my-brand',
  platforms: ['hashnode'],
  title: 'How we cut our build time in half',
  description: await readFile('faster-builds.md', 'utf8'),
  extra: { hashnode_tags: 'devops, ci, webdev', hashnode_canonical_url: 'https://example.com/blog/faster-builds' },
});
```

```python title="Python"
from pathlib import Path
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.text(
    "my-brand", ["hashnode"], "How we cut our build time in half",
    description=Path("faster-builds.md").read_text(),
    extra={"hashnode_tags": "devops, ci, webdev", "hashnode_canonical_url": "https://example.com/blog/faster-builds"},
)
```

## Fields

| Field | Meaning |
| --- | --- |
| `hashnode_title` | The article's title. Falls back to the caption's first line. |
| `hashnode_description` | The article's Markdown body. Falls back to `description`. |
| `description` | The body, when `hashnode_description` isn't sent. |
| `title` | The caption: its first line is the title and the whole of it the body, when the fields above aren't sent. |
| `hashnode_tags` | Tags, separated by commas. Each is lowercased and keeps only letters, digits and `-`, and is sent as the tag's slug. The first 5 are used. |
| `hashnode_canonical_url` | Where the article was first published, sent to Hashnode as the original article URL. |

In the dashboard composer, the Hashnode tab has **Tags** and **Canonical URL**.

## Limits and behaviour

- **Tags:** 5 per article; any more are dropped without a warning.
- **Title:** up to 250 characters; longer is cut.
- **No first comment:** a `first_comment` isn't posted; the result says `"first_comment": "unsupported"` with a warning.

## Common errors

| Code | When | Fix |
| --- | --- | --- |
| `INVALID_TOKEN` | Connecting: Hashnode didn't accept the token | Generate a new token under Account settings → Developer. |
| `PUBLICATION_REQUIRED` | Connecting: the account has several blogs and none was named, the one named isn't found, or the account has no blog yet. The message lists your blogs | Send `blog` with one of the listed addresses. |
| `UNSUPPORTED_POST_TYPE` | The request is a video or photo post | Send articles with `POST /v1/posts/text`. |
| `title_required` | The title came out empty | Send a `title` (or `hashnode_title`) with text on its first line. |
| `reauth_required` | Hashnode says the token is no longer valid | Generate a new token and connect again. |
| `hashnode_error` | Hashnode refused the article. Retried automatically on 429 and 5xx | Read `error` for Hashnode's reason. |
| `MISSING_FIELD` | Connecting without `token` | Send it. |

Errors when connecting come back as a 400 with the code in `error_code`. `UNSUPPORTED_POST_TYPE` refuses the whole request with a 400. Errors when posting are in that network's result. See [Errors](/errors).

Source: https://docs.reelspan.com/networks/hashnode

---

# Post to WordPress

> Publish blog posts to a self-hosted WordPress site with the video or photos embedded, published at once or saved as a draft.

Reelspan publishes blog posts to your self-hosted WordPress site (5.6 or later) through its REST API, signed in with an application password. Videos and photos go to the site's media library and are embedded in the post.

## What you can post

| Post | How it appears |
| --- | --- |
| Text | A post with a title and a body |
| Photos | A post with every photo embedded as an image block above the body. The first photo becomes the featured image |
| Video | A post with the video embedded as a video block above the body. `photos[]` can mix photos and videos too |

The **title** is `wordpress_title`, else the first line of the caption, up to 200 characters. The **body** is `wordpress_description`, else `description`, else the whole caption. Blank lines start new paragraphs.

> [!NOTE]
> The body is plain text: HTML and Markdown in it show as typed, not as formatting. If you send `wordpress_title`, the caption becomes that title too, so send the body in `wordpress_description` or `description`.

The result's `url` is the post's link and `post_id` its id.

## Connect your site

You need the site's address, a username and an application password. Setup takes about two minutes.

1. In your WordPress admin, open **Users → Profile** (`/wp-admin/profile.php`) and scroll to **Application Passwords**. They need WordPress 5.6 or later, on https.
2. Name it Reelspan and click **Add New Application Password**. Copy the password it shows once.
3. In the Reelspan dashboard, open **Accounts → Connect account**, choose the profile and WordPress, and enter your site, username and the application password.

Your own login password is never needed. Reelspan checks the three with your site, and that the user may publish posts, before saving them, encrypted.

### With the API

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/wordpress \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "site": "example.com", "username": "editor", "app_password": "abcd efgh ijkl mnop qrst uvwx"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.accounts.connect('my-brand', 'wordpress', {
  site: 'example.com',
  username: 'editor',
  app_password: process.env.WP_APP_PASSWORD,
});
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.accounts.connect("my-brand", "wordpress", site="example.com", username="editor", app_password=os.environ["WP_APP_PASSWORD"])
```

```json
{ "success": true, "platform": "wordpress", "account": "example.com", "reconnected": false }
```

| Field | Required | Also accepted (Upload-Post) |
| --- | --- | --- |
| `site` | Yes. Its address, with a path if WordPress lives in one (`example.com/blog`) | `site_url` |
| `username` | Yes | |
| `app_password` | Yes. With or without its spaces | `application_password` |

Connecting again replaces the WordPress account on that profile. See [Connect with credentials](/api/connect-credentials).

## Example post

A video post, saved as a draft to review in WordPress:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=wordpress" \
  -F "title=Launch day" \
  -F "wordpress_title=Our launch, in 60 seconds" \
  -F "wordpress_description=Today we opened the doors.

Watch the tour above, then read on for what comes next." \
  -F "wordpress_status=draft" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['wordpress'],
  title: 'Launch day',
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  extra: {
    wordpress_title: 'Our launch, in 60 seconds',
    wordpress_description: 'Today we opened the doors.\n\nWatch the tour above, then read on for what comes next.',
    wordpress_status: 'draft',
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["wordpress"], "launch.mp4", "Launch day",
    extra={
        "wordpress_title": "Our launch, in 60 seconds",
        "wordpress_description": "Today we opened the doors.\n\nWatch the tour above, then read on for what comes next.",
        "wordpress_status": "draft",
    },
)
```

## Fields

| Field | Meaning |
| --- | --- |
| `wordpress_title` | The post's title. Falls back to the caption's first line. |
| `wordpress_description` | The post's body. Falls back to `description`. |
| `description` | The body, when `wordpress_description` isn't sent. |
| `title` | The caption: its first line is the title and the whole of it the body, when the fields above aren't sent. |
| `wordpress_status` | `draft` saves the post as a draft. Anything else, or nothing, publishes it. |
| `wordpress_excerpt` | The post's excerpt, the short summary themes show in lists and feeds. |
| `wordpress_slug` | The post's slug, the last part of its address (`example.com/my-post`). WordPress makes it unique if it is taken. |
| `wordpress_alt_text` | Alt text for the photos: one text for all, or one per photo. Saved on each image in the media library. Falls back to `alt_text`. |
| `alt_text` | The alt text for every network that takes it. |

In the dashboard composer, the WordPress tab has **Save as a draft**. A `first_comment` isn't posted on WordPress; the result says `"first_comment": "unsupported"` with a warning.

## Limits and behaviour

- **Files:** up to 512 MB each, sent to your media library; your site's own upload limit may be lower.
- **Photos:** every photo in the request is uploaded and embedded, in order.
- **Drafts:** a draft answers with a warning, "Saved as a draft on WordPress".
- **https only:** Reelspan always calls your site over https, even if you enter `http://`.
- **No redirects:** Reelspan doesn't follow redirects, so enter the address the site answers on (for example with `www.` if it moves you there).
- **Your site only:** calls go only to the site you named, and never to private network addresses.

## After posting

- **Delete** a post with [Unpublish](/api/unpublish). It goes to the site's trash, where it can be restored for 30 days.
- **Edit** it with [Edit a post](/api/edit-post): `title` changes the title, `text` (or `description`) replaces the body text while keeping the images and video in it, and `fields` can change `wordpress_excerpt` and `wordpress_status` (`publish`, `draft`, `private` or `pending`).

## Common errors

| Code | When | Fix |
| --- | --- | --- |
| `INVALID_SITE` | Connecting: the site isn't an address | Enter it like `example.com`. |
| `INVALID_CREDENTIALS` | Connecting: the site didn't accept the username and application password | Make a new application password under Users → Profile, and check the site uses https. |
| `INSUFFICIENT_ROLE` | Connecting: the user can't publish posts | Use an Author, Editor or Administrator account. |
| `reauth_required` | The site answered 401 or 403: the application password was revoked | Make a new one and connect again. |
| `file_too_large` | A file is over 512 MB | Send a smaller file. |
| `wordpress_error` | The site refused the post or an upload. Retried automatically on 429 and 5xx | Read `error` for the site's reason. |
| `MISSING_FIELD` | Connecting without one of the three fields | Send all three. |

Errors when connecting come back as a 400 with the code in `error_code`. Errors when posting are in that network's result. See [Errors](/errors).

Source: https://docs.reelspan.com/networks/wordpress

---

# Post to Whop

> Publish forum posts with videos, photos or text to your Whop company's forums, with an optional title and pinning, through a company API key.

Reelspan posts to a forum in your Whop company through the Whop API, with a company API key. Videos and photos are uploaded to Whop and attached to the post.

## What you can post

| Post | How it appears |
| --- | --- |
| Text | A forum post |
| Photos | A forum post with up to 10 photos attached. `photos[]` can mix photos and videos |
| Video | A forum post with the video attached |

The post's text is `whop_title`, else `title`, the same as the caption on every network. A separate post title is optional: send it as `whop_post_title`.

Whop's API doesn't return a link to the post, so `url` is `null`; `post_id` is the post's id.

## Connect a forum

You need a company API key and the forum. Setup takes about two minutes.

1. In your [Whop dashboard](https://whop.com/dashboard), open **Developer** and create a Company API key with the `forum:read`, `forum:post:create` and file permissions.
2. Open the forum and copy its experience id (`exp_…`) from the address bar.
3. For the company's public forum instead, leave the forum empty and use the company id (`biz_…`).
4. In the Reelspan dashboard, open **Accounts → Connect account**, choose the profile and Whop, and enter the key with the forum or the company id.

Reelspan checks the key against the forum before saving it, encrypted.

### With the API

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/whop \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "api_key": "...", "forum": "exp_XXXXXXXX"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.accounts.connect('my-brand', 'whop', {
  api_key: process.env.WHOP_API_KEY,
  forum: 'exp_XXXXXXXX',
});
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.accounts.connect("my-brand", "whop", api_key=os.environ["WHOP_API_KEY"], forum="exp_XXXXXXXX")
```

For the company's public forum, send `company_id` instead of `forum`:

```json
{ "profile_username": "my-brand", "api_key": "...", "company_id": "biz_XXXXXXXX" }
```

```json
{ "success": true, "platform": "whop", "account": "Announcements", "reconnected": false }
```

`account` is the forum's name, or "Public forum".

| Field | Required | Also accepted (Upload-Post) |
| --- | --- | --- |
| `api_key` | Yes | The same name |
| `forum` | For a forum: its experience id (`exp_…`) | `experience_id` |
| `company_id` | For the public forum: the company id (`biz_…`) | |

Connecting again replaces the Whop account on that profile. See [Connect with credentials](/api/connect-credentials).

## Example post

A pinned post with a title and a video:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=whop" \
  -F "title=This week's lesson: pricing your first offer. Watch it, then post your price below." \
  -F "whop_post_title=Lesson 4: pricing" \
  -F "whop_pinned=true" \
  -F "video=@lesson.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['whop'],
  title: "This week's lesson: pricing your first offer. Watch it, then post your price below.",
  video: { data: await readFile('lesson.mp4'), name: 'lesson.mp4', type: 'video/mp4' },
  extra: { whop_post_title: 'Lesson 4: pricing', whop_pinned: 'true' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video(
    "my-brand", ["whop"], "lesson.mp4",
    "This week's lesson: pricing your first offer. Watch it, then post your price below.",
    extra={"whop_post_title": "Lesson 4: pricing", "whop_pinned": "true"},
)
```

## Fields

| Field | Meaning |
| --- | --- |
| `whop_title` | The post's text on Whop. Falls back to `title`. |
| `title` | The caption every network uses, when `whop_title` isn't sent. |
| `whop_post_title` | The post's title, shown above the text. Optional. |
| `whop_pinned` | `true` pins the post to the top of the forum. Default `false`. |

> [!WARNING]
> On Upload-Post, `whop_title` is the post's title. On Reelspan it is the post's text, as `{network}_title` is on every network; the title is `whop_post_title`.

In the dashboard composer, the Whop tab has **Title** and **Pin to the top of the forum**. A `first_comment` isn't posted on Whop; the result says `"first_comment": "unsupported"` with a warning.

## Limits and behaviour

- **Files:** up to 2 GB each, uploaded to Whop as public files. Reelspan waits up to about a minute for Whop to process each one, then fails with `processing_timeout`, which is retried.
- **Attachments:** up to 10 photos per post; any more are dropped.
- **No link:** the result has no `url`; find the post in the forum.

## Common errors

| Code | When | Fix |
| --- | --- | --- |
| `INVALID_COMPANY` | Connecting: the company id doesn't start with `biz_` | Copy it from the Whop dashboard → Settings → Developer. |
| `INVALID_FORUM` | Connecting: the forum isn't an `exp_…` id, or it's empty with no company id | Send the forum's `exp_…` id, or a `company_id` for the public forum. |
| `INVALID_TOKEN` | Connecting: Whop didn't accept the key for that forum or company | Give the key `forum:read` and `forum:post:create`, and check it belongs to that company. |
| `reauth_required` | Whop answered 401 or 403: the key was revoked or lost a permission | Fix the key and connect again. |
| `processing_timeout` | Whop took too long to process a file | Reelspan retries; if it keeps failing, try a smaller file. |
| `file_too_large` | A file is over 2 GB | Send a smaller file. |
| `whop_error` | Whop refused the post or a file. Retried automatically on 429 and 5xx | Read `error` for Whop's reason. |
| `MISSING_FIELD` | Connecting without `api_key` | Send it. |

Errors when connecting come back as a 400 with the code in `error_code`. Errors when posting are in that network's result. See [Errors](/errors).

Source: https://docs.reelspan.com/networks/whop

---

# Post to Listmonk

> Send each post as a Listmonk newsletter campaign to a list, with photos in the email, sent at once or saved as a draft campaign.

Reelspan turns each post into a campaign on your self-hosted Listmonk and sends it to the list you connected. Photos are uploaded to Listmonk's media library and shown in the email above the text.

## What you can post

| Post | How it appears |
| --- | --- |
| Text | An email campaign: a subject and the text, as HTML paragraphs |
| Photos | The same, with up to 10 photos above the text |

Videos can't be sent: the request is refused with `UNSUPPORTED_POST_TYPE`.

The **subject** is `listmonk_title`, else the first line of the caption (up to 200 characters), else "News". The **email body** is `listmonk_description`, else `description`, else the whole caption. Blank lines start new paragraphs; HTML in the text is shown as typed.

> [!WARNING]
> A campaign is sent to the whole list as soon as the post publishes. Send `listmonk_send=false` to save it as a draft instead, and send it from Listmonk.

The campaign is named after the subject, with "(Reelspan)" added, so you can tell it apart in Listmonk. The result's `url` opens the campaign in your Listmonk admin, and `post_id` is its id.

## Connect a list

You need your Listmonk address, an API user and its token, and the list. Setup takes about two minutes.

1. In Listmonk 4 or later, open **Admin → Users → New**, choose the **API** user type and copy its token.
2. On an older Listmonk, use the admin username and password instead.
3. In the Reelspan dashboard, open **Accounts → Connect account**, choose the profile and Listmonk, and enter your Listmonk address, the user, the token and the list to send to, by name or id.

Reelspan tries the pair as an API token first, then as a username and password, and checks the list exists, before saving it, encrypted.

### With the API

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/accounts/listmonk \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "server": "news.example.com", "user": "reelspan", "token": "...", "list": "Newsletter"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
await reelspan.accounts.connect('my-brand', 'listmonk', {
  server: 'news.example.com',
  user: 'reelspan',
  token: process.env.LISTMONK_TOKEN,
  list: 'Newsletter',
});
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.accounts.connect(
    "my-brand", "listmonk",
    server="news.example.com", user="reelspan", token=os.environ["LISTMONK_TOKEN"], list="Newsletter",
)
```

```json
{ "success": true, "platform": "listmonk", "account": "Newsletter", "reconnected": false }
```

| Field | Required | Also accepted (Upload-Post) |
| --- | --- | --- |
| `server` | Yes. Its address, with a path if Listmonk lives in one; a trailing `/admin` is removed | `instance_url` |
| `user` | Yes. The API user, or the username | `username` |
| `token` | Yes. The API token, or the password | `password` |
| `list` | Yes. The list's name or id | `list_id` |

Connecting again replaces the Listmonk account on that profile. See [Connect with credentials](/api/connect-credentials).

## Example post

A newsletter with one photo:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/photos \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=listmonk" \
  -F "title=New dashboard" \
  -F "listmonk_title=What's new in November" \
  -F "listmonk_description=Hi there,

This month we rebuilt the dashboard around keyboard shortcuts.

Thanks for reading." \
  -F "alt_text=The new dashboard" \
  -F "photos[]=@photo1.jpg"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.photos({
  user: 'my-brand',
  platforms: ['listmonk'],
  title: 'New dashboard',
  photos: [{ data: await readFile('photo1.jpg'), name: 'photo1.jpg', type: 'image/jpeg' }],
  altTexts: ['The new dashboard'],
  extra: {
    listmonk_title: "What's new in November",
    listmonk_description: 'Hi there,\n\nThis month we rebuilt the dashboard around keyboard shortcuts.\n\nThanks for reading.',
  },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.photos(
    "my-brand", ["listmonk"], ["photo1.jpg"], "New dashboard",
    alt_texts=["The new dashboard"],
    extra={
        "listmonk_title": "What's new in November",
        "listmonk_description": "Hi there,\n\nThis month we rebuilt the dashboard around keyboard shortcuts.\n\nThanks for reading.",
    },
)
```

## Fields

| Field | Meaning |
| --- | --- |
| `listmonk_title` | The email's subject. Falls back to the caption's first line. |
| `listmonk_description` | The email's body. Falls back to `description`. |
| `description` | The body, when `listmonk_description` isn't sent. |
| `title` | The caption: its first line is the subject and the whole of it the body, when the fields above aren't sent. |
| `listmonk_send` | `false` saves a draft campaign instead of sending it. Default: sent at once. |
| `listmonk_alt_text` | Alt text for the photos in the email: one text for all, or one per photo. Falls back to `alt_text`. |
| `alt_text` | The alt text for every network that takes it. |

In the dashboard composer, the Listmonk tab has **Save as a draft campaign**. A `first_comment` isn't posted on Listmonk; the result says `"first_comment": "unsupported"` with a warning.

## Limits and behaviour

- **Photos:** up to 10, each up to 20 MB, uploaded to Listmonk's media library. Videos in `photos[]` are left out, with a warning.
- **Campaigns:** a regular HTML campaign to the one connected list. To send to another list, connect it on another profile.
- **Drafts:** a draft answers with a warning, "Saved as a draft campaign in Listmonk".
- **Listmonk versions:** Listmonk 4 and later with an API user; older versions with a username and password.
- **https only:** Reelspan always calls your Listmonk over https.
- **Your server only:** calls go only to the address you named, and never to private network addresses.

## Common errors

| Code | When | Fix |
| --- | --- | --- |
| `INVALID_CREDENTIALS` | Connecting: Listmonk accepted neither the token nor the password | Make an API user under Admin → Users (Listmonk 4+), or check the username and password. |
| `LIST_NOT_FOUND` | Connecting: no list by that name or id. The message lists your lists | Send one of the listed names. |
| `UNSUPPORTED_POST_TYPE` | The request is a video post | Send text or photos to Listmonk. |
| `reauth_required` | Listmonk answered 401 or 403: the token or password changed | Connect again. |
| `file_too_large` | A photo is over 20 MB | Send a smaller photo. |
| `listmonk_error` | Listmonk refused the upload or the campaign. Retried automatically on 5xx | Read `error` for Listmonk's reason. |
| `MISSING_FIELD` | Connecting without one of the four fields | Send all four. |

Errors when connecting come back as a 400 with the code in `error_code`. `UNSUPPORTED_POST_TYPE` refuses the whole request with a 400. Errors when posting are in that network's result. See [Errors](/errors).

Source: https://docs.reelspan.com/networks/listmonk

---

# Async posts

> Send a post with async_upload=true to get a request_id at once, then follow each network's result by polling status or receiving a webhook.

A post request normally waits for the networks to finish, up to 59 seconds. Big videos and slow networks can take longer, and your HTTP client may give up first. Send `async_upload=true` and Reelspan answers straight away with a `request_id`; the post carries on in the background and you read the outcome later.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "platform[]=youtube" \
  -F "title=Launch day" \
  -F "async_upload=true" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['tiktok', 'youtube'],
  title: 'Launch day',
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  async: true,
});
const status = await reelspan.posts.wait(post.request_id);
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video("my-brand", ["tiktok", "youtube"], "launch.mp4", "Launch day", async_upload=True)
status = reelspan.posts.wait(post["request_id"])
```

## What comes back

An async post answers **200** with the request's id and how many networks it went to:

```json
{
  "success": true,
  "message": "Upload initiated successfully in background.",
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "total_platforms": 2
}
```

The same shape comes back when you did not ask for async but the networks were still working after 59 seconds: the request moves to the background on its own, and nothing is lost.

> [!NOTE]
> Check for `results` in the body rather than for a status code. A post that finished in time has `results` keyed by network; a post still running has `message` and `total_platforms` instead. If every network has already finished by the time Reelspan answers, an async request also returns `results`.

Requests that are checked and refused (a missing field, an unknown profile, a file over your plan's size) still fail at once with an HTTP error, async or not. See [Errors](/errors).

## Following the post

### Poll the status

`GET /v1/posts/status?request_id=…` returns the overall `status` and one entry in `results` per network that has finished. Networks still working are not listed yet; `completed` and `total` tell you how far it got.

```bash title="cURL"
curl "https://api.reelspan.com/v1/posts/status?request_id=9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const status = await reelspan.posts.status({ requestId: '9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1' });
```

```python title="Python"
status = reelspan.posts.status(request_id="9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1")
```

`status` is one of:

| Status | Meaning |
| --- | --- |
| `pending` | Accepted, nothing has finished yet (also a scheduled post waiting for its time). |
| `in_progress` | At least one network is working or has finished; others are still going. |
| `completed` | Every network finished and at least one published. Check each result: some may have failed. |
| `failed` | Every network finished and none published. |
| `cancelled` | A scheduled post that was cancelled. |

The full response is on [Post status](/api/post-status).

### How often to poll

Poll every **5 seconds or more**. Each status call counts against your [rate limit](/rate-limits), the same as any other request. A sensible pattern is to wait 5 seconds, then back off towards 15 to 30 seconds for large videos, which can take minutes on networks that process video after upload.

The SDKs' `wait` helpers poll for you until the status is `completed`, `failed` or `cancelled`, or a timeout passes (10 minutes by default). They poll every 3 seconds unless you set `intervalMs` (Node) or `interval` (Python); raise it if you run many posts at once.

```javascript title="Node.js"
const status = await reelspan.posts.wait(requestId, { intervalMs: 10_000, timeoutMs: 900_000 });
```

```python title="Python"
status = reelspan.posts.wait(request_id, timeout=900, interval=10)
```

### Or receive a webhook

Instead of polling, register a webhook and Reelspan sends an `upload_completed` event for **each network** as it finishes, with that network's `success`, `url`, `post_id`, `error` and `error_code`, plus your `request_id`, `job_id` and `external_id`. A post to three networks sends three events. See [Webhooks](/webhooks).

> [!TIP]
> Send your own `request_id` (8 to 100 letters, digits, `_` or `-`) with the post. You know the id before the response arrives, so you can poll it even if the connection drops mid-request. An `external_id` comes back in status, history and webhooks too, for matching posts to your own records.

## Scheduled posts use job_id

A post with `scheduled_date` or `add_to_queue=true` answers **202** with both a `job_id` and a `request_id`, and does not publish until its time. You can read its status with either id:

```bash title="cURL"
curl "https://api.reelspan.com/v1/posts/status?job_id=sched_3Jd9aQ" \
  -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const status = await reelspan.posts.status({ jobId: 'sched_3Jd9aQ' });
```

```python title="Python"
status = reelspan.posts.status(job_id="sched_3Jd9aQ")
```

Until it runs, its status is `pending`. Use the `job_id` to edit or cancel it; see [Scheduling and repeats](/guides/scheduling).

## When a network fails

One network failing never fails the others. Temporary errors on the network's side (timeouts, its own rate limits, 5xx answers) are retried automatically, up to four attempts with growing pauses, before the result is final. A final failure carries an `error_code`: look it up in [Errors](/errors) or [Troubleshooting](/troubleshooting), then send only the failed networks again with [Retry](/api/retry).

Source: https://docs.reelspan.com/guides/async-uploads

---

# Large files

> Send videos over 100 MB with a direct multipart upload to storage, know your plan's file size limit, and post from public URLs, Google Drive or Dropbox links.

A video can reach Reelspan three ways: in the post request itself, as a public URL Reelspan downloads, or uploaded first and referred to by `media_id`. For anything over 100 MB, upload it first with a **direct upload**: the file goes straight to storage in parts, and the post request stays small.

## Size limits

| Plan | Largest video |
| --- | --- |
| Free | 0.5 GB |
| Starter | 1 GB |
| Pro | 2 GB |
| Agency | 4 GB |
| Scale | 8 GB |

The plan limit applies to videos however they arrive (file, URL or direct upload). Other files have fixed limits: photos up to **20 MB** each and PDF documents up to **100 MB**. A file over the limit is refused with **413** and `error_code: FILE_TOO_LARGE`.

Separately, a single request sent to the API can carry at most **100 MB**, so a file bigger than that must use a direct upload (or a URL). Each network also has its own limits, checked when Reelspan publishes there; see [Video requirements](/limits/video).

## With the SDKs: nothing to do

The Node.js and Python SDKs switch to a direct upload on their own for files of **90 MB or more**, upload the parts three at a time with retries per part, then post with the resulting `media_id`. You pass the file as usual:

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['youtube'],
  title: 'Full keynote',
  video: { data: await readFile('keynote.mp4'), name: 'keynote.mp4', type: 'video/mp4' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.posts.video("my-brand", ["youtube"], "keynote.mp4", "Full keynote")
```

To upload once and post later (or several times), call `media.upload` and keep the `media_id`. It takes an `onProgress` (Node) / `on_progress` (Python) callback for a progress bar:

```javascript title="Node.js"
const media = await reelspan.media.upload(
  { data: await readFile('keynote.mp4'), name: 'keynote.mp4', type: 'video/mp4' },
  { kind: 'video', onProgress: (sent, total) => console.log(`${Math.round((sent / total) * 100)}%`) },
);
await reelspan.posts.video({ user: 'my-brand', platforms: ['youtube'], title: 'Full keynote', videoMediaId: media.media_id });
```

```python title="Python"
media = reelspan.media.upload("keynote.mp4", kind="video", on_progress=lambda sent, total: print(f"{sent * 100 // total}%"))
reelspan.posts.video("my-brand", ["youtube"], title="Full keynote", video_media_id=media["media_id"])
```

The 90 MB threshold can be changed with `directUploadBytes` (Node) or `direct_upload_bytes` (Python) when you create the client.

## Direct upload by hand

Three steps: start, send the parts, complete.

### 1. Start

Tell Reelspan the kind and size of the file. It checks the size against your plan and answers with one signed URL per part.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/media/uploads \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "video", "size_bytes": 734003200, "filename": "keynote.mp4"}'
```

```json
{
  "success": true,
  "kind": "video",
  "media_id": "med_…",
  "part_size": 8388608,
  "parts": [
    { "part_number": 1, "url": "https://…" },
    { "part_number": 2, "url": "https://…" }
  ],
  "expires_in": 3600
}
```

Parts are at least 8 MB, and there are never more than 1,000 of them. The part URLs are valid for an hour (`expires_in`, in seconds), and an upload that is not completed within a day is forgotten.

### 2. Send the parts

`PUT` each part's bytes to its URL: part `n` is the bytes from `(n - 1) × part_size`, `part_size` long (the last part is whatever is left). Each URL is signed for its part's exact length, so a body of any other size is refused. Keep the `ETag` header of every response.

```bash title="cURL"
# part 1 of a file split with: split -b 8388608 -d keynote.mp4 part_
curl -X PUT --upload-file part_00 "$PART_1_URL" -D - | grep -i etag
```

Parts can go in parallel and in any order. If one fails, send that part again to the same URL.

### 3. Complete

Send every part number with its ETag. Reelspan then reads the stored file's real size and first bytes, refuses it if it is not the kind you declared or is over your limit, and returns the `media_id` ready to use.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/media/uploads/med_…/complete \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parts": [{"part_number": 1, "etag": "\"9b2cf5…\""}, {"part_number": 2, "etag": "\"41d8cd…\""}]}'
```

```json
{ "success": true, "media_id": "med_…", "kind": "video", "content_type": "video/mp4", "size_bytes": 734003200, "duration_seconds": 1834.2 }
```

Then post it with `video_media_id` (or `photo_media_ids[]` for photos, `document_media_id` for a PDF):

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=youtube" \
  -F "title=Full keynote" \
  -F "video_media_id=med_…"
```

To give up on an upload part-way, `POST /v1/media/uploads/{media_id}/abort` discards the parts already sent.

| Error | When |
| --- | --- |
| `FILE_TOO_LARGE` (413) | `size_bytes`, or the stored file, is over your plan's limit. |
| `EMPTY_FILE` (400) | `size_bytes` is missing or zero, or nothing was stored. |
| `PARTS_REQUIRED` (400) | The complete call had no valid `parts`. |
| `UNSUPPORTED_MEDIA` / `WRONG_MEDIA_KIND` (400) | The stored file isn't a supported type, or isn't the `kind` you declared. |
| `UPLOAD_NOT_FOUND` (404) | The `media_id` is unknown or the upload expired. Start again. |

## Small files: one request

Under 100 MB you can send the file in the post itself (`video=@launch.mp4`), or upload it once with `POST /v1/media/upload` (a multipart field named `file`, and `?kind=video`, `photo` or `document`) to get a `media_id`. See [Upload media](/api/upload-media).

## Public URLs, Google Drive and Dropbox

Any `video`, `photos[]` or `document` value can be a public `https://` URL instead of a file. Reelspan downloads it before the post is accepted, so the same size limits apply and a failed download refuses the request with `URL_FETCH_FAILED`.

- Only `https://` URLs are fetched, with up to three redirects. Addresses on private networks are refused.
- **Google Drive** share links (`drive.google.com/file/d/…` and `drive.google.com/open?id=…`) and **Dropbox** share links are turned into direct downloads for you. The file must be shared so that anyone with the link can open it.
- One request can fetch at most 100 media URLs in total (`TOO_MANY_MEDIA_URLS`).

> [!TIP]
> Posting the same large video to several profiles, or again later? Upload it once and reuse the `media_id`. Media that no post uses is deleted after a day, and the media of a finished post after a retention period, unless you keep it in the [media library](/api/library).

Source: https://docs.reelspan.com/guides/large-files

---

# Retrying safely

> Use an Idempotency-Key header or your own request_id so a post retried after a timeout or network error is never published twice.

A network error can hide whether your post went out: the request may have reached Reelspan and the answer been lost on the way back. Retrying blindly could publish the same video twice. Send an `Idempotency-Key` header on every post, and a retry with the same key returns the first request's result instead of posting again.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Idempotency-Key: launch-2026-12-01" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "title=Launch day" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
// the SDK adds a key on its own; pass one to make retries safe across restarts of your process
await reelspan.posts.video({ user: 'my-brand', platforms: ['tiktok'], title: 'Launch day', video: 'https://example.com/launch.mp4', idempotencyKey: 'launch-2026-12-01' });
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.posts.video("my-brand", ["tiktok"], "https://example.com/launch.mp4", "Launch day", idempotency_key="launch-2026-12-01")
```

## How the key works

The key is any string you choose, up to 200 characters (longer keys are cut to 200). `X-Idempotency-Key` is accepted as another name for the header, and `X-Request-Id` as a third (see [Your own request_id](#your-own-request-id)); when more than one is sent, `Idempotency-Key` wins, then `X-Idempotency-Key`. It works on the four posting endpoints: `POST /v1/posts/video`, `/photos`, `/text` and `/document`.

| You send the same key… | What happens |
| --- | --- |
| Within 24 hours of the first request | No new post. You get the first request's current state: its `results` if every network has finished, the background shape (`message`, `request_id`, `total_platforms`) if it is still running, or the 202 with `job_id` if it is scheduled. The response carries the header `Idempotent-Replayed: true` and `"idempotent_replay": true` in the body. |
| While the first request is still being received or checked | **409** with `error_code: IDEMPOTENCY_KEY_IN_USE`. Wait a few seconds and send it again. |
| After 24 hours | The key is free again, and the request is treated as a new post. |
| On a different kind of post | Keys are kept separately for video, photo, text and document posts, so the same string on `/posts/video` and `/posts/text` makes two posts. |

Keys belong to your workspace: every API key in it shares them, and no other workspace can see or collide with them.

> [!WARNING]
> Reelspan does not compare the body of a replayed request with the first one. A second request with the same key and a different caption, video or network list gets the **first** request's result, and nothing new is posted. Use a new key for every distinct post, for example one derived from your own record id.

A request that is refused outright (a 4xx such as a missing field or a file too large) creates no post, so its key is not used up: fix the request and send it again with the same key.

## Your own request_id

You can also choose the post's `request_id` yourself: 8 to 100 letters, digits, `_` or `-`, sent as a form field (or JSON field on text posts). Because you know it before sending, you can poll [Post status](/api/post-status) with it even if the response never arrived.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user": "my-brand", "platform": ["x", "bluesky"], "title": "We are live", "request_id": "order-58213-announce"}'
```

The `X-Request-Id` header does the same, for clients (such as ones written for Upload-Post) that send the id as a header. It must have the same shape, 8 to 100 letters, digits, `_` or `-`; anything else (a proxy's own trace id, for example) is ignored. A `request_id` form field wins over the header. When the request has no `Idempotency-Key`, the header's value is also used as the idempotency key, so a repeat within 24 hours gets the first answer back rather than a 409.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text   -H "Authorization: Bearer $REELSPAN_API_KEY"   -H "X-Request-Id: order-58213-announce"   -H "X-External-Id: order-58213"   -H "Content-Type: application/json"   -d '{"user": "my-brand", "platform": ["x", "bluesky"], "title": "We are live"}'
```

`X-External-Id` is the header form of the `external_id` field (your own reference, up to 255 characters, returned in history, status and webhooks); the field wins when both are sent.

A `request_id` can be used once, ever. Sending it again is refused with **409** `REQUEST_ID_IN_USE` and never posts twice; read the existing request's status instead. This is stricter than `Idempotency-Key`, which replays the result for you, so the two work well together: the key for automatic retries, your own `request_id` for looking a post up later.

## Retrying in your own code

Retry on network errors, **408**, **409** `IDEMPOTENCY_KEY_IN_USE`, **429** and **5xx**, keeping the same key, with a growing pause. On a 429, wait for the `Retry-After` seconds. Don't retry other 4xx answers: they will fail the same way.

```bash title="cURL"
for attempt in 1 2 3 4 5; do
  code=$(curl -s -o out.json -w "%{http_code}" -X POST https://api.reelspan.com/v1/posts/video \
    -H "Authorization: Bearer $REELSPAN_API_KEY" \
    -H "Idempotency-Key: launch-2026-12-01" \
    -F "user=my-brand" -F "platform[]=tiktok" -F "title=Launch day" -F "video=@launch.mp4")
  case "$code" in 408|409|429|5*|000) sleep $((2 ** attempt)) ;; *) break ;; esac
done
```

## The SDKs do it for you

The Node.js and Python SDKs give every post its own random key and reuse it across their automatic retries. They retry network errors, 408, 409, 429 and 5xx (twice by default, set with `maxRetries` / `max_retries`), honour `Retry-After`, and only retry a POST when it carries a key. You don't need to do anything.

The automatic key lives only for that one call. If your own code catches an error and calls `posts.video` again, that is a new call with a new key. To make retries safe across separate calls, or across a restart of your worker, pass your own `idempotencyKey` (Node) / `idempotency_key` (Python), as in the example above.

> [!NOTE]
> Networks that fail temporarily on their side are retried by Reelspan itself, and a network that failed for good can be sent again with [Retry](/api/retry) without uploading the media again. Neither needs a new post request.

Source: https://docs.reelspan.com/guides/idempotency

---

# Test mode

> Use an rs_test_ key to run posts through every check without publishing or using uploads, and the sandbox network to rehearse results and failures.

A test key starts with `rs_test_` instead of `rs_live_`. Posts made with it go through every check a live post gets, then stop short of the network: nothing is published, and nothing counts against your monthly uploads. Use it while you build, in CI, and in staging.

Create one in the dashboard under **Developers → API keys**, choosing a test key. It works with the same base URL, SDKs and workspace as your live keys.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user": "my-brand", "platform": ["x", "linkedin"], "title": "Only a test"}'
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';

const reelspan = new Reelspan({ apiKey: process.env.REELSPAN_TEST_KEY });
const post = await reelspan.posts.text({ user: 'my-brand', platforms: ['x', 'linkedin'], title: 'Only a test' });
```

```python title="Python"
import os
from reelspan import Reelspan

reelspan = Reelspan(api_key=os.environ["REELSPAN_TEST_KEY"])
post = reelspan.posts.text("my-brand", ["x", "linkedin"], "Only a test")
```

## What a test post does

Everything up to the moment of publishing is real:

- Your fields are validated, media is uploaded or downloaded and checked for type and size against your plan, and network rules that run before publishing apply (for example YouTube needs a title, Pinterest a board).
- The profile must exist and the key must be allowed to use it.
- Each network must have an account connected to the profile and in good standing, as for a live post. A network with no account is skipped with `profile_platform_mapping_invalid`, exactly as it would be live.
- Scheduling, the queue and repeats work: a scheduled test post waits for its time, then is simulated.

Then, instead of sending it to the network, Reelspan marks each network as published:

```json
{
  "success": true,
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "results": {
    "x": { "success": true, "url": null, "post_id": "test_post_…", "test": true, "message": "Test mode: not sent to the network" },
    "linkedin": { "success": true, "url": null, "post_id": "test_post_…", "test": true, "message": "Test mode: not sent to the network" }
  }
}
```

- `url` is `null` and `post_id` starts with `test_`, because no real post exists.
- [Post status](/api/post-status) for the request includes `"test": true`.
- The post appears in your history and dashboard like any other, and `upload_completed` [webhooks](/webhooks) are sent for it, so you can test your webhook handler end to end.
- No upload is counted, so test posts work past the Free plan's monthly limit. Cancelling a scheduled test post refunds nothing because nothing was taken.

## What is not simulated

A test post stops before anything network-specific happens, so it can't tell you whether the network would accept the post. These are only found out by a live post:

- the network's own limits on size, length, duration and format, and any processing errors;
- whether the connected account's token still works (Reelspan only checks the account is marked active);
- network options such as a TikTok privacy level the account can't use;
- first comments, which are never sent.

## The sandbox network

`sandbox` is a pretend network that needs no connected account. Add it to `platform[]` on video, photo or text posts. It reads the media like a real network would and "publishes" at once.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_TEST_KEY" \
  -F "user=my-brand" \
  -F "platform[]=sandbox" \
  -F "title=Pipeline check" \
  -F "video=@launch.mp4"
```

With a **test key**, a sandbox post is simulated like any other network: `url` is `null`, and nothing counts.

With a **live key**, the sandbox runs for real, and these fields let you rehearse outcomes:

| Field | Effect |
| --- | --- |
| *(none)* | Succeeds with a URL like `https://sandbox.reelspan.com/p/…`, plus `bytes_received`, `caption` and, for photos, `photos_received` in its result. |
| `sandbox_fail=true` | Fails for good with `error_code: sandbox_rejected`. Use it to test your failure handling and [Retry](/api/retry). |
| `sandbox_fail=retryable` | Fails with a temporary error (`sandbox_unavailable`), which Reelspan retries automatically before reporting it as failed. |
| `sandbox_delay_ms` | Waits this long (up to 120,000 ms) before finishing, to test async posts and polling. |

> [!IMPORTANT]
> A sandbox post made with a live key counts as an upload against your plan, like any other network. Use a test key when you only want to check the request.

## Limits

- A workspace can send **500 test posts a day** (each request counts once, whatever the number of networks). The count resets at midnight UTC. Past it, test posts get **429** with `error_code: TEST_LIMIT`.
- Test keys share the workspace's [rate limit](/rate-limits) with its live keys.
- A test key only changes how posts are published. Every other call it makes is real: creating or deleting a profile, connecting an account, setting a webhook or using AI caption credits works exactly as with a live key.
- Dashboard sessions and MCP clients signed in with OAuth always post live.

Source: https://docs.reelspan.com/guides/test-mode

---

# Scheduling and repeats

> Schedule a post for a set time in any timezone, add it to a profile's queue, repeat it daily, weekly or monthly, and edit, cancel or hold it for approval.

Every posting endpoint takes the same timing fields. Leave them out and the post goes now; add `scheduled_date` for a set time, `add_to_queue=true` for the profile's next free slot, or `repeat_every` and `repeat_times` for a series.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "platform[]=instagram" \
  -F "title=Launch day" \
  -F "scheduled_date=2026-12-01T09:00:00" \
  -F "timezone=Europe/London" \
  -F "video=@launch.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['tiktok', 'instagram'],
  title: 'Launch day',
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  scheduledDate: '2026-12-01T09:00:00',
  timezone: 'Europe/London',
});
console.log(post.job_id);
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video("my-brand", ["tiktok", "instagram"], "launch.mp4", "Launch day",
                            scheduled_date="2026-12-01T09:00:00", timezone="Europe/London")
print(post["job_id"])
```

A scheduled post answers **202** at once:

```json
{ "success": true, "job_id": "sched_3Jd9aQ…", "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1", "scheduled_date": "2026-12-01T09:00:00.000Z" }
```

Keep the `job_id`: it is how you edit or cancel the post. `scheduled_date` in the answer is always UTC.

## The time and the timezone

- `scheduled_date` is ISO 8601. With an offset or `Z` (`2026-12-01T09:00:00+01:00`, `2026-12-01T08:00:00Z`) that exact moment is used and `timezone` is ignored for it.
- Without an offset (`2026-12-01T09:00:00`, or a bare date, which means midnight), the time is read in `timezone`, an IANA name such as `America/New_York` or `Asia/Kolkata`. Without `timezone`, the workspace's [default time zone](/api/preferences) is used, and UTC when none is set. Daylight-saving changes are handled.
- The time must be in the future and within 365 days. An unknown timezone or an unreadable date is refused with 400.

The media is uploaded and checked when you schedule, and the monthly upload count is taken then too (one per network). Whether each network's account is connected is checked when the post runs, so you can schedule for an account you will connect later; if it is still missing at that time, that network is skipped with `profile_platform_mapping_invalid`.

## The queue

Send `add_to_queue=true` instead of a date, and the post takes the profile's next open posting slot within the next 30 days. The answer is the same 202, with the chosen time in `queue_slot`. `max_posts_per_slot` (1 to 100) overrides how many posts one slot may hold for this request. `scheduled_date` and `add_to_queue` can't be used together.

Set a profile's slots, days and capacity with the queue endpoints; see [Queue](/api/queue). A full queue answers 400 with `QUEUE_FULL`.

## Repeating posts

`repeat_every` (`day`, `week` or `month`) with `repeat_times` (2 to 30, the first post included) creates the whole series at once:

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user": "my-brand", "platform": ["x", "linkedin"], "title": "Office hours are open: reply with your questions",
       "scheduled_date": "2026-12-07T16:00:00", "timezone": "America/New_York",
       "repeat_every": "week", "repeat_times": 6}'
```

```javascript title="Node.js"
await reelspan.posts.text({
  user: 'my-brand',
  platforms: ['x', 'linkedin'],
  title: 'Office hours are open: reply with your questions',
  scheduledDate: '2026-12-07T16:00:00',
  timezone: 'America/New_York',
  repeatEvery: 'week',
  repeatTimes: 6,
});
```

```python title="Python"
reelspan.posts.text("my-brand", ["x", "linkedin"], "Office hours are open: reply with your questions",
                    scheduled_date="2026-12-07T16:00:00", timezone="America/New_York",
                    repeat_every="week", repeat_times=6)
```

- The first post is at `scheduled_date` (or the queue slot, or now if you give neither). Each later one keeps the same local time in the timezone, so a 4 pm post stays at 4 pm across daylight-saving changes.
- A monthly series on the 29th, 30th or 31st falls on the last day of shorter months.
- The last post must be within 365 days.
- Every post in the series is its own scheduled post, with its own `job_id`, listed in the response under `repeat.posts`, alongside `repeat.series_id`. Each can be edited or cancelled on its own.
- Each post counts as an upload per network. On a plan with a monthly limit, a series that would go over it is refused up front with 429 `USAGE_LIMIT`.

## Listing, editing and cancelling

| Task | Call |
| --- | --- |
| List upcoming posts | `GET /v1/scheduled` (filter with `profile_username`, `from`, `to`; page with `limit` up to 200 and `offset`) |
| Read one | `GET /v1/scheduled/{job_id}` |
| Change the time or text | `PATCH /v1/scheduled/{job_id}` |
| Cancel | `DELETE /v1/scheduled/{job_id}` |

```bash title="cURL"
curl -X PATCH https://api.reelspan.com/v1/scheduled/sched_3Jd9aQ \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_date": "2026-12-02T09:00:00", "timezone": "Europe/London", "fields": {"tiktok_title": "Launch day, take two"}}'
```

```javascript title="Node.js"
await reelspan.scheduled.edit('sched_3Jd9aQ', { scheduled_date: '2026-12-02T09:00:00', timezone: 'Europe/London', fields: { tiktok_title: 'Launch day, take two' } });
await reelspan.scheduled.cancel('sched_3Jd9aQ', { withLaterRepeats: true });
```

```python title="Python"
reelspan.scheduled.edit("sched_3Jd9aQ", scheduled_date="2026-12-02T09:00:00", timezone="Europe/London", fields={"tiktok_title": "Launch day, take two"})
reelspan.scheduled.cancel("sched_3Jd9aQ", with_later_repeats=True)
```

- **Edit:** change `scheduled_date`, `timezone`, `title`, `description`, or any other field through `fields` (a `null` value removes a field). The profile, networks and media can't change (`user`, `platform[]`, `video`, `photos[]` and `request_id` are refused); cancel and post again for that. A new time must be at least a minute ahead. Moving a queued post to a set time takes it out of the queue.
- **Cancel:** the post is stopped and its upload count refunded. Add `?series=rest` (SDK: `withLaterRepeats` / `with_later_repeats`) to also cancel the later posts of its repeating series.
- **Too late:** once a post has started publishing, or is due within a minute, both calls answer **409** `scheduled_post_in_progress`.

More detail is on [Scheduled posts](/api/scheduled-posts).

## Holding posts for client approval

An agency can put scheduled posts in an approval link and send it to a client, who opens it without an account and approves each post or asks for changes.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/approval-links \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "job_ids": ["sched_3Jd9aQ", "sched_8kLw2P"], "title": "December posts", "expires_in_days": 14}'
```

- A post in a link **does not publish until the client approves it**. When its time comes and it is not approved, it waits.
- Approving a post whose time has already passed publishes it at once.
- A post held for approval can still be edited after its time has passed. Editing a post that was approved, or had changes requested, sends it back to the client for approval.
- Deleting the link lets its posts publish as scheduled.
- A link holds up to 100 posts of one profile, and is valid for `expires_in_days` (1 to 60, default 14). Putting a post in a new link takes it out of any earlier one.

See [Approval links](/api/approval-links) for the full calls.

## Seeing scheduled posts run

When a scheduled post runs, it behaves like any other post: each network's result appears in [Post status](/api/post-status) (by `job_id` or `request_id`) and in an `upload_completed` [webhook](/webhooks).

Source: https://docs.reelspan.com/guides/scheduling

---

# AI content labels

> Mark a post as AI-generated with is_ai_generated and Reelspan sets the label on TikTok, YouTube and Threads, plus TikTok's brand content disclosure.

Some networks let you label a post as made or altered with AI. Send `is_ai_generated=true` with any post and Reelspan sets that label on every network in the request that supports one through its API. Today that is TikTok, YouTube and Threads.

```bash title="cURL"
curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "platform[]=youtube" \
  -F "platform[]=threads" \
  -F "title=What our city looks like in 2050" \
  -F "is_ai_generated=true" \
  -F "video=@city-2050.mp4"
```

```javascript title="Node.js"
import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['tiktok', 'youtube', 'threads'],
  title: 'What our city looks like in 2050',
  video: { data: await readFile('city-2050.mp4'), name: 'city-2050.mp4', type: 'video/mp4' },
  extra: { is_ai_generated: 'true' },
});
```

```python title="Python"
from reelspan import Reelspan

reelspan = Reelspan()
reelspan.posts.video("my-brand", ["tiktok", "youtube", "threads"], "city-2050.mp4", "What our city looks like in 2050",
                     extra={"is_ai_generated": "true"})
```

Boolean fields take `true`, `1` or `yes`.

## What each network gets

| Network | Field Reelspan sets | Your fields | Applies to |
| --- | --- | --- | --- |
| TikTok | `is_aigc` | `is_ai_generated`, `tiktok_is_ai_generated` or `is_aigc` | Videos posted directly. Not photo posts, and not videos sent to the TikTok inbox (`post_mode=MEDIA_UPLOAD`). |
| YouTube | `status.containsSyntheticMedia` | `containsSyntheticMedia` or `is_ai_generated` | Every video. |
| Threads | `is_made_with_ai` | `is_ai_generated` or `threads_is_made_with_ai` | Video, photo, carousel and text posts. |

How the fields combine:

- **TikTok and Threads:** the label is set if any of the listed fields is true. A network field can't switch off a label that `is_ai_generated=true` turned on; to label only some networks, leave `is_ai_generated` out and use the network fields.
- **YouTube:** `containsSyntheticMedia` wins over `is_ai_generated` when both are sent, so `containsSyntheticMedia=false` keeps the YouTube label off. When neither is sent, Reelspan leaves the field unset.

## Networks without an AI label

Every other network gets no label from Reelspan: Instagram, Facebook, X, LinkedIn, Pinterest, Bluesky and the rest either have no AI-disclosure field in the API Reelspan uses, or Reelspan doesn't set it yet. `is_ai_generated` is ignored for them, without a warning. If a network's rules ask you to disclose AI content and it has no API field, say so in the caption.

## TikTok: commercial content disclosure

TikTok also asks creators to disclose posts that promote a brand. Two fields set it on direct video and photo posts:

| Field | TikTok label |
| --- | --- |
| `brand_organic_toggle=true` | You are promoting yourself or your own business ("Promotional content"). |
| `brand_content_toggle=true` | Branded content: a paid partnership promoting a third party. |

TikTok doesn't allow branded content to be private, so don't combine `brand_content_toggle=true` with `privacy_level=SELF_ONLY`. See [TikTok](/networks/tiktok) for the other TikTok fields.

## Scheduled and repeated posts

The fields are stored with the post, so a scheduled or repeating post is labelled when it publishes. You can add or remove them on a scheduled post with `PATCH /v1/scheduled/{job_id}` and `fields`; see [Scheduling and repeats](/guides/scheduling).

Source: https://docs.reelspan.com/guides/ai-content-labeling

---

# Errors

> Every error the Reelspan API returns: the error body, HTTP statuses, request error codes and per-network result codes for TikTok, YouTube, Instagram and more.

There are two kinds of error, and a client should handle both:

1. **The request is refused.** You get an HTTP error status and an error body. Nothing was posted.
2. **The request is accepted, but a network fails.** The request succeeds, and that network's entry in `results` has `success: false` with an `error_code`. The other networks are not affected.

## The error body

A refused request answers with this JSON:

```json
{
  "success": false,
  "message": "This API key does not have the \"publish\" scope",
  "error_code": "INSUFFICIENT_SCOPE"
}
```

- Branch on `error_code`. The `message` is written for people and can change.
- Request error codes are UPPER_CASE; network result codes are lower_case.
- Some errors add fields: `usage` on a monthly limit, `platform` when one network's rule refused the request, `invalid_platforms` when no requested network can be used, `api_url` on a 421.
- A few errors have no `error_code`, only `message` (for example an unknown route, an invalid timezone or a key that is wrong). Fall back on the HTTP status.
- Server errors use `error` instead of `message`: `{ "success": false, "error": "Internal server error" }`.

## HTTP statuses

| Status | Meaning | What to do |
| --- | --- | --- |
| 200 | Done, or moved to the background (see [Async posts](/guides/async-uploads)). Check each network's `success`. | |
| 201 | Created (approval links). | |
| 202 | Scheduled or queued; the body has a `job_id`. | |
| 400 | The request is invalid: a missing or wrong field, an unknown network, an unsupported file. | Fix the request; retrying won't help. |
| 401 | No key, a wrong key, a revoked or expired one. | Check the `Authorization: Bearer` header. |
| 403 | The key can't do this: a missing scope, a profile it isn't allowed, a plan limit, or a suspended workspace. | Use another key or plan. |
| 404 | No such profile, post, job or media, or the key can't see it. | |
| 409 | A conflict: the request is still running, the id is taken, or a scheduled post is already publishing. | See the code. |
| 413 | A file is larger than your plan or the library allows. | Send a smaller file or upgrade. |
| 421 | An API key was sent to the dashboard's address instead of the API. | Use `https://api.reelspan.com/v1`. |
| 429 | Too many requests, too many failed keys, or a monthly limit reached. | Wait for `Retry-After` when present. |
| 500 | Something broke on Reelspan's side. | Retry with the same `Idempotency-Key`. |
| 502 | A network didn't answer a lookup Reelspan made for you (for example TikTok creator info), or the AI provider failed. | Retry later. |
| 503 | Reelspan is briefly in maintenance, or a feature isn't set up on this server. | Wait for `Retry-After`. |

## Request error codes

### Authentication and access

| Code | Status | Meaning |
| --- | --- | --- |
| `INSUFFICIENT_SCOPE` | 403 | The key lacks the scope this call needs (`publish`, `read`, `profiles`, `analytics` or `webhooks`). |
| `PROFILE_FORBIDDEN` | 403 | The key is limited to other profiles, or an account-wide webhook was set with a profile-limited key. |
| `RATE_LIMITED` | 429 | Too many requests in the current window; see [Rate limits](/rate-limits). Also too many credential connection attempts or manual webhook sends. |
| `AUTH_RATE_LIMITED` | 429 | Too many failed keys from your IP address (10 in 5 minutes). `Retry-After: 300`. |
| `USE_API_HOST` | 421 | An API key was sent to `app.reelspan.com`. The body's `api_url` is where it belongs. |
| `WORKSPACE_SUSPENDED` | 403 | The workspace is suspended. Contact [support](/support). |
| `USER_SUSPENDED` | 403 | The signed-in user (MCP with OAuth) is suspended. |
| `TWO_FACTOR_REQUIRED` | 401 | Dashboard sessions only: enter the authenticator code first. |
| `MAINTENANCE` | 503 | Reelspan is under maintenance. Retry after `Retry-After` seconds. |

### Posting

| Code | Status | Meaning |
| --- | --- | --- |
| `INVALID_REQUEST` | 400 | A field is missing or malformed, or a network's own rule failed before posting (YouTube needs a title, Pinterest a `pinterest_board_id`, Reddit a `reddit_subreddit`; the body names the `platform`). |
| `INVALID_PLATFORM` | 400 | A name in `platform[]` isn't a network Reelspan posts to. |
| `UNSUPPORTED_POST_TYPE` | 400 | A network doesn't take this kind of post (for example text to Instagram, or a document anywhere but LinkedIn). |
| `TITLE_REQUIRED` | 400 | Text and document posts need `title`. |
| `MEDIA_REQUIRED` | 400 | The post needs a video, photos or a PDF (file, URL or media id). |
| `INVALID_MULTIPART` | 400 | The body isn't valid `multipart/form-data`, or has too many fields or files, or a field that is too long. |
| `TOO_MANY_MEDIA_URLS` | 400 | More than 100 media URLs in one request. |
| `QUEUE_FULL` | 400 | `add_to_queue`: the profile's queue has no free slot in the next 30 days. |
| `USAGE_LIMIT` | 429 | A repeating series would go over your monthly uploads. |
| `TEST_LIMIT` | 429 | A [test key](/guides/test-mode) workspace sent 500 test posts today. |
| `REQUEST_ID_IN_USE` | 409 | Your `request_id` has been used before. |
| `IDEMPOTENCY_KEY_IN_USE` | 409 | The first request with this `Idempotency-Key` is still running. Retry in a few seconds. See [Retrying safely](/guides/idempotency). |

A request that would go over the monthly upload limit is refused with **429** and the current `usage` (`count`, `limit`, `last_reset`) in the body. When none of the requested networks can be used (none connected, all needing reconnection), the request is refused with **400** and `invalid_platforms`, giving the reason for each.

### Media

| Code | Status | Meaning |
| --- | --- | --- |
| `FILE_TOO_LARGE` | 413 | Over your plan's video size, 20 MB for a photo or 100 MB for a PDF. See [Large files](/guides/large-files). |
| `UNSUPPORTED_MEDIA` | 400 | Not a file type Reelspan takes (SVG, BMP and TIFF, for example). |
| `WRONG_MEDIA_KIND` | 400 | A photo where a video was expected, or the other way round. |
| `EMPTY_FILE` | 400 | The file is empty. |
| `URL_FETCH_FAILED` | 400 | Reelspan couldn't download the media URL (not https, not public, a private address, an error or too many redirects). |
| `MEDIA_NOT_FOUND` | 400 / 404 | A `media_id` doesn't exist, belongs to another workspace, is the wrong kind, or was deleted. |
| `UPLOAD_NOT_FOUND` | 404 | A direct upload's id is unknown or expired. |
| `PARTS_REQUIRED` | 400 | Completing a direct upload without its `parts`. |
| `LIBRARY_FULL` | 413 | The media library has no room left on your plan. |

### Scheduling, retries and approvals

| Code | Status | Meaning |
| --- | --- | --- |
| `scheduled_post_in_progress` | 409 | The scheduled post is publishing or due within a minute; it can't be edited or cancelled. |
| `NOTHING_TO_RETRY` | 409 | No network of this post failed (or the ones you named didn't). |
| `retry_media_expired` | 404 | The post's media has been deleted; post it again with the file. |
| `NOT_FOUND` | 404 | No such request, job or posts, or the key can't see them. |
| `NOT_SCHEDULED` | 400 / 409 | Only scheduled posts can go in an approval link; or the post was already published or cancelled. |
| `COMMENT_REQUIRED` | 400 | Asking for changes on an approval link needs a note. |

### Profiles, accounts and connecting

| Code | Status | Meaning |
| --- | --- | --- |
| `PROFILE_NOT_FOUND` | 404 | No profile with this username in your workspace. |
| `PROFILE_LIMIT_REACHED` | 403 | Your plan's profile count is used up. See [Plans and limits](/limits/plans). |
| `PROFILE_EXISTS` | 409 | A profile with this username already exists. |
| `INVALID_USERNAME` / `INVALID_DISPLAY_NAME` | 400 | The profile's username or display name isn't allowed. |
| `profile_platform_mapping_invalid` | 404 | The profile has no account on this network (Pinterest boards, TikTok creator info). |
| `reauth_required` | 409 | The account must be reconnected (TikTok creator info). |
| `tiktok_unavailable` | 502 | TikTok didn't answer the creator info lookup. |
| `NOT_OAUTH` | 400 | The network connects with credentials, not OAuth: use the hosted connect page. |
| `UNSUPPORTED_PLATFORM` | 400 | The network can't be connected through OAuth. |
| `PROVIDER_NOT_CONFIGURED` | 400 | The network's OAuth app isn't set up on this server. |
| `ACCESS_DENIED` | 403 | The white-label connect link is read-only or doesn't offer this network. |
| `INVALID_WEBHOOK` | 400 | The webhook URL isn't allowed (not https, or a private address) or an event name is unknown. |

When connecting with credentials (`POST /v1/accounts/{platform}`), a refusal from the network comes back as **400** with the network's code in upper case, such as `INVALID_TOKEN`, `INVALID_CREDENTIALS`, `INVALID_WEBHOOK` or `INVALID_SERVER`, or **403** `PLATFORM_DISABLED`.

A browser connect flow (OAuth or the hosted connect page) can't answer with JSON, so it sends the person back to your redirect with `connect_status=error`, an `error_code` (`INVALID_STATE` for an expired link, `ACCESS_DENIED`, `CONNECTION_FAILED`, `NOT_SUPPORTED`, `RATE_LIMITED`, `WORKSPACE_SUSPENDED` or `PROFILE_NOT_FOUND`) and usually an `error_description`. A person who cancels comes back with `connect_status=cancelled`.

### AI captions

| Code | Status | Meaning |
| --- | --- | --- |
| `AI_CREDITS_EXHAUSTED` | 429 | No AI caption credits left this month. |
| `NOTHING_TO_ADAPT` | 400 | Nothing to write captions from: add a video, photos or a caption. |
| `VIDEO_TOO_LONG` | 400 | Videos up to 5 minutes can be analysed. |
| `AI_PROVIDER_ERROR` / `AI_BAD_OUTPUT` | 502 | The AI provider failed or answered with something unusable. Retry; no credit is charged. |
| `AI_NOT_CONFIGURED` | 503 | AI captions aren't set up on this server. |

## Network result codes

Each network in `results` (and in [Post status](/api/post-status) and `upload_completed` webhooks) has its own outcome:

```json
{
  "tiktok": { "success": true, "url": "https://www.tiktok.com/@mybrand/video/7441…", "post_id": "7441…" },
  "instagram": { "success": false, "error": "Instagram could not process the video: ERROR", "error_code": "instagram_processing_failed" },
  "x": { "success": false, "skipped": true, "skip_reason": "profile_platform_not_configured", "error": "Profile my-brand has no X account configured", "error_code": "profile_platform_mapping_invalid" }
}
```

A failed network has `error` (for people) and `error_code` (for code). A network that was never tried also has `skipped: true` and a `skip_reason`. Failures that were temporary on the network's side (its 5xx answers, its rate limits, timeouts) are retried automatically, up to four attempts in all, before the result is final.

Many codes are built from what the network said: `tiktok_<TikTok's code>`, `youtube_<YouTube's reason>`. Treat any code you don't know by its prefix and the `error` text.

### Any network

| Code | Meaning | Fix |
| --- | --- | --- |
| `reauth_required` | The network refused the account's access (revoked, expired or missing a permission). The account is marked for reconnection and a `social_account_reauth_required` webhook is sent. | Reconnect the account, then [Retry](/api/retry). |
| `profile_platform_mapping_invalid` | Skipped: the profile has no active account on this network (`skip_reason: profile_platform_not_configured`). | Connect one. |
| `token_error` | The network refused to refresh the account's token. | Reconnect. |
| `media_required` | The network needs media this post doesn't have, such as a carousel of videos to a network that takes only photos. | |
| `file_too_large` | Over this network's own file limit (Telegram 50 MB, Discord 10 MB, Mastodon 99 MB…). See [Video requirements](/limits/video). | |
| `processing_timeout` | The server (Mastodon, Lemmy) was still processing the media when Reelspan stopped waiting. | Check the post; retry. |
| `platform_disabled` | Posting to this network is switched off for now. | Try later. |
| `workspace_suspended` | The workspace was suspended before the post ran. | Contact support. |
| `cancelled` | A scheduled post was cancelled. | |
| `internal_error` | Something broke on Reelspan's side; it was retried first. | Retry. |

### TikTok

| Code | Meaning |
| --- | --- |
| `tiktok_privacy_unavailable` | The `privacy_level` isn't one this account may use. The message lists the allowed ones. |
| `tiktok_duration_too_long` | Longer than this account may post. |
| `tiktok_processing_timeout` | TikTok was still processing when Reelspan stopped waiting. |
| `tiktok_spam_risk_too_many_posts` | TikTok's daily post limit for this account was reached. |
| `tiktok_spam_risk_user_banned_from_posting` | TikTok has blocked this account from posting. |
| `tiktok_reached_active_user_cap` | TikTok's daily limit of posting users for Reelspan's app was reached. |
| `tiktok_unaudited_client_can_only_post_to_private_accounts` | TikTok accepts posts only to private accounts from this app for now. |
| `tiktok_url_ownership_unverified` | TikTok hasn't verified the domain photos are served from. |
| `tiktok_rate_limit_exceeded` | TikTok's rate limit; retried automatically. |
| `tiktok_<reason>` | Any other refusal or failure, with TikTok's own reason. |

### YouTube

| Code | Meaning |
| --- | --- |
| `youtube_quotaExceeded`, `youtube_uploadLimitExceeded` | YouTube's daily limit was reached. Try again tomorrow. |
| `youtube_youtubeSignupRequired` | The Google account has no YouTube channel. Create one and reconnect. |
| `youtube_forbidden` | YouTube refused the request for this account. |
| `youtube_rejected` | YouTube rejected the upload. |
| `youtube_<reason>` / `youtube_error` | Any other YouTube error, with its reason. |

### Instagram and Facebook

| Code | Meaning |
| --- | --- |
| `instagram_processing_failed`, `facebook_processing_failed` | The network couldn't process the media. |
| `instagram_processing_timeout` | Instagram was still processing when Reelspan stopped waiting. |
| `facebook_page_required`, `facebook_page_not_connected` | No Facebook Page is chosen for the profile, or the Page isn't connected. |
| `meta_permission_denied` | A permission was removed; the account is marked for reconnection. |
| `meta_rate_limited` | Meta's rate limit; retried automatically. |
| `unsupported_media_type`, `not_found`, `meta_error` | Other Graph API refusals. |

### X, Threads, LinkedIn, Pinterest, Bluesky

| Code | Meaning |
| --- | --- |
| `x_payment_required` | X wants payment for the call. |
| `x_media_failed`, `x_processing_timeout` | X couldn't process the media, or was still processing. |
| `x_rate_limited`, `x_error` | X's rate limit (retried), or another X error. |
| `threads_processing_failed`, `threads_processing_timeout`, `threads_error` | Threads couldn't process the media, was too slow, or refused. |
| `linkedin_processing_failed`, `linkedin_processing_timeout`, `linkedin_upload_failed`, `linkedin_error` | LinkedIn media or post errors. |
| `linkedin_version_sunset` | LinkedIn retired the API version in use; Reelspan has to update. Contact support. |
| `pinterest_blocked_content` | Pinterest blocked the content or link. |
| `pinterest_processing_failed`, `pinterest_processing_timeout`, `pinterest_upload_failed`, `pinterest_error` | Pinterest media or Pin errors. |
| `bluesky_video_too_large` | Over Bluesky's 100 MB. Send `bluesky_compress=true` to compress it. |
| `bluesky_video_limit` | Bluesky's daily video limit for the account is used up. |
| `bluesky_email_unconfirmed` | Bluesky needs the account's email confirmed before it takes video. |
| `bluesky_processing_failed`, `bluesky_processing_timeout`, `bluesky_upload_failed`, `bluesky_error` | Bluesky video or post errors. |
| `invalid_app_password` | The Bluesky app password no longer works. Reconnect. |

### Other networks

| Code | Meaning |
| --- | --- |
| `subreddit_not_found`, `reddit_error` | The subreddit doesn't exist, or Reddit refused. |
| `location_required`, `google_business_error` | Choose a Business Profile location, or Google refused. |
| `invalid_chat`, `bot_not_admin`, `telegram_error` | Telegram: the chat is wrong, or the bot isn't an admin there. |
| `invalid_webhook`, `discord_error` | Discord: the webhook URL is wrong or was deleted. |
| `channel_not_found`, `not_in_channel`, `invalid_webhook`, `slack_error` | Slack: the channel is wrong, or the bot isn't in it. |
| `invalid_server`, `invalid_token`, `mastodon_error` | Mastodon. |
| `invalid_key`, `invalid_relay`, `invalid_media_server`, `nostr_media_error`, `nostr_relays_failed` | Nostr. |
| `community_not_found`, `lemmy_error` | Lemmy. |
| `invalid_site`, `invalid_credentials`, `insufficient_role`, `wordpress_error` | WordPress. |
| `title_required`, `publication_required`, `devto_error`, `hashnode_error` | Dev.to and Hashnode. |
| `invalid_company`, `invalid_forum`, `whop_error` | Whop. |
| `list_not_found`, `listmonk_error` | Listmonk. |
| `sandbox_rejected`, `sandbox_unavailable` | The [sandbox](/guides/test-mode) network, on request. |

For symptoms and fixes, see [Troubleshooting](/troubleshooting).

## Warnings

A network can succeed and still carry `warnings`: text cut to fit, links removed from an X post, a long post turned into a thread, extra photos left out, or a first comment the network refused. The post is live; the warning says what changed.

Source: https://docs.reelspan.com/errors

---

# Rate limits

> Reelspan API rate limits per plan, the X-RateLimit headers on every response, what a 429 looks like, and how often to poll for post status.

Limits are per workspace: every API key in it, live or test, shares the same count. Every response to an API key says where you stand, so your client never has to guess.

## Limits by plan

Requests are counted in two windows at once, one minute and ten minutes. A request over either limit is refused.

| Plan | Requests a minute | Requests per 10 minutes |
| --- | --- | --- |
| Free | 60 | 300 |
| Starter | 60 | 300 |
| Pro | 100 | 500 |
| Agency | 200 | 1,000 |
| Scale | 500 | 2,500 |

Every call counts once: a post, a status check, a profile lookup. A post to five networks is still one request (it counts as five uploads against a monthly upload limit, which only the Free plan has; see [Plans and limits](/limits/plans)).

The windows are fixed, not rolling: the minute window starts again at the top of each minute and the ten-minute window at :00, :10, :20 and so on (UTC).

## Headers

Every answer to an API key carries:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Requests allowed in the window that is closest to running out. |
| `X-RateLimit-Remaining` | Requests left in that window. |
| `X-RateLimit-Reset` | Unix time, in seconds, when that window starts again. |
| `Retry-After` | On a 429 only: seconds to wait before trying again. |

The headers describe whichever window is tighter at that moment, so `X-RateLimit-Limit` can switch between the per-minute and the per-10-minute figure.

```javascript title="Node.js"
await reelspan.me();
console.log(reelspan.rateLimit); // { limit: 100, remaining: 97, reset: 1796198460 }
```

```python title="Python"
reelspan.me()
print(reelspan.rate_limit)  # {'limit': 100, 'remaining': 97, 'reset': 1796198460}
```

## When you go over

```
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1796198460

{ "success": false, "message": "Rate limit exceeded", "error_code": "RATE_LIMITED" }
```

Wait for `Retry-After` seconds, then send the request again. A refused request was not carried out, so retrying it is safe; for posts, keep the same `Idempotency-Key` anyway (see [Retrying safely](/guides/idempotency)). The Node.js and Python SDKs wait and retry 429s on their own (up to 60 seconds at a time, twice by default).

Other 429s are not about the request rate. Tell them apart by `error_code`:

| `error_code` | Cause |
| --- | --- |
| `RATE_LIMITED` | The request rate above. |
| `AUTH_RATE_LIMITED` | 10 failed authentications from your IP address within 5 minutes. Every request from that address is refused for up to 5 minutes (`Retry-After: 300`). Check your key before trying again. |
| `TEST_LIMIT` | 500 [test-key](/guides/test-mode) posts in a day. |
| `USAGE_LIMIT`, or a 429 with `usage` | The monthly upload limit. Waiting a few seconds won't help: it resets on the 1st (UTC), or upgrade. |
| `AI_CREDITS_EXHAUSTED` | No AI caption credits left this month. |

A few actions have their own, smaller limits on top: connecting an account with credentials (`POST /v1/accounts/{platform}`) allows 30 attempts per 10 minutes per workspace, and manual webhook tests and redeliveries allow 10 a minute and 100 an hour.

## Polling for status

A status check costs one request like any other, so polling many posts at once can use up your limit. Poll [Post status](/api/post-status) **every 5 seconds or more**, and back off for big videos, which can take minutes on some networks:

| Post | Suggested interval |
| --- | --- |
| Text and photos | every 5 seconds |
| Short video | every 5 to 10 seconds |
| Long or large video | every 15 to 30 seconds |
| Scheduled post | don't poll before its `scheduled_date` |

Better still, don't poll: an `upload_completed` [webhook](/webhooks) arrives for each network as it finishes, at no cost to your limit. And requests that finish within 59 seconds return the results directly, with nothing to poll.

## Good habits

- Read `X-RateLimit-Remaining` and slow down before you reach zero, rather than waiting for a 429.
- Spread bulk jobs out: a burst of hundreds of posts is better sent as a steady stream, or scheduled with `scheduled_date` or the queue.
- Post to many networks in one request instead of one request per network.
- Page through history with `limit=100` instead of many small pages.

Source: https://docs.reelspan.com/rate-limits

---

# MCP server

> Connect Claude, ChatGPT, Cursor, VS Code or any MCP client to Reelspan so your AI agent can publish, schedule and check posts on 22 networks.

Reelspan runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server. Add it to an AI client once and the agent can publish videos, photos and text, schedule posts, write captions and read results, using the same API key, scopes and limits as the REST API. There is nothing to install.

| | |
| --- | --- |
| Address | `https://api.reelspan.com/mcp` |
| Transport | Streamable HTTP |
| Auth | `Authorization: Bearer <your API key>` |

## Before you start

1. Create an API key in the dashboard under **Developers → API keys**. Tick **Test key** to try things first: a test key (`rs_test_…`) runs every check but never posts to a network.
2. Keep it in an environment variable, for example `REELSPAN_API_KEY`, rather than pasting it into shared files.

## Connect a client

### Claude Code

```bash
claude mcp add --transport http reelspan https://api.reelspan.com/mcp \
  --header "Authorization: Bearer $REELSPAN_API_KEY"
```

Run `/mcp` inside Claude Code to check that it connected. Add `--scope project` to save it in the project's `.mcp.json` for your team; that file can read the key from the environment:

```json
{
  "mcpServers": {
    "reelspan": {
      "type": "http",
      "url": "https://api.reelspan.com/mcp",
      "headers": { "Authorization": "Bearer ${REELSPAN_API_KEY}" }
    }
  }
}
```

### Claude (desktop and web)

1. Open **Customize → Connectors**, select **+ Add**, then **Add custom connector**.
2. Name it `Reelspan` and enter `https://api.reelspan.com/mcp` as the server URL.
3. Under **Authentication**, choose **No sign in**.
4. Under **Request headers**, add `Authorization` with the value `Bearer rs_live_…` (your key).
5. Select **Add**, then turn the connector on in a chat.

On Team and Enterprise plans an owner adds the connector under **Organization settings → Connectors**, and everyone who uses it shares that one key, so give it only the scopes they need.

### Cursor

Add the server to `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project:

```json
{
  "mcpServers": {
    "reelspan": {
      "url": "https://api.reelspan.com/mcp",
      "headers": { "Authorization": "Bearer ${env:REELSPAN_API_KEY}" }
    }
  }
}
```

### VS Code

Add it to `.vscode/mcp.json`. VS Code asks for the key the first time the server starts and stores it securely:

```json
{
  "inputs": [
    { "type": "promptString", "id": "reelspan-key", "description": "Reelspan API key", "password": true }
  ],
  "servers": {
    "reelspan": {
      "type": "http",
      "url": "https://api.reelspan.com/mcp",
      "headers": { "Authorization": "Bearer ${input:reelspan-key}" }
    }
  }
}
```

### ChatGPT

ChatGPT signs in with your Reelspan account instead of an API key. It needs a plan that can add custom MCP servers (Plus or Pro, or a Business, Enterprise or Edu workspace where the admin allows it).

1. Open [chatgpt.com/plugins](https://chatgpt.com/plugins), select **+**, then **Add custom MCP server**.
2. Name it `Reelspan`. Under **Connection**, choose **Server URL** and enter `https://app.reelspan.com/mcp`.
3. Set **Authentication** to **OAuth** and leave the client ID and secret empty: ChatGPT registers itself.
4. Confirm, then sign in to Reelspan when ChatGPT opens it, check the workspace, and select **Allow**.

In a chat, type `@` and pick Reelspan, then ask in plain words. ChatGPT asks before each tool that changes something. If your account still has the older menu, the same setup is under **Settings → Apps & Connectors → Advanced settings → Developer mode**.

> [!NOTE]
> The sign-in flow uses `https://app.reelspan.com/mcp`. Clients that send an API key use `https://api.reelspan.com/mcp`. Both reach the same tools.

### Any other client

Any client that supports remote Streamable HTTP servers works. Most take a config like Cursor's above: the URL plus an `Authorization` header. If your client can't send headers, put the key in the path instead:

```text
https://api.reelspan.com/mcp/rs_live_your_key
```

Treat that URL like the key itself: anyone who sees it can use your account. Prefer the header wherever you can.

To use Reelspan from code, see the agent framework guides, starting with [LangChain](/integrations/langchain).

## Tools

Every tool calls the REST API with your key, so the key's scopes decide what the agent can do. Media is passed as public `https` URLs (Google Drive and Dropbox share links work); the MCP tools don't take local files.

### Account and profiles

| Tool | What it does |
| --- | --- |
| `get_account_info` | Checks the key and shows the plan and this month's upload usage. |
| `list_profiles` | Lists profiles and the networks each one has connected. |
| `create_profile` | Creates a profile (a brand or client). Accounts are connected afterwards. |
| `get_connect_link` | A link, valid 48 hours, where someone connects their own accounts to a profile without a Reelspan login. |
| `delete_profile` | Deletes a profile and disconnects its accounts. Cannot be undone. |
| `get_preferences` | Reads the workspace [preferences](/api/preferences): the week start day and the default time zone for scheduled dates. |
| `set_preferences` | Changes `weekStartDay` (0 Sunday, 1 Monday) and/or `timezone` (an IANA zone, or `null` for UTC). |

### Network settings

| Tool | What it does |
| --- | --- |
| `list_facebook_pages` | The Facebook Pages connected to a profile, with followers, likes and which one posts go to. |
| `choose_facebook_page` | Chooses the Page Facebook posts go to when a post names none; without `facebook_page_id` it clears the choice. |
| `get_facebook_page_info` | A connected Page's about text, website, phone, opening hours, category, picture and cover. |
| `list_google_business_locations` | The locations of a profile's Google Business account and which one posts go to; `refresh` reads them again from Google. |
| `choose_google_business_location` | Chooses the location posts go to; without `location_id` it clears the choice. |
| `list_pinterest_board_sections` | The sections of a Pinterest board, to use as `pinterest_board_section_id`. |
| `create_pinterest_board_section` | Adds a section to a Pinterest board. |
| `get_publishing_limits` | How many more posts the profile's Instagram and Threads accounts may make in the next 24 hours. |
| `list_reddit_posts` | A profile's Reddit posts with score, comments, views and media. |

### Publishing

| Tool | What it does |
| --- | --- |
| `upload_video` | Publishes a video from a URL to one or more networks; returns a `request_id`. |
| `upload_photos` | Publishes one photo or a carousel from URLs, with alt text per photo. |
| `upload_text` | Publishes a text-only post; long text becomes a thread on X and Bluesky. |
| `upload_document` | Publishes a PDF to LinkedIn as a swipeable document. |
| `upload_status` | Per-network status of a publish request. |
| `retry_failed` | Sends the failed networks of a request again, optionally with changed settings, now or at a `scheduled_date`. |
| `upload_history` | Past posts, one row per network, newest first. |

### Live posts

| Tool | What it does |
| --- | --- |
| `unpublish_post` | Deletes a published post from the network. Cannot be undone. See [Unpublish](/api/unpublish) for the networks. |
| `edit_post` | Changes a published post's text (and some settings) where the network allows it. See [Edit a post](/api/edit-post). |
| `repost_post` | Shares a post again from the profile's account: a LinkedIn reshare, an X or Threads repost, a Bluesky repost or a Mastodon boost. |
| `save_pinterest_pin` | Saves (repins) a Pin to one of the account's boards, optionally into a section. |
| `set_youtube_thumbnail` | Gives a published YouTube video a new thumbnail from a public image URL. |

### Scheduling and approvals

| Tool | What it does |
| --- | --- |
| `list_scheduled` | Posts waiting to be published, soonest first. |
| `edit_scheduled` | Moves a scheduled post, changes its text (overall or per network with `platform_content`), or changes or removes a video's cover. |
| `get_scheduled_media` | Signed links, valid an hour, to the media a scheduled post will publish, and a small thumbnail. |
| `cancel_scheduled` | Cancels a scheduled post (and optionally the rest of its repeats); its upload credits are refunded. |
| `create_approval_link` | Puts scheduled posts in a link a client opens to approve each one or ask for changes. |

### Media library

| Tool | What it does |
| --- | --- |
| `import_to_library` | Copies a file from a share link or public URL into the media library and returns its `media_id`. |
| `list_library` | Lists the files in the media library, newest first. |

### Captions

| Tool | What it does |
| --- | --- |
| `generate_captions` | Watches a video (up to 5 minutes) and writes a caption for each network. Uses one AI credit. |
| `write_captions` | Writes each network's caption from your text or notes. Uses one AI credit. |
| `rewrite_captions` | Fits captions you already have to each network's length and tone. Uses one AI credit. |

### Analytics

| Tool | What it does |
| --- | --- |
| `get_analytics` | Followers, views and post counts per connected network of a profile; `days` adds how each number changed. |
| `get_analytics_history` | The same numbers per day, up to 365 days. |
| `get_total_impressions` | Impressions and views (or other post numbers) added up over a period, per network and per day. |
| `get_post_analytics` | Views, likes and comments for each network a request went to, or for any post of the account by `platform` and `platform_post_id`. |
| `get_best_times` | The hours and weekdays when a profile's posts did better than usual, per network. |

### Webhooks

| Tool | What it does |
| --- | --- |
| `get_webhook` | Reads the webhook URL, events and signing secret. |
| `set_webhook` | Sends upload and account events to an `https` URL. |

## How publishing works

The publish tools run in the background: they return a `request_id` straight away, and the agent calls `upload_status` to see each network's result. `upload_video` takes `wait: true` to wait up to a minute for the results instead. Per-network settings go in the tool's `options` object, using the same field names as the REST API, for example `{"youtube_title": "…", "privacy_level": "SELF_ONLY"}`. Each network's fields are on its page under [Networks](/networks/tiktok).

## Authentication

- **API key in the header** (`Authorization: Bearer <key>`) at `https://api.reelspan.com/mcp`. Live keys start with `rs_live_`, test keys with `rs_test_`.
- **API key in the path** (`/mcp/<key>`) for clients that can't send headers.
- **OAuth sign-in** at `https://app.reelspan.com/mcp` for clients that support it, such as ChatGPT. The token acts for the workspace you chose, with every scope.

Ten failed key attempts from one IP address lock that address out for 5 minutes, the same as the REST API. See [Authentication](/authentication).

## Safety

- **Start with a test key.** Posts made with an `rs_test_` key go through every check and show as done, but nothing reaches the networks and nothing counts against your plan (up to 500 test posts a day). See [Test mode](/guides/test-mode).
- **Use the `sandbox` network** to watch the whole flow without a connected account: it accepts video, photo and text posts and needs no connection.
- **Give the agent only the scopes it needs.** A key with just **Read** can check status and history but can't publish. A key without **Profiles** can't create or delete profiles.
- **Review destructive actions.** `delete_profile`, `cancel_scheduled` and `unpublish_post` are marked as destructive, and clients that honour the marking ask before running them.
- **One key per agent or customer**, so you can revoke one without touching the others.

## Example prompts

- "List my profiles and which networks each one has connected."
- "Post this video to TikTok, YouTube and Instagram for my-brand tomorrow at 9am London time, with a caption that fits each network."
- "Post 'Testing Reelspan' as a text post to the sandbox network for my-brand, then check the status."
- "How did yesterday's post do on each network?"

Source: https://docs.reelspan.com/integrations/mcp

---

# n8n

> Post videos and text to 22 networks from an n8n workflow with the HTTP Request node, then check each network's result by polling or with a webhook.

There is no Reelspan node for n8n yet. The built-in **HTTP Request** node calls the Reelspan REST API directly, and one node posts to every network you name. This page builds a workflow that publishes a video, waits, and reads each network's result.

```text
Trigger → get the video → HTTP Request (publish) → Wait → HTTP Request (status) → IF → notify
```

## Before you start

1. In Reelspan, create a profile (for example `my-brand`) and connect the networks you post to.
2. Create an API key under **Developers → API keys**. A test key (`rs_test_…`) lets you build the whole workflow without posting anything.
3. In n8n, create a credential of type **Header Auth** with:
   - **Name:** `Authorization`
   - **Value:** `Bearer rs_test_…` (your key)

Keeping the key in a credential means it never appears in exported workflows.

## Post a video

Get the video into the workflow first. Either it is already at a public `https` URL, or a node such as Google Drive **Download** puts the file on the item as binary data, usually in a property called `data`.

Add an **HTTP Request** node:

| Setting | Value |
| --- | --- |
| Method | `POST` |
| URL | `https://api.reelspan.com/v1/posts/video` |
| Authentication | Generic Credential Type → Header Auth → your credential |
| Send Body | On |
| Body Content Type | Form-Data |

Then add the body parameters:

| Name | Type | Value |
| --- | --- | --- |
| `user` | Form Data | `my-brand` |
| `platform[]` | Form Data | `tiktok` |
| `platform[]` | Form Data | `youtube` |
| `platform[]` | Form Data | `instagram` |
| `title` | Form Data | the caption (YouTube uses it as the title) |
| `video` | n8n Binary File | Input Data Field Name: `data` |
| `async_upload` | Form Data | `true` |

Add one `platform[]` row per network. To send a URL instead of a file, make `video` a normal Form Data field with the URL as its value.

With `async_upload` set, the node returns at once with a `request_id`:

```json
{
  "success": true,
  "message": "Upload initiated successfully in background.",
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "total_platforms": 3
}
```

Every other field from [Post a video](/api/post-video) is another Form Data row: `youtube_title` and `tiktok_title` for per-network captions, `privacy_level` for TikTok, `first_comment`, and so on.

## Post text

Text posts take JSON, so there is no file to handle. In an **HTTP Request** node, set **Method** to `POST`, **URL** to `https://api.reelspan.com/v1/posts/text`, the same credential, **Send Body** on, **Body Content Type** JSON, **Specify Body** Using JSON, and:

```json
{
  "user": "my-brand",
  "platform": ["x", "bluesky", "threads"],
  "title": "{{ $json.text }}",
  "async_upload": "true"
}
```

To try it without a connected account, use `"platform": ["sandbox"]`. See [Post text](/api/post-text) for the networks that take text.

## Read the results

### Poll the status

1. Add a **Wait** node, for example one or two minutes for a video.
2. Add an **HTTP Request** node: `GET https://api.reelspan.com/v1/posts/status`, the same credential, with the query parameter `request_id` set to `{{ $('Publish').item.json.request_id }}` (use your publish node's name).
3. Add an **IF** node on `{{ $json.status }}`. It is `pending` or `in_progress` while networks are still working, then `completed` (at least one network published) or `failed`. Loop back to the Wait node while it is still working.

```json
{
  "success": true,
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "status": "in_progress",
  "completed": 1,
  "total": 3,
  "results": [
    { "platform": "tiktok", "success": true, "status": "completed", "post_url": "https://www.tiktok.com/@mybrand/video/7441…", "error_message": null, "error_code": null }
  ]
}
```

Only networks that have finished appear in `results`. Each has its own `success`, `post_url` and `error_message`, so send yourself a message for the ones that failed. Poll no more often than every 5 seconds. For a scheduled post, query with `job_id` instead. See [Post status](/api/post-status).

### Or get a webhook

Instead of waiting and polling, start a second workflow with a **Webhook** trigger node, and set its production URL as your Reelspan webhook in the dashboard or with `POST /v1/webhook`. Reelspan sends an `upload_completed` event as each network finishes, so the workflow runs once per network with that network's `result`. Deliveries are signed with `X-Reelspan-Signature`; see [Webhooks](/webhooks).

## Retry what failed

From the failure branch, call `POST https://api.reelspan.com/v1/posts/retry` with a JSON body holding the `request_id` and, optionally, `platforms` to retry only some. The media is not uploaded again. See [Retry](/api/retry).

## Schedule instead of posting now

Add `scheduled_date` (ISO 8601) and `timezone` (for example `Europe/London`) to the publish request. Reelspan answers `202` with a `job_id` and posts at that time even when n8n is off. Or add `add_to_queue` = `true` to take the profile's next queue slot. See [Scheduled posts](/api/scheduled-posts).

## Tips

- **Send an `Idempotency-Key` header** (for example the file name plus the date) so a retried run never posts twice. See [Retrying safely](/guides/idempotency).
- **Log the `request_id`** next to the video in a sheet, so you can trace any post later.
- **Move or mark the source file** after it posts, so the workflow doesn't pick it up again.

## Troubleshooting

| What you see | Likely cause | Fix |
| --- | --- | --- |
| `401` | Missing or wrong key | The credential's name must be `Authorization` and its value must start with `Bearer ` |
| `400` about `user` or `platform` | A required field is missing | Send `user`, at least one `platform[]`, `title` and `video` |
| A network shows `skipped` | It isn't connected on that profile | Connect it, or drop it from the request |
| The video arrives empty | Wrong binary property | Match **Input Data Field Name** to the property the download node wrote, usually `data` |
| Posts show as done but nothing appears | You are using a test key | Switch the credential to a live key (`rs_live_…`) |

Source: https://docs.reelspan.com/integrations/n8n

---

# Make

> Publish videos and text to 22 networks from a Make scenario with the HTTP "Make a request" module, then read each network's result by polling or webhook.

There is no Reelspan app in Make yet. The built-in **HTTP → Make a request** module calls the Reelspan REST API directly: one module posts to every network you name.

```text
Trigger → get the video → HTTP (publish) → Sleep → HTTP (status) → Router → notify
```

## Before you start

1. In Reelspan, create a profile (for example `my-brand`) and connect the networks you post to.
2. Create an API key under **Developers → API keys**. A test key (`rs_test_…`) lets you build and run the scenario without posting anything.

## Post a video

Get the video into the scenario first: a module such as Google Drive **Download a file** outputs the file's name and data, or you may already have a public `https` URL to it.

Add **HTTP → Make a request** and set:

| Field | Value |
| --- | --- |
| URL | `https://api.reelspan.com/v1/posts/video` |
| Method | `POST` |
| Headers | `Authorization` = `Bearer rs_test_…` (your key) |
| Body content type | multipart/form-data |
| Parse response | Yes |

Under **Body content**, add one item per field:

| Type | Key | Value |
| --- | --- | --- |
| Text | `user` | `my-brand` |
| Text | `platform[]` | `tiktok` |
| Text | `platform[]` | `youtube` |
| Text | `platform[]` | `instagram` |
| Text | `title` | the caption (YouTube uses it as the title) |
| Text | `async_upload` | `true` |
| File | `video` | map the file name and data from the download module |

Add one `platform[]` item per network. To send a URL instead of a file, make `video` a **Text** item with the URL as its value.

The module returns at once with a `request_id` to map into later modules:

```json
{
  "success": true,
  "message": "Upload initiated successfully in background.",
  "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1",
  "total_platforms": 3
}
```

Every other field from [Post a video](/api/post-video) is another Text item: `youtube_title` and `tiktok_title` for per-network captions, `privacy_level` for TikTok, `first_comment`, and so on.

## Post text

Text posts take JSON. In **Make a request**, set the URL to `https://api.reelspan.com/v1/posts/text`, **Method** `POST`, the same `Authorization` header, **Body content type** application/JSON, **Body input method** JSON string, **Parse response** Yes, and:

```json
{
  "user": "my-brand",
  "platform": ["x", "bluesky", "threads"],
  "title": "Your post text",
  "async_upload": "true"
}
```

Map the text from an earlier module into `title`. To try it without a connected account, use `"platform": ["sandbox"]`. See [Post text](/api/post-text).

## Read the results

### Poll the status

1. Add **Tools → Sleep** to wait, for example a minute or two for a video.
2. Add **HTTP → Make a request**: `GET https://api.reelspan.com/v1/posts/status`, the same header, **Parse response** Yes, and a query parameter `request_id` mapped from the publish module.
3. Route on `status`: `pending` or `in_progress` while networks are still working, then `completed` (at least one network published) or `failed`.

`results` lists each network that has finished, with its `success`, `post_url` and `error_message`. Poll no more often than every 5 seconds. For a scheduled post, query with `job_id` instead. See [Post status](/api/post-status).

### Or get a webhook

Start a second scenario with **Webhooks → Custom webhook**, copy its address, and set it as your Reelspan webhook in the dashboard or with `POST /v1/webhook`. Reelspan sends an `upload_completed` event as each network finishes, so the scenario runs once per network with that network's `result`. See [Webhooks](/webhooks).

## Keep the key safe

The key sits in the module's header, so anyone who can edit the scenario can read it. Give it only the scopes the scenario needs (**Publish** and **Read** for this one), and use a separate key per scenario so you can revoke one without touching the others. See [Authentication](/authentication).

## Troubleshooting

| What you see | Likely cause | Fix |
| --- | --- | --- |
| `401` | Missing or wrong key | The header must be `Authorization` with a value that starts with `Bearer ` |
| `400` "Expected multipart/form-data" | Wrong body type on the video module | Set **Body content type** to multipart/form-data |
| `400` about `user` or `platform` | A required field is missing | Send `user`, at least one `platform[]`, `title` and `video` |
| A network shows `skipped` | It isn't connected on that profile | Connect it, or drop it from the request |
| Posts show as done but nothing appears | You are using a test key | Switch to a live key (`rs_live_…`) |

Source: https://docs.reelspan.com/integrations/make

---

# Zapier

> Publish videos and text to 22 networks from a Zap with a Code by Zapier step, and catch each network's result with Webhooks by Zapier.

There is no Reelspan app in Zapier yet. A **Code by Zapier** step (JavaScript) calls the Reelspan REST API directly, and one step posts to every network you name. A **Webhooks by Zapier** trigger can then catch each network's result.

```text
Trigger (new row, new file…) → Code by Zapier (publish) → … 
Webhooks by Zapier: Catch Hook → filter → notify
```

## Before you start

1. In Reelspan, create a profile (for example `my-brand`) and connect the networks you post to.
2. Create an API key under **Developers → API keys**. A test key (`rs_test_…`) lets you build and test the Zap without posting anything.
3. Have the video at a public `https` URL, for example from the trigger step. Google Drive and Dropbox share links work.

## Post a video

Add an action step: **Code by Zapier → Run JavaScript**. Under **Input Data**, add:

| Key | Value |
| --- | --- |
| `apiKey` | your key |
| `user` | `my-brand` |
| `platforms` | `tiktok,youtube,instagram` |
| `title` | the caption, mapped from an earlier step |
| `videoUrl` | the video's URL, mapped from an earlier step |

Then paste this code. The video endpoint takes `multipart/form-data`, so the code builds that body by hand from text fields:

```javascript
const fields = [
  ['user', inputData.user],
  ...inputData.platforms.split(',').map((p) => ['platform[]', p.trim()]),
  ['title', inputData.title],
  ['video', inputData.videoUrl],
  ['async_upload', 'true'],
];

const boundary = `reelspan${Date.now()}`;
const body =
  fields.map(([name, value]) => `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`).join('') +
  `--${boundary}--\r\n`;

const res = await fetch('https://api.reelspan.com/v1/posts/video', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${inputData.apiKey}`,
    'Content-Type': `multipart/form-data; boundary=${boundary}`,
  },
  body,
});
const json = await res.json();
if (!res.ok) throw new Error(json.message || `Reelspan answered ${res.status}`);

return { request_id: json.request_id, total_platforms: json.total_platforms };
```

`async_upload` makes Reelspan answer at once with a `request_id` while the networks work in the background, which keeps the step well inside Zapier's time limit. Add more fields from [Post a video](/api/post-video) as more `[name, value]` pairs, for example `['youtube_title', '…']` or `['privacy_level', 'SELF_ONLY']`.

## Post text

Text posts take JSON. In a **Run JavaScript** step with `apiKey`, `user`, `platforms` and `text` as Input Data:

```javascript
const res = await fetch('https://api.reelspan.com/v1/posts/text', {
  method: 'POST',
  headers: { Authorization: `Bearer ${inputData.apiKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user: inputData.user,
    platform: inputData.platforms.split(',').map((p) => p.trim()),
    title: inputData.text,
    async_upload: 'true',
  }),
});
const json = await res.json();
if (!res.ok) throw new Error(json.message || `Reelspan answered ${res.status}`);

return { request_id: json.request_id };
```

Set `platforms` to `sandbox` to try it without a connected account. See [Post text](/api/post-text) for the networks that take text.

## Read the results

### With a webhook

1. Create a second Zap that starts with **Webhooks by Zapier → Catch Hook** and copy its URL.
2. Set that URL as your Reelspan webhook in the dashboard or with `POST /v1/webhook`.
3. Reelspan sends an `upload_completed` event as each network finishes, so the Zap runs once per network. Filter on `result success` to act on failures, and map `platform`, `result url` and `result error`.

Webhooks by Zapier needs a paid Zapier plan. See [Webhooks](/webhooks) for the full payload.

### By polling

In a later step (after a **Delay by Zapier**, for example), call `GET https://api.reelspan.com/v1/posts/status?request_id=…` with the same `Authorization` header. `status` is `pending` or `in_progress` while networks are still working, then `completed` or `failed`, and `results` lists each finished network with its `success`, `post_url` and `error_message`. See [Post status](/api/post-status).

## Keep the key safe

Input Data is visible to anyone who can edit the Zap. Give the key only the scopes the Zap needs (**Publish** and **Read** here), and use one key per Zap so you can revoke it alone. See [Authentication](/authentication).

## Troubleshooting

| What you see | Likely cause | Fix |
| --- | --- | --- |
| An error about the API key | Missing or wrong key | Check `apiKey` in Input Data |
| `400` about `user` or `platform` | A required field is missing or misspelt | Send `user`, at least one network, `title` and the video |
| `Invalid platforms` | A network name is wrong | Use the ids from [Networks](/networks/tiktok), such as `google_business`, comma-separated |
| A network shows `skipped` | It isn't connected on that profile | Connect it, or drop it from `platforms` |
| Posts show as done but nothing appears | You are using a test key | Switch to a live key (`rs_live_…`) |

Source: https://docs.reelspan.com/integrations/zapier

---

# Airtable

> Publish a video from an Airtable record to 22 networks with a scripting extension script, and write the request ID and each network's result back to the record.

Keep your content plan in Airtable and post from it: a script in the **Scripting** extension sends a record's video and caption to Reelspan, then writes the `request_id` and the results back to the record. There is no Reelspan app for Airtable; the script calls the REST API.

## Set up the table

Create a table called `Posts` with these fields:

| Field | Type | Holds |
| --- | --- | --- |
| `Caption` | Long text | The caption (YouTube uses it as the title) |
| `Video` | Attachment | The video file |
| `Networks` | Multiple select | Network ids: `tiktok`, `youtube`, `instagram`, `x`, `sandbox`… |
| `Profile` | Single line text | The Reelspan profile, for example `my-brand` |
| `Request ID` | Single line text | Filled in by the script |
| `Status` | Single line text | Filled in by the script |

The multiple-select options must be Reelspan's network ids exactly; see [Networks](/networks/tiktok). Add `sandbox` to try the flow without a connected account.

## Add the script

1. Create an API key under **Developers → API keys**. Use a test key (`rs_test_…`) while you set this up: posts go through every check but nothing reaches the networks.
2. In the base, open **Extensions**, add **Scripting**, and paste the script below.
3. Open the script's settings and paste the key into **Reelspan API key**.

```javascript
const settings = input.config({
  title: 'Post to Reelspan',
  description: 'Publishes a record’s video to the networks in its Networks field.',
  items: [input.config.text('apiKey', { label: 'Reelspan API key' })],
});

const table = base.getTable('Posts');
const record = await input.recordAsync('Pick the post to publish', table);
if (!record) throw new Error('No record picked');

const video = record.getCellValue('Video')?.[0];
const networks = (record.getCellValue('Networks') ?? []).map((n) => n.name);
if (!video || networks.length === 0) throw new Error('The record needs a video and at least one network');

// the video endpoint takes multipart/form-data; Airtable's remote fetch can't send FormData, so build the body by hand
const fields = [
  ['user', record.getCellValueAsString('Profile')],
  ...networks.map((n) => ['platform[]', n]),
  ['title', record.getCellValueAsString('Caption')],
  ['video', video.url],
  ['async_upload', 'true'],
];
const boundary = `reelspan${Date.now()}`;
const body =
  fields.map(([name, value]) => `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`).join('') +
  `--${boundary}--\r\n`;

const res = await remoteFetchAsync('https://api.reelspan.com/v1/posts/video', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${settings.apiKey}`,
    'Content-Type': `multipart/form-data; boundary=${boundary}`,
    'Idempotency-Key': `airtable-${record.id}`,
  },
  body,
});
const json = await res.json();

if (!res.ok) {
  await table.updateRecordAsync(record, { Status: `Error: ${json.message}` });
  throw new Error(json.message);
}
await table.updateRecordAsync(record, { 'Request ID': json.request_id, Status: 'Posting' });
output.markdown(`Sent to ${networks.join(', ')}. Request ID: \`${json.request_id}\``);
```

Select **Run**, pick a record, and the script fills in **Request ID** and **Status**.

A few things the script relies on:

- **`remoteFetchAsync`** sends the request from Airtable's servers. A plain `fetch` from the extension runs in your browser, and the Reelspan API doesn't accept browser requests from other sites.
- **The video goes as a URL.** The script sends the attachment's URL in the `video` field and Reelspan downloads the file from there, so nothing is uploaded from your computer.
- **`Idempotency-Key`** is the record's ID, so running the script twice on the same record never posts twice. See [Retrying safely](/guides/idempotency).

Other fields from [Post a video](/api/post-video), such as `youtube_title` or `scheduled_date`, go in as more `[name, value]` pairs. For text-only posts, send JSON to `/v1/posts/text` instead; see [Post text](/api/post-text).

## Check the results

Add a second script that reads the status of the picked record:

```javascript
const settings = input.config({
  title: 'Check Reelspan status',
  items: [input.config.text('apiKey', { label: 'Reelspan API key' })],
});

const table = base.getTable('Posts');
const record = await input.recordAsync('Pick the post to check', table);
const requestId = record?.getCellValueAsString('Request ID');
if (!requestId) throw new Error('This record has no Request ID yet');

const res = await remoteFetchAsync(`https://api.reelspan.com/v1/posts/status?request_id=${encodeURIComponent(requestId)}`, {
  headers: { Authorization: `Bearer ${settings.apiKey}` },
});
const json = await res.json();
if (!res.ok) throw new Error(json.message);

const lines = json.results.map((r) => `${r.platform}: ${r.success ? r.post_url ?? 'done' : `failed (${r.error_message})`}`);
await table.updateRecordAsync(record, { Status: `${json.status} (${json.completed}/${json.total})` });
output.markdown(lines.join('\n\n') || 'No network has finished yet.');
```

`status` is `pending` or `in_progress` while networks are still working, then `completed` (at least one network published) or `failed`. Only networks that have finished appear in `results`. With a test key, finished posts have no `post_url`. See [Post status](/api/post-status).

To have results arrive on their own, set a [webhook](/webhooks) that points at an Airtable automation's **When webhook received** trigger, or at a tool such as [n8n](/integrations/n8n) that updates the record.

## Keep the key safe

Script settings are visible to everyone who can edit the base. Use a key with only the **Publish** and **Read** scopes, and one key per base, so you can revoke it without touching anything else. See [Authentication](/authentication).

Source: https://docs.reelspan.com/integrations/airtable

---

# Postman

> Import Reelspan's Postman collection, set your API key once, and try every endpoint, with environments to switch between a test key and a live one.

Reelspan publishes a Postman collection of the whole API at `https://reelspan.com/postman.json`. It is built from the live [OpenAPI spec](https://api.reelspan.com/openapi.json), so it always matches the API: one folder per area (Publishing, Scheduling, Queue, Profiles, Webhooks, Media, Analytics and more), and every request with its path variables, query parameters and body fields.

## Import the collection

1. In Postman, select **Import**.
2. Paste `https://reelspan.com/postman.json` and confirm.

The collection appears as **Reelspan API**. To pick up endpoints added later, import the link again and replace the old copy.

## Set your API key

The collection sends `Authorization: Bearer {{apiKey}}` on every request, so you set the key once:

1. Create a key under **Developers → API keys** in the dashboard. A test key (`rs_test_…`) runs every check without posting anything.
2. Open the collection, go to **Variables**, and paste the key as the value of `apiKey`.
3. Save.

| Variable | Default | What it is |
| --- | --- | --- |
| `baseUrl` | `https://api.reelspan.com` | The API host; every request URL starts with it |
| `apiKey` | empty | Your Reelspan API key |

Try **Account → Check the API key and read the account plan and usage** (`GET /v1/me`) first: it answers with your plan and usage when the key works.

## Environments

To switch between a test key and a live key without editing the collection, use environments. A variable set in the active environment takes priority over the collection's.

1. Select **Environments → +** and name it `Reelspan test`. Add `apiKey` with your `rs_test_…` key, type **secret**.
2. Create a second one, `Reelspan live`, with your `rs_live_…` key.
3. Pick the environment in the top-right selector before you send a request.

With the test environment active, posts go through every check and show as done, but nothing reaches the networks. See [Test mode](/guides/test-mode).

## Send a post

Open **Publishing → Publish a video to one or more networks** (`POST /v1/posts/video`). The body is form-data with every field listed; `user`, `platform[]` and `video` are on, and the optional fields start switched off, so tick only the ones you need:

- `user`: your profile, for example `my-brand`.
- `platform[]`: a network id such as `tiktok`. Duplicate the row for each further network.
- `title`: the caption (switch it on; YouTube needs it).
- `video`: choose a file, or change the row's type to **Text** and paste a public URL.

To try a post without a connected account, use `sandbox` as the network. For text, **Publish a text-only post** (`POST /v1/posts/text`) takes JSON. The response holds a `request_id`; paste it into **Status of a publish request, per platform** (`GET /v1/posts/status`) to see each network's result. See [Post a video](/api/post-video) and [Post status](/api/post-status).

> [!TIP]
> Postman's **Code** panel turns any request into cURL, JavaScript, Python and more, which is a quick way to start an integration. For Node.js and Python, the [SDKs](/sdks) do the same with less code.

Source: https://docs.reelspan.com/integrations/postman

---

# LangChain

> Give a LangChain agent Reelspan's publishing tools through the hosted MCP server, with your API key, and let it post, schedule and check results.

LangChain loads tools from any MCP server, so a LangChain agent can use Reelspan's hosted [MCP server](/integrations/mcp) directly: publish, schedule, write captions and read results. There is no separate Reelspan package to install.

## Install

```bash
pip install "langchain[mcp]>=1.4.0" langchain-anthropic
```

LangChain marks its `langchain.mcp` module as beta, so its API may still change. Swap `langchain-anthropic` for the provider package of the model you use.

## API key

Create a key under **Developers → API keys** and export it. Start with a test key (`rs_test_…`): every check runs, but nothing is posted.

```bash
export REELSPAN_API_KEY=rs_test_...
```

## Example

This agent publishes a text post to the `sandbox` network, which needs no connected account, and then checks the result.

```python
import asyncio
import os

from fastmcp.client import Client
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter


async def main():
    # auth=<key> sends Authorization: Bearer <key>
    reelspan = Client("https://api.reelspan.com/mcp", auth=os.environ["REELSPAN_API_KEY"])
    async with MCPAdapter(reelspan) as adapter:
        tools = await adapter.list_tools()
        agent = create_agent("claude-sonnet-5", tools)
        result = await agent.ainvoke({
            "messages": [{
                "role": "user",
                "content": "Publish 'Hello from my LangChain agent' as a text post to the sandbox network "
                "for the profile my-brand, then check its status and tell me the result.",
            }]
        })
        print(result["messages"][-1].content)


asyncio.run(main())
```

Replace `my-brand` with one of your profiles (the agent can find them with `list_profiles`).

## Notes

- **Posting runs in the background.** The publish tools return a `request_id`; the agent calls `upload_status` to read each network's result.
- **Media goes in as URLs.** `upload_video` and `upload_photos` take public `https` URLs, not local files.
- **Scope the key.** The agent can do whatever the key allows. A key with only **Publish** and **Read** can't create or delete profiles.
- **Going live:** swap the test key for a live one (`rs_live_…`) and use real networks instead of `sandbox`.

The full tool list is on the [MCP server](/integrations/mcp) page. LangChain's own guide: [docs.langchain.com/oss/python/langchain/mcp](https://docs.langchain.com/oss/python/langchain/mcp).

Source: https://docs.reelspan.com/integrations/langchain

---

# Vercel AI SDK

> Connect the Vercel AI SDK's MCP client to Reelspan's hosted MCP server and let generateText or streamText publish, schedule and check social posts.

The AI SDK has an MCP client, so it can load Reelspan's tools from the hosted [MCP server](/integrations/mcp) and pass them to `generateText` or `streamText`. There is no separate Reelspan package to install.

## Install

```bash
npm install ai @ai-sdk/mcp
```

## API key

Create a key under **Developers → API keys** and export it. Start with a test key (`rs_test_…`): every check runs, but nothing is posted.

```bash
export REELSPAN_API_KEY=rs_test_...
```

## Example

This script publishes a text post to the `sandbox` network, which needs no connected account, and then checks the result.

```typescript
import { createMCPClient } from '@ai-sdk/mcp';
import { generateText, isStepCount } from 'ai';

const reelspan = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://api.reelspan.com/mcp',
    headers: { Authorization: `Bearer ${process.env.REELSPAN_API_KEY}` },
  },
});

try {
  const { text } = await generateText({
    model: 'anthropic/claude-sonnet-5.5',
    tools: await reelspan.tools(),
    stopWhen: isStepCount(5),
    prompt:
      "Publish 'Hello from my AI SDK agent' as a text post to the sandbox network for the profile my-brand, " +
      'then check its status and tell me the result.',
  });
  console.log(text);
} finally {
  await reelspan.close();
}
```

`stopWhen` lets the model call several tools in a row: publish, then check the status. A model given as a string goes through the Vercel AI Gateway; you can pass a provider's model instead. Replace `my-brand` with one of your profiles.

## Notes

- **Close the client** when the response is done: in `finally` for `generateText`, or when the stream ends for `streamText`.
- **Posting runs in the background.** The publish tools return a `request_id`; the model calls `upload_status` to read each network's result.
- **Media goes in as URLs.** `upload_video` and `upload_photos` take public `https` URLs, not local files.
- **One key per customer.** If your app posts for many customers, create the client per request with that customer's key.
- **Going live:** swap the test key for a live one (`rs_live_…`) and use real networks instead of `sandbox`.

The full tool list is on the [MCP server](/integrations/mcp) page. The AI SDK's own guide: [ai-sdk.dev/docs/ai-sdk-core/mcp-tools](https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools).

Source: https://docs.reelspan.com/integrations/vercel-ai-sdk

---

# OpenAI Agents SDK

> Connect an OpenAI Agents SDK agent to Reelspan's hosted MCP server over Streamable HTTP so it can publish, schedule and check social posts.

The OpenAI Agents SDK connects agents to MCP servers, so an agent can use Reelspan's hosted [MCP server](/integrations/mcp) to publish, schedule and read results. There is no separate Reelspan package to install.

## Install

```bash
pip install openai-agents
```

## API key

Create a key under **Developers → API keys** and export it with your OpenAI key. Start with a test key (`rs_test_…`): every check runs, but nothing is posted.

```bash
export REELSPAN_API_KEY=rs_test_...
export OPENAI_API_KEY=sk-...
```

## Example

This agent publishes a text post to the `sandbox` network, which needs no connected account, and then checks the result.

```python
import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main():
    async with MCPServerStreamableHttp(
        name="Reelspan",
        params={
            "url": "https://api.reelspan.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['REELSPAN_API_KEY']}"},
            "timeout": 30,
        },
        cache_tools_list=True,
    ) as reelspan:
        agent = Agent(
            name="Social publisher",
            instructions="You publish and check social media posts with the Reelspan tools.",
            mcp_servers=[reelspan],
        )
        result = await Runner.run(
            agent,
            "Publish 'Hello from my OpenAI agent' as a text post to the sandbox network for the profile my-brand, "
            "then check its status and tell me the result.",
        )
        print(result.final_output)


asyncio.run(main())
```

Replace `my-brand` with one of your profiles (the agent can find them with `list_profiles`).

## Notes

- **Posting runs in the background.** The publish tools return a `request_id`; the agent calls `upload_status` to read each network's result.
- **Media goes in as URLs.** `upload_video` and `upload_photos` take public `https` URLs, not local files.
- **Scope the key.** The agent can do whatever the key allows. A key with only **Publish** and **Read** can't create or delete profiles.
- **Going live:** swap the test key for a live one (`rs_live_…`) and use real networks instead of `sandbox`.

The full tool list is on the [MCP server](/integrations/mcp) page. The SDK's own guide: [openai.github.io/openai-agents-python/mcp](https://openai.github.io/openai-agents-python/mcp/).

Source: https://docs.reelspan.com/integrations/openai-agents-sdk

---

# CrewAI

> Give CrewAI agents Reelspan's publishing tools through the hosted MCP server so a crew can post, schedule and check social media results.

CrewAI agents can load tools from MCP servers, so a crew can use Reelspan's hosted [MCP server](/integrations/mcp) to publish, schedule and read results. There is no separate Reelspan package to install.

## Install

```bash
pip install crewai mcp
```

## API key

Create a key under **Developers → API keys** and export it, along with the key for the model your agents use. Start with a test key (`rs_test_…`): every check runs, but nothing is posted.

```bash
export REELSPAN_API_KEY=rs_test_...
```

## Example

This crew publishes a text post to the `sandbox` network, which needs no connected account, and then checks the result.

```python
import os

from crewai import Agent, Crew, Task
from crewai.mcp import MCPServerHTTP

reelspan = MCPServerHTTP(
    url="https://api.reelspan.com/mcp",
    headers={"Authorization": f"Bearer {os.environ['REELSPAN_API_KEY']}"},
    cache_tools_list=True,
)

publisher = Agent(
    role="Social media publisher",
    goal="Publish posts with Reelspan and confirm they went out",
    backstory="You manage the brand's social accounts through Reelspan.",
    mcps=[reelspan],
)

task = Task(
    description="Publish 'Hello from my CrewAI agent' as a text post to the sandbox network for the profile my-brand, "
    "then check its status.",
    expected_output="The request_id and each network's result.",
    agent=publisher,
)

print(Crew(agents=[publisher], tasks=[task]).kickoff())
```

Replace `my-brand` with one of your profiles (the agent can find them with `list_profiles`).

## Notes

- **Posting runs in the background.** The publish tools return a `request_id`; the agent calls `upload_status` to read each network's result.
- **Media goes in as URLs.** `upload_video` and `upload_photos` take public `https` URLs, not local files.
- **Scope the key.** The agents can do whatever the key allows. A key with only **Publish** and **Read** can't create or delete profiles.
- **Going live:** swap the test key for a live one (`rs_live_…`) and use real networks instead of `sandbox`.

The full tool list is on the [MCP server](/integrations/mcp) page. CrewAI's own guide: [docs.crewai.com/en/mcp/overview](https://docs.crewai.com/en/mcp/overview).

Source: https://docs.reelspan.com/integrations/crewai

---

# Mastra

> Connect a Mastra agent to Reelspan's hosted MCP server with MCPClient so it can publish, schedule and check posts on 22 social networks.

Mastra's `MCPClient` loads tools from remote MCP servers, so a Mastra agent can use Reelspan's hosted [MCP server](/integrations/mcp) to publish, schedule and read results. There is no separate Reelspan package to install.

## Install

```bash
npm install @mastra/core @mastra/mcp
```

## API key

Create a key under **Developers → API keys** and export it, along with the key for your model provider. Start with a test key (`rs_test_…`): every check runs, but nothing is posted.

```bash
export REELSPAN_API_KEY=rs_test_...
```

## Example

This agent publishes a text post to the `sandbox` network, which needs no connected account, and then checks the result.

```typescript
import { Agent } from '@mastra/core/agent';
import { MCPClient } from '@mastra/mcp';

const reelspan = new MCPClient({
  id: 'reelspan',
  servers: {
    reelspan: {
      url: new URL('https://api.reelspan.com/mcp'),
      requestInit: { headers: { Authorization: `Bearer ${process.env.REELSPAN_API_KEY}` } },
    },
  },
});

const publisher = new Agent({
  id: 'publisher',
  name: 'Social publisher',
  instructions: 'You publish and check social media posts with the Reelspan tools.',
  model: 'openai/gpt-6.1-sol',
  tools: await reelspan.listTools(),
});

const response = await publisher.generate(
  "Publish 'Hello from my Mastra agent' as a text post to the sandbox network for the profile my-brand, then check its status and tell me the result.",
);
console.log(response.text);
await reelspan.disconnect();
```

Replace `my-brand` with one of your profiles (the agent can find them with `list_profiles`).

## Notes

- **One key per customer.** For credentials that change per request, create an `MCPClient` per request and pass `await client.listToolsets()` to `generate()` as `toolsets` instead of giving the agent fixed `tools`. Disconnect the client afterwards.
- **Posting runs in the background.** The publish tools return a `request_id`; the agent calls `upload_status` to read each network's result.
- **Media goes in as URLs.** `upload_video` and `upload_photos` take public `https` URLs, not local files.
- **Going live:** swap the test key for a live one (`rs_live_…`) and use real networks instead of `sandbox`.

The full tool list is on the [MCP server](/integrations/mcp) page. Mastra's own guide: [mastra.ai/docs/mcp/overview](https://mastra.ai/docs/mcp/overview).

Source: https://docs.reelspan.com/integrations/mastra

---

# Google ADK

> Give a Google Agent Development Kit agent Reelspan's publishing tools with McpToolset and the hosted MCP server, to post and check social media results.

Google's Agent Development Kit (ADK) loads tools from MCP servers with `McpToolset`, so an ADK agent can use Reelspan's hosted [MCP server](/integrations/mcp) to publish, schedule and read results. There is no separate Reelspan package to install.

## Install

```bash
pip install "google-adk[mcp]"
```

## API key

Create a key under **Developers → API keys** and export it, along with your Gemini key. Start with a test key (`rs_test_…`): every check runs, but nothing is posted.

```bash
export REELSPAN_API_KEY=rs_test_...
export GOOGLE_API_KEY=...
```

## Example

ADK finds agents by folder. Create `social_agent/__init__.py` containing `from . import agent`, and `social_agent/agent.py`:

```python
import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

root_agent = LlmAgent(
    model="gemini-flash-latest",
    name="social_publisher",
    instruction="You publish and check social media posts with the Reelspan tools.",
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://api.reelspan.com/mcp",
                headers={"Authorization": f"Bearer {os.environ['REELSPAN_API_KEY']}"},
                timeout=30,
            )
        )
    ],
)
```

Run it from the folder above `social_agent`, with the terminal chat or the dev UI:

```bash
adk run social_agent
```

Then ask: "Publish 'Hello from my ADK agent' as a text post to the sandbox network for the profile my-brand, then check its status." The `sandbox` network needs no connected account. Replace `my-brand` with one of your profiles.

## Notes

- **Define the toolset in `agent.py`**, as above, rather than creating it at run time: ADK needs it there when you deploy the agent.
- **Posting runs in the background.** The publish tools return a `request_id`; the agent calls `upload_status` to read each network's result.
- **Media goes in as URLs.** `upload_video` and `upload_photos` take public `https` URLs, not local files.
- **Going live:** swap the test key for a live one (`rs_live_…`) and use real networks instead of `sandbox`.

The full tool list is on the [MCP server](/integrations/mcp) page. ADK's own guide: [adk.dev/tools-custom/mcp-tools](https://adk.dev/tools-custom/mcp-tools/).

Source: https://docs.reelspan.com/integrations/google-adk

---

# Pydantic AI

> Connect a Pydantic AI agent to Reelspan's hosted MCP server with MCPToolset so it can publish, schedule and check posts on 22 social networks.

Pydantic AI connects agents to MCP servers as toolsets, so an agent can use Reelspan's hosted [MCP server](/integrations/mcp) to publish, schedule and read results. There is no separate Reelspan package to install.

## Install

```bash
pip install "pydantic-ai-slim[mcp,openai]"
```

Swap `openai` for the extra of the model provider you use.

## API key

Create a key under **Developers → API keys** and export it with your model provider's key. Start with a test key (`rs_test_…`): every check runs, but nothing is posted.

```bash
export REELSPAN_API_KEY=rs_test_...
export OPENAI_API_KEY=sk-...
```

## Example

This agent publishes a text post to the `sandbox` network, which needs no connected account, and then checks the result.

```python
import asyncio
import os

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPToolset

reelspan = MCPToolset(
    "https://api.reelspan.com/mcp",
    headers={"Authorization": f"Bearer {os.environ['REELSPAN_API_KEY']}"},
)
agent = Agent(
    "openai:gpt-6.1-sol",
    toolsets=[reelspan],
    instructions="You publish and check social media posts with the Reelspan tools.",
)


async def main():
    async with agent:
        result = await agent.run(
            "Publish 'Hello from my Pydantic AI agent' as a text post to the sandbox network for the profile my-brand, "
            "then check its status and tell me the result."
        )
        print(result.output)


asyncio.run(main())
```

Replace `my-brand` with one of your profiles (the agent can find them with `list_profiles`).

## Notes

- **One key per customer.** `headers=` also takes a function, called at the start of each run with the run context, so it can read each customer's key from `deps`.
- **Posting runs in the background.** The publish tools return a `request_id`; the agent calls `upload_status` to read each network's result.
- **Media goes in as URLs.** `upload_video` and `upload_photos` take public `https` URLs, not local files.
- **Going live:** swap the test key for a live one (`rs_live_…`) and use real networks instead of `sandbox`.

The full tool list is on the [MCP server](/integrations/mcp) page. Pydantic AI's own guide: [pydantic.dev/docs/ai/mcp/client](https://pydantic.dev/docs/ai/mcp/client/).

Source: https://docs.reelspan.com/integrations/pydantic-ai

---

# LlamaIndex

> Turn Reelspan's hosted MCP server into LlamaIndex tools with McpToolSpec, and let a FunctionAgent publish, schedule and check social posts.

LlamaIndex turns an MCP server's tools into LlamaIndex tools, so an agent can use Reelspan's hosted [MCP server](/integrations/mcp) to publish, schedule and read results. There is no separate Reelspan package to install.

## Install

```bash
pip install llama-index-tools-mcp llama-index-llms-openai
```

## API key

Create a key under **Developers → API keys** and export it with your OpenAI key. Start with a test key (`rs_test_…`): every check runs, but nothing is posted.

```bash
export REELSPAN_API_KEY=rs_test_...
export OPENAI_API_KEY=sk-...
```

## Example

This agent publishes a text post to the `sandbox` network, which needs no connected account, and then checks the result.

```python
import asyncio
import os

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec


async def main():
    client = BasicMCPClient(
        "https://api.reelspan.com/mcp",
        headers={"Authorization": f"Bearer {os.environ['REELSPAN_API_KEY']}"},
    )
    # only the tools this agent needs
    spec = McpToolSpec(client=client, allowed_tools=["list_profiles", "upload_text", "upload_status"])
    tools = await spec.to_tool_list_async()

    agent = FunctionAgent(
        tools=tools,
        llm=OpenAI(model="gpt-5-mini"),
        system_prompt="You publish and check social media posts with the Reelspan tools.",
    )
    response = await agent.run(
        "Publish 'Hello from my LlamaIndex agent' as a text post to the sandbox network for the profile my-brand, "
        "then check its status and tell me the result."
    )
    print(response)


asyncio.run(main())
```

Replace `my-brand` with one of your profiles (the agent can find them with `list_profiles`).

## Notes

- **`allowed_tools`** keeps the agent to the tools you list. Leave it out to load all of them.
- **Posting runs in the background.** The publish tools return a `request_id`; the agent calls `upload_status` to read each network's result.
- **Media goes in as URLs.** `upload_video` and `upload_photos` take public `https` URLs, not local files.
- **Going live:** swap the test key for a live one (`rs_live_…`) and use real networks instead of `sandbox`.

The full tool list is on the [MCP server](/integrations/mcp) page. LlamaIndex's own guide: [developers.llamaindex.ai](https://developers.llamaindex.ai/python/framework/module_guides/mcp/llamaindex_mcp).

Source: https://docs.reelspan.com/integrations/llamaindex

---

# smolagents

> Load Reelspan's publishing tools into a Hugging Face smolagents agent with MCPClient and the hosted MCP server, to post and check social media results.

smolagents loads tools from MCP servers with `MCPClient`, so an agent can use Reelspan's hosted [MCP server](/integrations/mcp) to publish, schedule and read results. There is no separate Reelspan package to install.

## Install

```bash
pip install "smolagents[mcp]"
```

## API key

Create a key under **Developers → API keys** and export it, along with your Hugging Face token for the model. Start with a test key (`rs_test_…`): every check runs, but nothing is posted.

```bash
export REELSPAN_API_KEY=rs_test_...
export HF_TOKEN=hf_...
```

## Example

This agent publishes a text post to the `sandbox` network, which needs no connected account, and then checks the result.

```python
import os

from smolagents import CodeAgent, InferenceClientModel, MCPClient

# the key goes in the path: /mcp/<key>
reelspan = {"url": f"https://api.reelspan.com/mcp/{os.environ['REELSPAN_API_KEY']}", "transport": "streamable-http"}

with MCPClient(reelspan, structured_output=False) as tools:
    agent = CodeAgent(tools=tools, model=InferenceClientModel())
    agent.run(
        "Publish 'Hello from my smolagents agent' as a text post to the sandbox network for the profile my-brand, "
        "then check its status and tell me the result."
    )
```

Replace `my-brand` with one of your profiles (the agent can find them with `list_profiles`).

## Notes

- **Why the key is in the URL:** `MCPClient` takes a plain dict of connection settings, and Reelspan accepts the key in the path (`/mcp/<key>`) for clients like this. Treat that URL like the key itself, and keep it out of logs and shared code.
- **`structured_output`** is set explicitly because smolagents warns when it is left out; Reelspan's tools return JSON as text either way.
- **Posting runs in the background.** The publish tools return a `request_id`; the agent calls `upload_status` to read each network's result.
- **Media goes in as URLs.** `upload_video` and `upload_photos` take public `https` URLs, not local files.
- **Going live:** swap the test key for a live one (`rs_live_…`) and use real networks instead of `sandbox`.

The full tool list is on the [MCP server](/integrations/mcp) page. smolagents' own guide: [huggingface.co/docs/smolagents/tutorials/tools](https://huggingface.co/docs/smolagents/tutorials/tools).

Source: https://docs.reelspan.com/integrations/smolagents

---

# Video requirements

> Video formats, file sizes and per-network limits for posting video through Reelspan: what Reelspan checks, what it adjusts, and what each network decides.

A video passes two sets of limits. Reelspan's own (file type and your plan's size) are checked when you send the request, and a video that fails them is refused before anything is posted. Each network's own limits are checked when Reelspan publishes there, and a network that can't take the video fails on its own with an `error_code`, without affecting the others.

## What Reelspan accepts

| | |
| --- | --- |
| Formats | MP4, MOV and WebM (AVI is also recognised). The type is read from the file's content, not its name. |
| Size | Your plan's limit: Free 0.5 GB, Starter 1 GB, Pro 2 GB, Agency 4 GB, Scale 8 GB. See [Plans and limits](/limits/plans). |
| One request | At most 100 MB per request; send bigger files with a direct upload. See [Large files](/guides/large-files). |
| From a URL | A public `https://` URL, including Google Drive and Dropbox share links. |
| Thumbnail / cover | An image up to 20 MB, as a file, a URL (`thumbnail_url`, `cover_url`) or a media id. `thumbnail` is the YouTube thumbnail; `cover` is the Instagram Reel cover, the Pinterest video Pin cover and the Reddit poster image. TikTok takes its cover from a frame of the video instead (`cover_timestamp`, in milliseconds). |

A video over the plan limit is refused with **413** `FILE_TOO_LARGE`; a file that isn't a video with **400** `UNSUPPORTED_MEDIA` or `WRONG_MEDIA_KIND`.

## Per network

What each network takes, and the limits Reelspan itself enforces or adjusts for it. "Shapes" are the aspect ratios the network shows best, preferred first. Where a cell says *network decides*, Reelspan sends the video as it is and the network's own answer is reported in the result.

| Network | Video post | Shapes | Size and length |
| --- | --- | --- | --- |
| YouTube | Shorts and long-form | 9:16, 16:9 | Network decides. A video of 3 minutes or less that is vertical or square gets a `youtube.com/shorts/` URL. |
| TikTok | Direct post, or a draft in the TikTok inbox (`post_mode=MEDIA_UPLOAD`) | 9:16 | Before a direct post Reelspan asks TikTok for the account's longest allowed video and fails with `tiktok_duration_too_long` if it is longer. Size: network decides. |
| Instagram | Reels, or a Story (`media_type=STORIES`) | 9:16, 4:5, 1:1 | Network decides. |
| Facebook | Page Reels, a Page video (`facebook_media_type=VIDEO`), or a Page Story (`facebook_media_type=STORIES`) | 9:16, 16:9; any shape for a Page video | Network decides. |
| X | A video post | 16:9, 1:1 | Network decides. |
| Threads | A video post | 4:5, 9:16 | Network decides. |
| LinkedIn | A video post, personal or company page | 1:1, 16:9 | Network decides. |
| Pinterest | A video Pin (needs `pinterest_board_id`) | 2:3, 9:16 | Network decides. |
| Bluesky | A video post | 16:9 | **100 MB**. Over it fails with `bluesky_video_too_large`, unless you send `bluesky_compress=true`: Reelspan then re-encodes it to fit (H.264, at most 1080p) and says so in a warning. Bluesky also has a daily video limit per account (`bluesky_video_limit`). |
| Reddit | A video post in `reddit_subreddit` | 16:9, 9:16, 1:1 | **1 GB**. Reddit needs a poster image: the cover if you sent one, else a frame of the video. |
| Telegram | A channel or group message | 9:16, 16:9, 1:1 | **50 MB** (Telegram's limit for bots). |
| Discord | A channel message | 16:9, 9:16, 1:1 | **10 MB** per file (webhooks on servers without boosts). |
| Slack | A channel message | 16:9, 9:16, 1:1 | **1 GB** with a bot token. Through an Incoming Webhook the video is sent as a link. |
| Mastodon | A post | 16:9, 9:16, 1:1 | **99 MB**; servers may set lower limits. |
| WordPress | A blog post with the video embedded | 16:9, 1:1 | **512 MB**; your site's own upload limit also applies. |
| Lemmy | A community post | 16:9, 1:1 | **100 MB**. |
| Nostr | A note linking the video, uploaded to your media server | 16:9, 9:16, 1:1 | **100 MB**. |
| Whop | A forum post | 16:9, 9:16, 1:1 | **2 GB**. |
| Google Business | No video posts | | |
| Dev.to, Hashnode, Listmonk | No video posts | | |

A file over a network's limit fails that network with `file_too_large` (or the network's own code above). Sending video to a network that has no video posts refuses the request with **400** `UNSUPPORTED_POST_TYPE`.

## Carousels with video

On [photo posts](/api/post-photos), Instagram and Threads take videos mixed into a carousel. Other networks get only the photos, with a warning; a network that would be left with no photos fails with `media_required`.

## Processing on the network

Most networks process a video after it is uploaded. Reelspan waits for that and reports the outcome; a network that rejects the file fails with a `*_processing_failed` code, and one that is still processing when Reelspan stops waiting fails with `*_processing_timeout`. In the second case the post may still appear: check the account before retrying. See [Troubleshooting](/troubleshooting).

> [!TIP]
> To avoid surprises, export H.264 video with AAC audio in an MP4, vertical 9:16 for short-form networks, and keep it within the smallest limit of the networks you post to. Network rules change; the network's own help pages have its current limits.

Source: https://docs.reelspan.com/limits/video

---

# Photo requirements

> Photo formats, sizes and per-network carousel limits for Reelspan photo posts, and how Reelspan converts or trims photos so each network accepts them.

A photo post sends one photo or a carousel of up to 35 to every network you name. Reelspan checks each photo when you send the request, then adapts the set to each network: it converts formats a network won't take, and uses only as many photos as the network allows, with a warning.

## What Reelspan accepts

| | |
| --- | --- |
| Formats | JPEG, PNG, WebP, GIF and HEIC (AVIF is also recognised). SVG, BMP and TIFF are refused. The type is read from the file's content, not its name. |
| Size | Up to **20 MB** per photo, on every plan. |
| Count | Up to **35** photos per request in `photos[]` / `photo_media_ids[]`; any more are ignored with a warning. |
| From a URL | Public `https://` URLs in `photos[]`, in order after any uploaded files. At most 100 media URLs per request. |
| Alt text | `alt_text[]` (one per photo, in order), one `alt_text` for all, or `{network}_alt_text` for one network. Sent to X, Instagram, Facebook, Threads, LinkedIn, Pinterest and Bluesky. |
| Per network | `{network}_photos[]` (URLs) or `{network}_photo_media_ids[]` give one network its own photos, for example `pinterest_photos[]` cropped to 2:3. |

A photo over 20 MB is refused with **413** `FILE_TOO_LARGE`, a file that isn't an image with **400** `UNSUPPORTED_MEDIA` or `WRONG_MEDIA_KIND`.

## Per network

| Network | Photos per post | What Reelspan does |
| --- | --- | --- |
| TikTok | 35 | A photo post. JPEG and WebP up to 20 MB go as they are; other photos are converted to JPEG (at most 1920 px). `photo_cover_index` picks the cover. |
| Instagram | 10 in a carousel | Instagram takes JPEG only: PNG, WebP and HEIC are converted (up to 8 MB). Carousels can mix in videos. `media_type=STORIES` posts each photo as a Story. Instagram wants shapes from 4:5 to 1.91:1. |
| Facebook | 30 in a Page post; 10 as Stories | `facebook_media_type=STORIES` shares each photo as its own Page Story. |
| Threads | 20 in a carousel | Carousels can mix in videos. |
| X | 4 | GIFs are sent as GIFs. |
| LinkedIn | 20 | Personal or company page. |
| Pinterest | 5 in a carousel | Needs `pinterest_board_id`. Every photo in a carousel must have the same shape; up to 20 MB each. |
| Bluesky | 4 | Each image must be under 1 MB; bigger ones are re-encoded. |
| Mastodon | 4 | |
| Telegram | 10 in an album | |
| Discord | 10 | Up to 10 MB per file. |
| Slack | 10 | |
| Nostr | 10 | Uploaded to your media server and linked in the note. |
| Whop | 10 | |
| Listmonk | 10 | Uploaded to Listmonk's media library and shown in the email; up to 20 MB each. |
| WordPress | All | Embedded in the blog post. |
| Lemmy | 1 | The first photo. |
| Reddit | 1 | An image post with the first photo, in `reddit_subreddit`. |
| Google Business | 1 | One photo per update. |
| YouTube, Dev.to, Hashnode | No photo posts | |

When a post has more photos than a network takes, the first ones are used and that network's result carries a warning such as "Instagram carousels hold 10 images; the first 10 of 12 were used." Sending photos to a network without photo posts refuses the request with **400** `UNSUPPORTED_POST_TYPE`.

## Shapes

The networks crop or letterbox photos differently. The shapes Reelspan lists for each network, preferred first (they cover video too):

| Network | Shapes |
| --- | --- |
| Instagram | 9:16, 4:5, 1:1 (photo carousels: 4:5 to 1.91:1) |
| Facebook | 9:16, 16:9 |
| X | 16:9, 1:1 |
| Threads | 4:5, 9:16 |
| LinkedIn | 1:1, 16:9 |
| Pinterest | 2:3, 9:16 |
| Bluesky | 16:9 |
| Google Business | 4:3, 1:1 |
| TikTok | 9:16 |

To give one network a different crop, send it its own photos with `{network}_photos[]` or `{network}_photo_media_ids[]`.

See [Post photos](/api/post-photos) for the request, and [Video requirements](/limits/video) for videos.

Source: https://docs.reelspan.com/limits/photos

---

# Character limits

> Caption, title and text limits for every network Reelspan posts to, which field carries each, and what Reelspan does with text that is too long.

`title` is the caption every network uses. To write something different for one network, send `{network}_title` (for example `x_title`, `instagram_title`), and `{network}_description` where the network has a separate body. This page lists how long each can be and what happens to longer text.

Reelspan doesn't refuse a request for long text. Depending on the network, it either **cuts** the text to fit (often with a warning in that network's result), turns it into a **thread**, or sends it as it is and the network decides.

## Per network

Characters are counted as people count them: an emoji is one.

| Network | Field | Limit | Longer text |
| --- | --- | --- | --- |
| YouTube | `youtube_title` (else `title`) | 100 | Cut to 100. A title is required. |
| YouTube | `youtube_description` (else `description`, else `title`) | 5,000 | Cut to 5,000. `<` and `>` are removed (YouTube refuses them). |
| TikTok | `tiktok_title` (else `title`), video | 2,200 | Cut to 2,200. |
| TikTok | photo post title | 90 | The first line of the caption, cut to 90. |
| TikTok | `tiktok_description`, photo post | 4,000 | Cut to 4,000. Defaults to the caption. |
| Instagram | `instagram_title` (else `title`) | 2,200 | Cut to 2,200. Instagram also allows up to 30 hashtags and 20 mentions. |
| Facebook | `facebook_title` / `facebook_description` | 63,206 | Sent as it is. On a Reel, `facebook_title` is also used as the video title, cut to 255. |
| X | `x_title` (else `title`) | 280 per post | Split into a thread of 280-character posts, with a warning. `x_long_text_as_post=true` sends one long post instead (needs X Premium). Links are removed unless `x_keep_links=true` (see below). |
| Threads | `threads_title` (else `title`) | 500 | Cut to 500. |
| LinkedIn | `linkedin_title` (else `title`) | 3,000 | Cut to 3,000. The first two lines show before "see more". |
| LinkedIn | video or document title | 400 | Cut to 400. |
| Pinterest | `pinterest_title` (else `title`) | 100 | Cut to 100. |
| Pinterest | `pinterest_description` (else `description`) | 800 | Cut to 800. |
| Bluesky | `bluesky_title` (else `title`) | 300 per post | Split into a thread of 300-character posts, with a warning. |
| Reddit | `reddit_title` (else the caption's first line) | 300 | Cut to 300. |
| Reddit | `reddit_description` | 40,000 | Sent as it is. |
| Google Business | `google_business_title` (else `title`) | 1,500 | Cut to 1,500, with a warning. |
| Telegram | `telegram_title` (else `title`) | 4,096 for a text message; 1,024 under a video, photos or a PDF | Cut, with a warning. |
| Discord | `discord_title` (else `title`) | 2,000 | Cut, with a warning. |
| Slack | `slack_title` (else `title`) | 40,000 | Through an Incoming Webhook the text block holds 3,000. |
| Mastodon | `mastodon_title` (else `title`) | 500 on most servers | Sent as it is; the server decides. |
| WordPress | `wordpress_title` (else the caption's first line) | 200 when taken from the caption | |
| WordPress | `wordpress_description` | 100,000 | Sent as it is. |
| Lemmy | `lemmy_title` / `lemmy_description` | 200 / 10,000 | Sent as they are; the server decides. |
| Nostr | `nostr_title` (else `title`) | 10,000 | Sent as it is. |
| Dev.to, Hashnode | `devto_title`, `hashnode_title` (else the caption's first line) | 250 | Cut to 250. |
| Dev.to, Hashnode | `devto_description`, `hashnode_description` (Markdown) | 100,000 | Sent as it is. |
| Whop | `whop_title` (else `title`) | 10,000 | Sent as it is. |
| Listmonk | `listmonk_title` / `listmonk_description` | 200 / 100,000 | The subject and the email body. |

Where the limit is shown but the text is "sent as it is", the network's own answer decides: text it refuses fails that network with an error code.

## Other text fields

| Field | Limit |
| --- | --- |
| Alt text | Instagram, Facebook, Bluesky 1,000; Pinterest 500; LinkedIn 4,086. Cut to fit. |
| Tags | Dev.to takes 4 tags and Hashnode 5; extra tags are dropped (Dev.to with a warning). |
| First comment (`first_comment`) | X 280, Threads 500, Bluesky 300, LinkedIn 1,250, Instagram 2,200, YouTube 10,000. Cut to fit. |
| `external_id` | 255 |
| `request_id` | 8 to 100 letters, digits, `_` or `-` |

## Links on X

X charges much more for a post that contains a link, so Reelspan removes links from X posts by default and adds a warning saying so. Send `x_keep_links=true` to keep them. Paid plans include a monthly number of X posts with links (Pro 20, Agency 60, Scale 200); past it, links are removed again. See [Plans and limits](/limits/plans).

## Threads on X and Bluesky

Long text is split at paragraph breaks where it can, then at line breaks, then between words; a single word longer than a post is cut. Each part is posted as a reply to the one before, and the result's warning says how many posts the thread has. Media goes on the first post.

Source: https://docs.reelspan.com/limits/characters

---

# Network posting limits

> The daily posting caps and quotas TikTok, YouTube, Instagram, Threads, Bluesky and X set on API posts, and the error code Reelspan returns for each.

Reelspan sets no daily cap per connected account of its own: on a paid plan you can post as often as your [rate limit](/rate-limits) allows. The networks do set caps on posts made through their APIs, and when one is reached, that network's result fails with a specific `error_code` while the other networks in the request carry on.

This page lists the limits Reelspan recognises and reports, and, where a network publishes a number, that number with a link to its documentation. Networks change these limits; their pages are the source of truth.

For Instagram and Threads, which tell apps how much of the day's quota an account has used, [`GET /v1/publishing-limits`](/api/publishing-limits) shows what is left before you post.

## Summary

| Network | Limit | `error_code` when reached | What Reelspan does |
| --- | --- | --- | --- |
| TikTok | A daily post cap per account (number not published) | `tiktok_spam_risk_too_many_posts` | Fails that network. Try again the next day. |
| TikTok | A daily cap on how many different accounts can post through one app | `tiktok_reached_active_user_cap` | Fails that network. |
| TikTok | 6 requests a minute per account | `tiktok_rate_limit_exceeded` | Retries automatically. |
| YouTube | Daily upload quota | `youtube_quotaExceeded`, `youtube_uploadLimitExceeded` | Fails that network; the message says to try tomorrow. |
| Instagram, Facebook | Graph API rate limits; Instagram also caps API-published posts per 24 hours | `meta_rate_limited` | Retries automatically. |
| Threads | 250 posts and 1,000 replies per 24 hours | `threads_error` | Retries Threads' rate-limit answers automatically; otherwise fails that network. |
| Bluesky | A daily video limit per account | `bluesky_video_limit` | Fails that network. Try again the next day. |
| X | X's rate limits | `x_rate_limited` | Retries automatically. |
| Reddit | Reddit's posting rate limit | `reddit_error` | Retries automatically. |

"Retries automatically" means Reelspan tries again up to four attempts in all, with pauses of 15, 30 and 60 seconds, before reporting the failure. A limit that lasts a day can outlast those retries; send the post again later with [Retry](/api/retry), which doesn't upload the media again.

## TikTok

TikTok's [Content Posting API reference](https://developers.tiktok.com/doc/content-posting-api-reference-direct-post) documents three limits that Reelspan maps to error codes:

- **Daily posts per account.** TikTok answers `spam_risk_too_many_posts` when "the daily post cap from the API is reached for the current user". TikTok doesn't publish the number. Reelspan reports it as `tiktok_spam_risk_too_many_posts`.
- **Active publishing users per app.** `reached_active_user_cap` means the app (Reelspan's) has reached TikTok's daily quota of accounts that publish through it. Reelspan reports it as `tiktok_reached_active_user_cap`. It is not about your account; try again later.
- **Requests per minute.** Each account's token is limited to 6 requests a minute. Reelspan retries `tiktok_rate_limit_exceeded` on its own.

Separately, TikTok limits video length per account; Reelspan checks it before posting (`tiktok_duration_too_long`).

## YouTube

YouTube's [quota documentation](https://developers.google.com/youtube/v3/determine_quota_cost) says `videos.insert` has its own quota bucket with a default daily limit of 100 calls per API project. The quota belongs to the app making the uploads, not to your channel. YouTube may also refuse uploads from a channel that has uploaded too much in a day.

Either way, Reelspan reports YouTube's reason in the code: `youtube_quotaExceeded` or `youtube_uploadLimitExceeded`, with a message to try again tomorrow. These are not retried automatically.

## Instagram

Instagram's [content publishing documentation](https://developers.facebook.com/docs/instagram-platform/content-publishing) limits each account to 100 API-published posts within a moving 24-hour period (the same page also mentions 50 in its carousel section). Meta's rate-limit answers come back as `meta_rate_limited` and are retried automatically. To see how many posts an account has left, ask [Publishing limits](/api/publishing-limits): it reads Instagram's own count for the account (Instagram reports a quota of 50, and a carousel counts as one post).

## Threads

The [Threads API overview](https://developers.facebook.com/docs/threads/overview) limits each profile to 250 API-published posts and 1,000 replies within a moving 24-hour period. A `first_comment` on Threads is posted as a reply. Reelspan retries Threads' rate-limit answers; other refusals fail with `threads_error`. [Publishing limits](/api/publishing-limits) shows how many posts and replies the account has left.

## Bluesky

Bluesky limits how much video an account can upload per day. When Bluesky's video service says the limit is reached, Reelspan fails Bluesky with `bluesky_video_limit` ("Bluesky's daily video limit for this account is used up… Retry tomorrow."). Text and photo posts are not affected.

## X

X's rate-limit answers (HTTP 429) are reported as `x_rate_limited` and retried automatically. X also bills Reelspan per post, much more for posts with links, which is why links are removed unless you send `x_keep_links=true`; see [Character limits](/limits/characters).

## What isn't capped

- Reelspan has no per-account or per-profile daily cap of its own.
- Paid plans have no monthly upload limit; the Free plan has 15 uploads a month. See [Plans and limits](/limits/plans).
- Your workspace's request rate is limited per plan; see [Rate limits](/rate-limits).

Source: https://docs.reelspan.com/limits/network-limits

---

# Plans and limits

> What each Reelspan plan includes: monthly uploads, profiles, seats, file sizes, library storage, AI caption credits, API rate limits and white-label.

Every plan has every network, the full API, the SDKs, scheduling, the queue and webhooks. Plans differ in how much you can do. Prices and the current offer are on [reelspan.com/pricing](https://reelspan.com/pricing).

## At a glance

| | Free | Starter | Pro | Agency | Scale |
| --- | --- | --- | --- | --- | --- |
| Uploads a month | 15 | Unlimited | Unlimited | Unlimited | Unlimited |
| Profiles | 1 | 5 | 25 | 75 | 225 |
| Team seats | 1 | 1 | 3 | 5 | 10 |
| Largest video | 0.5 GB | 1 GB | 2 GB | 4 GB | 8 GB |
| Media library | 1 GB | 25 GB | 100 GB | 250 GB | 500 GB |
| AI caption credits a month | 10 | 100 | 400 | 1,000 | 2,500 |
| API requests a minute | 60 | 60 | 100 | 200 | 500 |
| API requests per 10 minutes | 300 | 300 | 500 | 1,000 | 2,500 |
| X posts with links a month | 0 | 0 | 20 | 60 | 200 |
| White-label connect | | | Yes | Yes | Yes |
| Priority support | | | | Yes | Yes |

## Uploads

An upload is one post on one network: a video sent to TikTok, YouTube and Instagram is three uploads. Only the Free plan has a monthly limit; on paid plans the [rate limit](/rate-limits) is the only ceiling.

- The count is taken when a post is accepted, for each network it will be sent to. Networks skipped at once (for example with no account connected) aren't counted.
- Scheduled and queued posts count when you schedule them. Cancelling one refunds its uploads.
- [Retrying](/api/retry) a failed network counts again, like a new upload.
- Posts made with a [test key](/guides/test-mode) never count.
- The count resets on the 1st of each month at 00:00 UTC.

A post that would go over the limit is refused with **429** and your `usage`. Read the current count any time with [Current account](/api/me):

```bash title="cURL"
curl https://api.reelspan.com/v1/me -H "Authorization: Bearer $REELSPAN_API_KEY"
```

```javascript title="Node.js"
const me = await reelspan.me();
console.log(me.plan, me.api_usage); // 'free' { count: 4, limit: 15, last_reset: '2026-11-01T00:00:00.000Z' }
```

```python title="Python"
me = reelspan.me()
print(me["plan"], me["api_usage"])
```

`limit` is `null` on plans without a monthly limit. Successful post responses carry the same `usage` object.

## Profiles and seats

A profile holds one account per network, usually one brand or one client. Creating a profile past your plan's count is refused with **403** `PROFILE_LIMIT_REACHED`; `GET /v1/profiles` returns your `limit` alongside the list. Seats are the people in your workspace, including pending invites.

## Files and storage

- **Videos** up to your plan's size, however they arrive. Files over 100 MB go up with a [direct upload](/guides/large-files).
- **Photos** up to 20 MB and **documents** (PDF, PowerPoint, Word) up to 100 MB, on every plan.
- The **media library** keeps files you choose to save, for reuse, and is never cleared automatically. Saving past your storage is refused with **413** `LIBRARY_FULL`. Media you don't save is deleted after its post finishes and a retention period passes.

## AI caption credits

Each caption generation (from a video, from your notes, or a rewrite) uses one credit, charged only when it succeeds. Credits reset on the 1st with your uploads. With none left, the AI caption endpoints answer **429** `AI_CREDITS_EXHAUSTED`. See [AI captions](/api/ai-captions).

## X posts with links

X charges far more for a post that contains a link, so Reelspan removes links from X posts unless you send `x_keep_links=true`. Plans include a monthly number of X posts that keep their links; past it, links are removed with a warning and the post still goes out. See [Character limits](/limits/characters).

## Changing plan

Upgrade or downgrade in the dashboard under **Billing**. New limits apply as soon as the plan changes. Need more than 225 profiles? [Contact us](https://reelspan.com/contact).

Source: https://docs.reelspan.com/limits/plans

---

# Troubleshooting

> Fix common Reelspan problems by symptom: reconnecting accounts, TikTok privacy, Instagram processing, YouTube quota, large files and rate limits.

Find the symptom, check the `error_code` in the response or in that network's result, and apply the fix. Every code is listed on [Errors](/errors).

> [!TIP]
> Most network failures can be sent again without uploading the media: `POST /v1/posts/retry` with the `request_id` resends only the networks that failed. See [Retry](/api/retry).

## Requests refused

### 401: "Invalid API key" or "API key expired"

**Cause:** the `Authorization` header is missing, misspelled, or holds a revoked or expired key.
**Fix:** send `Authorization: Bearer rs_live_…` (or `rs_test_…`) exactly; no quotes, no `Apikey` prefix. Check the key in the dashboard under API keys and create a new one if it was revoked or expired. After 10 failed attempts in 5 minutes your IP address is refused for up to 5 minutes (`AUTH_RATE_LIMITED`), so fix the key before retrying.

### 421 `USE_API_HOST`

**Cause:** the request went to `app.reelspan.com`, the dashboard's address.
**Fix:** use `https://api.reelspan.com/v1`, as given in the response's `api_url`.

### 403 `INSUFFICIENT_SCOPE` or `PROFILE_FORBIDDEN`

**Cause:** the key was created with limited scopes, or limited to some profiles.
**Fix:** use a key with the scope named in the message (`publish`, `read`, `profiles`, `analytics`, `webhooks`), or one allowed on that profile. See [Authentication](/authentication).

### 404 "User not found" (`PROFILE_NOT_FOUND`)

**Cause:** `user` must be the profile's **username** in your workspace, not a display name or a network handle.
**Fix:** list your profiles with `GET /v1/profiles` and use the `username`.

### 400 "None of the requested platforms are valid for profile…"

**Cause:** every network you asked for is unusable on this profile: not connected, or needing reconnection. The body's `invalid_platforms` gives the reason for each.
**Fix:** connect the accounts to the profile (see [Connecting accounts](/connecting-accounts)), or reconnect them.

### 400 `INVALID_REQUEST` naming a network

**Cause:** a network's required field is missing: YouTube needs a title (`title` or `youtube_title`), Pinterest a `pinterest_board_id`, Reddit a `reddit_subreddit`.
**Fix:** add the field. Pinterest boards are listed by `GET /v1/pinterest/boards`.

### 400 `UNSUPPORTED_POST_TYPE`

**Cause:** the network has no API for this kind of post: text-only to Instagram, TikTok or Pinterest; video to Google Business; a document anywhere but LinkedIn.
**Fix:** drop that network from this request.

### 413 `FILE_TOO_LARGE`, or the upload breaks off

**Cause:** the video is over your plan's size, a photo over 20 MB or a PDF over 100 MB; or a single request carried more than 100 MB.
**Fix:** for big files use a direct upload, or let the SDK do it (it switches at 90 MB). A video over your plan's limit needs a smaller file or a bigger plan. See [Large files](/guides/large-files).

### 400 `URL_FETCH_FAILED`

**Cause:** Reelspan couldn't download the media URL: it isn't `https://`, isn't public, needs a sign-in, points to a private address, or redirects more than three times.
**Fix:** open the URL in a private browser window; it must download the file directly. For Google Drive, share the file with "Anyone with the link".

### 429 `RATE_LIMITED`

**Cause:** too many requests in the current minute or 10 minutes for your plan, often from polling.
**Fix:** wait for `Retry-After`, poll every 5 seconds or more, or use webhooks. See [Rate limits](/rate-limits).

### 429 with `usage`, or `USAGE_LIMIT`

**Cause:** the Free plan's 15 uploads this month are used (one per network per post).
**Fix:** wait for the 1st (UTC), or upgrade. Test posts with an `rs_test_` key don't count.

### 409 `IDEMPOTENCY_KEY_IN_USE`

**Cause:** you retried while the first request with the same key was still being received.
**Fix:** wait a few seconds and send it again with the same key. See [Retrying safely](/guides/idempotency).

### 409 `REQUEST_ID_IN_USE`

**Cause:** the `request_id` you chose was used before.
**Fix:** read that request's status instead of posting again, or choose a new id for a new post.

### 409 `scheduled_post_in_progress`

**Cause:** the scheduled post is publishing or due within a minute.
**Fix:** wait for it to finish, then retry or delete the posts on the network if needed.

## A network failed

### `reauth_required` or `token_error`

**Cause:** the network no longer accepts the account's access: the password changed, access was revoked, the token expired, or a permission was removed. Reelspan marks the account for reconnection and sends a `social_account_reauth_required` webhook.
**Fix:** reconnect the account in the dashboard (or send your client a new connect link), then retry the post.

### `profile_platform_mapping_invalid` (skipped)

**Cause:** the profile has no active account on that network, at the time the post ran.
**Fix:** connect one. For scheduled posts, connect it before the post's time.

### `tiktok_privacy_unavailable`

**Cause:** the `privacy_level` you sent isn't one this TikTok account may use. TikTok decides the levels per account.
**Fix:** use one of the levels listed in the message, or read the account's options first with `GET /v1/tiktok/creator-info`. Leave `privacy_level` out and Reelspan picks `PUBLIC_TO_EVERYONE` when allowed, else the account's first option.

### A TikTok post went out as private ("Only me")

**Cause:** until Reelspan's app passes TikTok's audit, TikTok accepts direct posts only as private. When TikTok refuses a public post for this reason, Reelspan posts it as private instead and adds a warning to the result. If even that is refused, the result fails with `tiktok_unaudited_client_can_only_post_to_private_accounts`.
**Fix:** make the post public in the TikTok app; or make the TikTok account itself private (Settings → Privacy) before posting; or post with `post_mode=MEDIA_UPLOAD` to send the video to the TikTok inbox and finish it in the app.

### `tiktok_duration_too_long`

**Cause:** the video is longer than TikTok allows this account.
**Fix:** trim it to the length in the message.

### `tiktok_spam_risk_too_many_posts` or `tiktok_reached_active_user_cap`

**Cause:** a TikTok daily limit: posts for this account, or accounts posting through Reelspan's app.
**Fix:** retry the next day. See [Network posting limits](/limits/network-limits).

### `instagram_processing_timeout`

**Cause:** Instagram was still processing the video when Reelspan stopped waiting. It may still appear on the account.
**Fix:** check the account first. If the post isn't there after a few minutes, retry. Very large or long videos process slowest.

### `instagram_processing_failed`, `facebook_processing_failed`

**Cause:** the network couldn't process the file: an unusual codec, shape or length for that network.
**Fix:** export as H.264 with AAC audio in an MP4, in a shape the network takes (9:16 for Reels and Stories), and retry. See [Video requirements](/limits/video).

### `facebook_page_required` or `facebook_page_not_connected`

**Cause:** no Facebook Page is chosen for the profile, or the Page wasn't shared with Reelspan when connecting.
**Fix:** reconnect Facebook and select the Page. `GET /v1/facebook/pages` lists the Pages Reelspan can post to.

### `meta_permission_denied`

**Cause:** a permission Reelspan needs was removed from the Facebook or Instagram connection.
**Fix:** reconnect and accept every permission.

### `youtube_quotaExceeded` or `youtube_uploadLimitExceeded`

**Cause:** YouTube's daily upload limit was reached.
**Fix:** retry the next day. See [Network posting limits](/limits/network-limits).

### `youtube_youtubeSignupRequired`

**Cause:** the Google account has no YouTube channel.
**Fix:** create a channel on YouTube, then reconnect.

### `x_payment_required`

**Cause:** X refused the call for billing reasons on the API side.
**Fix:** retry later; if it keeps happening, [contact support](/support) with the `request_id`.

### Links missing from an X post

**Cause:** Reelspan removes links from X posts by default, with a warning in the result.
**Fix:** send `x_keep_links=true`. Your plan includes a monthly number of X posts with links. See [Character limits](/limits/characters).

### `bluesky_video_too_large`

**Cause:** Bluesky takes videos up to 100 MB.
**Fix:** send `bluesky_compress=true` and Reelspan compresses it for Bluesky, or upload a smaller file.

### `bluesky_email_unconfirmed`

**Cause:** Bluesky needs the account's email confirmed before it takes video.
**Fix:** confirm the email in Bluesky's settings and retry.

### `file_too_large` on Telegram, Discord or Mastodon

**Cause:** the network's own file limit: Telegram 50 MB, Discord 10 MB, Mastodon 99 MB.
**Fix:** send a smaller file to that network in a separate request.

### `bot_not_admin` (Telegram)

**Cause:** your bot isn't an admin of the channel or group with permission to post.
**Fix:** add the bot as an admin who can post messages, then retry.

### A `*_processing_timeout` code

**Cause:** the network was still processing the media when Reelspan stopped waiting.
**Fix:** check whether the post appeared before retrying, so it isn't posted twice.

## Other problems

### The response has no `results`

**Cause:** the request moved to the background: you sent `async_upload=true`, or the networks took longer than 59 seconds.
**Fix:** poll `GET /v1/posts/status?request_id=…` or use webhooks. See [Async posts](/guides/async-uploads).

### A post was published twice

**Cause:** a request was retried after a timeout without an `Idempotency-Key`.
**Fix:** send an `Idempotency-Key` on every post (the SDKs do), or choose your own `request_id`. See [Retrying safely](/guides/idempotency).

### Retry answers `retry_media_expired`

**Cause:** the post's media has been deleted after its retention period.
**Fix:** post it again with the file. Keep media you reuse in the [media library](/api/library).

### Webhooks stopped arriving

**Cause:** an endpoint is switched off after 20 failed deliveries in a row, each already retried for a day.
**Fix:** fix the endpoint, then turn it on again by saving the webhook. Missed deliveries can be listed and sent again. See [Webhooks](/webhooks).

Still stuck? Email [support](/support) with the `request_id`.

Source: https://docs.reelspan.com/troubleshooting

---

# FAQ

> Answers to common Reelspan questions on connecting accounts, limits, uploads, scheduling, errors, test mode, white-label and moving from Upload-Post.

Short answers, with links to the page that has the detail.

## Accounts and connecting

### Do I need my own TikTok, Meta or Google developer app?

No. TikTok, YouTube, Instagram, Facebook, X, Threads, LinkedIn, Pinterest, Reddit and Google Business connect through Reelspan's own apps with the network's usual sign-in, so you don't need an app, an API review or a quota of your own. A few networks connect with something you create on their side instead: a bot for Telegram, a channel webhook for Discord, a Slack app, an app password for Bluesky, an access token for Mastodon, and so on. See [Connecting accounts](/connecting-accounts).

### What is a profile?

A profile holds one account per network, usually one brand or one client. You name the profile in `user` when you post, and the post goes to that profile's accounts. Your plan sets how many profiles you can have. See [Profiles](/api/profiles).

### Are limits per profile, per account or per workspace?

Per workspace. Rate limits, monthly uploads (Free plan), AI credits and storage are shared by every key and profile in the workspace. Reelspan has no daily cap per connected account; the networks have their own. See [Plans and limits](/limits/plans) and [Network posting limits](/limits/network-limits).

### Does Instagram need a Facebook Page?

Yes. Instagram connects through Facebook Login, and Reelspan posts to the Instagram professional (Business or Creator) account linked to a Facebook Page you manage. Connecting Facebook once covers both; each is still its own connection on the profile.

### How do my clients connect their accounts without giving me their passwords?

Create a connect link for their profile (`POST /v1/connect-links`). It is valid for 48 hours and needs no Reelspan login; the client signs in to each network themselves. On Pro and above the page can carry your logo and texts. See [White-label connect](/white-label).

### Why does an account suddenly need reconnecting?

The network stopped accepting its access: the password changed, access was revoked, a permission was removed, or the token ran out (LinkedIn's last 60 days and can't be renewed without the person). Reelspan refreshes tokens itself wherever the network allows. When one fails, posts to it fail with `reauth_required` and a `social_account_reauth_required` webhook is sent. See [Troubleshooting](/troubleshooting).

## Posting

### What happens if one network fails?

Only that network fails. Each network in `results` has its own `success`, `url` and `error_code`, and the others publish normally. Send just the failed ones again with [Retry](/api/retry); the media isn't uploaded again.

### How do I know a post went live?

A request that finishes within 59 seconds returns each network's `url` in `results`. Otherwise poll [Post status](/api/post-status) with the `request_id`, or receive an `upload_completed` [webhook](/webhooks) per network. See [Async posts](/guides/async-uploads).

### How big can a video be?

Up to your plan's limit: 0.5 GB on Free, up to 8 GB on Scale. Files over 100 MB go up with a direct upload, which the SDKs do for you. Each network has its own limits too. See [Large files](/guides/large-files) and [Video requirements](/limits/video).

### Can I post from a URL instead of uploading?

Yes. `video`, `photos[]` and `document` take a public `https://` URL, including Google Drive and Dropbox share links. See [Large files](/guides/large-files).

### Can I post the same video to several profiles?

One request posts to one profile. Upload the video once with [Upload media](/api/upload-media), then send one post per profile with the same `video_media_id`.

### Can I write a different caption for each network?

Yes. `title` is used everywhere, and `{network}_title` (such as `tiktok_title`, `x_title`) replaces it on one network. Long text becomes a thread on X and Bluesky. See [Character limits](/limits/characters).

### How do I post a YouTube Short?

Post a vertical (or square) video of 3 minutes or less to `youtube`; YouTube treats it as a Short, and Reelspan returns the `youtube.com/shorts/` URL. There is no separate endpoint.

### Can I edit or delete a post after it is published?

On most networks, yes. [Unpublish](/api/unpublish) deletes a live post on Facebook, LinkedIn, X, Pinterest, Bluesky, Google Business, Discord, Telegram, Mastodon and WordPress, and [Edit a post](/api/edit-post) changes its text on the same networks except Bluesky. Instagram, TikTok, Threads and YouTube posts can't be changed or deleted through Reelspan (a YouTube video's thumbnail can, with [YouTube thumbnail](/api/youtube-thumbnail)). Until a post is published, you can edit or cancel it as a [scheduled post](/guides/scheduling).

### Can I add a first comment?

Yes: `first_comment` is posted right after the post goes live (as a reply on X, Bluesky and Threads), and `{network}_first_comment` overrides it for one network. If a network has no comments API or refuses, the post still counts and its result carries a warning.

## Scheduling

### How far ahead can I schedule, and in which timezone?

Up to 365 days ahead. Send `scheduled_date` in ISO 8601 with an offset, or a local time plus an IANA `timezone` such as `Europe/Berlin`. You can also add posts to a profile's queue or repeat them daily, weekly or monthly. See [Scheduling and repeats](/guides/scheduling).

### Can a client approve posts before they go out?

Yes. Put scheduled posts in an approval link; each waits until the client approves it. See [Approval links](/api/approval-links).

## Building and testing

### How do I test without publishing anything?

Use a test key (`rs_test_…`). Posts go through every check but are not sent to the networks and don't count against your plan. The `sandbox` network lets you rehearse successes and failures. See [Test mode](/guides/test-mode).

### How do I avoid posting twice when I retry?

Send an `Idempotency-Key` header; a retry with the same key returns the first result instead of posting again. The SDKs add one to every post. See [Retrying safely](/guides/idempotency).

### Can I use Reelspan from n8n, Make, Zapier or an AI agent?

Yes. No-code tools call the API with their HTTP request step; see [n8n](/integrations/n8n), [Make](/integrations/make) and [Zapier](/integrations/zapier). AI assistants and agent frameworks connect to the [MCP server](/integrations/mcp).

### I use Upload-Post. How much do I have to change?

Very little: Reelspan takes the same request shapes and field names. Change the base URL to `https://api.reelspan.com/v1` and send your Reelspan key as `Authorization: Bearer <key>`. See [Migrate from Upload-Post](/migrate-from-upload-post).

## Plans

### What does "unlimited uploads" mean?

Paid plans have no monthly upload count. The ceiling is your plan's API rate limit, which every request counts against. The Free plan has 15 uploads a month, one per network per post. See [Plans and limits](/limits/plans).

### What happens when I reach the Free plan's limit?

Posts are refused with 429 and your `usage` until the 1st of the next month (UTC), or until you upgrade. Test-key posts are never counted.

Source: https://docs.reelspan.com/faq

---

# Versioning

> How the Reelspan API changes: what can change in v1 at any time, what counts as breaking, the notice and 12-month overlap you get, and SDK versions.

Code you write against `/v1` keeps working. New features arrive without breaking it, and anything that would break it waits for a new version, with a year of overlap.

## The version is in the path

Every endpoint lives under `https://api.reelspan.com/v1`. There is one stable version today, v1. A future v2 would live beside it at `/v2`, so you could move one call at a time.

## Changes that can happen any time

These don't break a well-behaved client, so they ship to v1 whenever they are ready and are listed in the [changelog](https://reelspan.com/changelog):

- New endpoints, and new optional request fields or query parameters.
- New fields in responses and in webhook payloads. Ignore fields you don't know.
- New values in lists such as networks, error codes, warnings and webhook events. Handle unknown values gracefully.
- Higher limits, clearer error messages and new response headers. Match on `error_code`, never on the message text.

Write your client with that in mind: parse JSON leniently, treat an unknown `error_code` by its HTTP status, and don't rely on the order of keys.

## Breaking changes

Removing or renaming a field or endpoint, changing a field's type or meaning, making an optional field required, or changing how authentication works. These only ship in a new version, and then:

- We announce it at least **90 days** before the new version becomes the default, by email to every account owner with an active API key, and in the changelog.
- The old version keeps working for at least **12 months** after the new one ships.
- Responses from an endpoint that is going away carry `Deprecation` and `Sunset` headers with the date, and a `Link` to the migration guide.

```
Deprecation: @1798761600
Sunset: Mon, 01 Nov 2027 00:00:00 GMT
Link: <https://reelspan.com/…>; rel="deprecation"
```

A security problem is the one exception: if keeping something as it is would put accounts at risk, we change it as fast as needed and tell you why.

## Networks change too

TikTok, Meta, Google and the other networks change their own APIs and rules. When a network drops or changes a feature, Reelspan adapts on its side. If a field can no longer work, the request still succeeds and the result carries a warning before the field is ever refused.

## SDKs and tools

- **Node.js / TypeScript:** `npm install reelspan`. See [SDKs](/sdks).
- **Python:** `pip install reelspan`.
- **OpenAPI 3.1:** [api.reelspan.com/openapi.json](https://api.reelspan.com/openapi.json), for generating a client in any language.
- **Postman:** import [reelspan.com/postman.json](https://reelspan.com/postman.json) and set the `apiKey` variable. It is built from the live spec, so it always matches the API. See [Postman](/integrations/postman).

The SDKs follow semantic versioning: a new major version only when their own interface changes, never just because the API added something. Both send their version in an `X-Reelspan-SDK` header.

Source: https://docs.reelspan.com/versioning

---

# Support

> How to get help with Reelspan: email support, check the live status page, report a security problem, and what to include so we can fix it fast.

A person on the Reelspan team reads every message. Before you write, two quick checks often answer the question:

- **Is something down?** The site, the dashboard and the API are checked every minute at [status.reelspan.com](https://status.reelspan.com).
- **Is it a known error?** Look the `error_code` up in [Errors](/errors) or [Troubleshooting](/troubleshooting).

## Email

Write to [support@reelspan.com](mailto:support@reelspan.com). We reply within one business day, usually sooner. The Agency and Scale plans include priority support. You can also use the form at [reelspan.com/contact](https://reelspan.com/contact).

## What to include

The fastest fixes start with:

- **The `request_id`** of the post (and the `job_id` if it was scheduled). It is in every post response, in [Post status](/api/post-status), in history and in webhooks, and it lets us find exactly what happened on each network.
- **The network** that failed and its `error_code` and `error` from the result.
- **What you sent:** the endpoint, the fields (without the file), and the time with its timezone.
- **What you got back:** the HTTP status and the response body.
- **The profile's username**, if the problem is with one profile or account.
- **The SDK and version**, if you use one.

> [!WARNING]
> Never send your API key, a webhook signing secret, or a network password. We don't need them to investigate. If a key was exposed, revoke it in the dashboard under API keys and create a new one.

## Security problems

If you found a vulnerability, please don't post it publicly. Email [support@reelspan.com](mailto:support@reelspan.com?subject=Security%20report) with "Security report" in the subject, and read the [vulnerability disclosure policy](https://reelspan.com/security/disclosure) for what is in scope, the rules for testing (use a test key, `rs_test_…`, so nothing is posted) and safe harbour. We reply within two working days.

## Feature requests

Missing a network, a field or an endpoint? Email support with what you are trying to do. New features are announced in the [changelog](https://reelspan.com/changelog).

Source: https://docs.reelspan.com/support