# SwapFlow API Documentation

> Publish content to social media platforms programmatically using the SwapFlow REST API.

Base URL: `https://www.swapflow.top`

---

## Overview

The SwapFlow API lets you publish to any connected social platform using curl, scripts, or your own tools.

### Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/cli/connections` | List your social accounts |
| POST | `/api/cli/publish` | Publish content immediately (synchronous) |
| POST | `/api/cli/posts` | Schedule or queue a post (asynchronous) |
| GET | `/api/cli/posts` | List posts (filter by status, platform, date) |
| GET | `/api/cli/posts/:id` | Get post details |
| PATCH | `/api/cli/posts/:id` | Update a scheduled post |
| DELETE | `/api/cli/posts/:id` | Cancel a scheduled post |

---

## Authentication

All requests require authentication via one of two methods:

### API Key (Recommended)

Include your SwapFlow API key in the `X-API-Key` header:

```bash
curl -s "https://www.swapflow.top/api/cli/connections" \
  -H "X-API-Key: sf_your_api_key_here" | jq .
```

Generate API keys in your [SwapFlow dashboard](https://www.swapflow.top/dashboard/settings/swapflow-api).

### Bearer Token (Alternative)

Use a Supabase access token (expires after 1 hour):

```bash
TOKEN=$(curl -s -X POST "SUPABASE_URL/auth/v1/token?grant_type=password" \
  -H "apikey: YOUR_SUPABASE_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}' \
  | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)

curl -s "https://www.swapflow.top/api/cli/connections" \
  -H "Authorization: Bearer $TOKEN" | jq .
```

---

## Quick Start

### 1. List your connected accounts

```bash
curl -s "https://www.swapflow.top/api/cli/connections" \
  -H "X-API-Key: sf_your_api_key_here" | jq .
```

### 2. Publish content

```bash
curl -X POST "https://www.swapflow.top/api/cli/publish" \
  -H "X-API-Key: sf_your_api_key_here" \
  -F "file=@photo.jpg" \
  -F "connectionId=YOUR_CONNECTION_ID" \
  -F "platform=twitter" \
  -F "caption=Posted from the API!"
```

---

## Endpoints

### GET /api/cli/connections

List all connected social media accounts.

```bash
curl -s "https://www.swapflow.top/api/cli/connections" \
  -H "X-API-Key: sf_your_api_key_here" | jq .
```

**Response:**

```json
[
  {
    "id": "uuid",
    "platform": "twitter",
    "accountName": "My Account",
    "accountUsername": "@handle"
  }
]
```

---

### POST /api/cli/publish

Publish content to a connected social platform.

#### File Upload (multipart/form-data)

```bash
curl -X POST "https://www.swapflow.top/api/cli/publish" \
  -H "X-API-Key: sf_your_api_key_here" \
  -F "file=@video.mp4" \
  -F "connectionId=CONNECTION_ID" \
  -F "platform=tiktok" \
  -F "caption=Check this out! #ai" \
  -F "tiktokUserConsent=true" \
  -F "tiktokPrivacyLevel=SELF_ONLY"
```

#### Multi-Image / Carousel

```bash
curl -X POST "https://www.swapflow.top/api/cli/publish" \
  -H "X-API-Key: sf_your_api_key_here" \
  -F "file1=@photo1.jpg" \
  -F "file2=@photo2.jpg" \
  -F "file3=@photo3.jpg" \
  -F "connectionId=CONNECTION_ID" \
  -F "platform=instagram-standalone" \
  -F "caption=My carousel post"
```

Max images per platform: Instagram (10), Twitter (4), Threads (10), Facebook (10), LinkedIn (9), TikTok (35).

#### Text-Only Post (JSON)

```bash
curl -X POST "https://www.swapflow.top/api/cli/publish" \
  -H "X-API-Key: sf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "CONNECTION_ID",
    "platform": "twitter",
    "caption": "Hello from the SwapFlow API!"
  }'
```

#### Multi-Platform Publishing

Publish the same content to multiple platforms with separate calls. No need to re-upload — use the same file each time:

```bash
# Post to Twitter
curl -X POST "https://www.swapflow.top/api/cli/publish" \
  -H "X-API-Key: sf_your_api_key_here" \
  -F "file=@photo.jpg" \
  -F "connectionId=TWITTER_CONNECTION_ID" \
  -F "platform=twitter" \
  -F "caption=Check this out!"

# Same file to Instagram
curl -X POST "https://www.swapflow.top/api/cli/publish" \
  -H "X-API-Key: sf_your_api_key_here" \
  -F "file=@photo.jpg" \
  -F "connectionId=INSTAGRAM_CONNECTION_ID" \
  -F "platform=instagram-standalone" \
  -F "caption=Check this out!"
```

---

### POST /api/cli/posts

Schedule a post for future publishing or queue for immediate async publish. Posts are published automatically by the scheduling engine (up to 5-minute precision).

#### Schedule a Post

```bash
curl -X POST "https://www.swapflow.top/api/cli/posts" \
  -H "X-API-Key: sf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "CONNECTION_ID",
    "caption": "Launching tomorrow! 🚀",
    "scheduledAt": "2026-04-01T15:30:00Z"
  }'
```

#### Schedule with File Upload

```bash
curl -X POST "https://www.swapflow.top/api/cli/posts" \
  -H "X-API-Key: sf_your_api_key_here" \
  -F "file=@video.mp4" \
  -F "connectionId=CONNECTION_ID" \
  -F "caption=Check this out!" \
  -F "scheduledAt=2026-04-01T15:30:00Z" \
  -F 'platformSettings={"tiktok":{"privacyLevel":"PUBLIC_TO_EVERYONE"}}'
```

#### Schedule with Webhook

```bash
curl -X POST "https://www.swapflow.top/api/cli/posts" \
  -H "X-API-Key: sf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "CONNECTION_ID",
    "caption": "Scheduled via API",
    "scheduledAt": "2026-04-01T15:30:00Z",
    "webhookUrl": "https://example.com/webhook"
  }'
```

**Response (202 Accepted):**

```json
{
  "id": "uuid",
  "status": "scheduled",
  "platform": "twitter",
  "scheduledAt": "2026-04-01T15:30:00Z",
  "caption": "Launching tomorrow! 🚀",
  "createdAt": "2026-03-30T10:00:00Z"
}
```

---

### GET /api/cli/posts

List your posts with optional filtering.

```bash
# List all scheduled posts
curl -s "https://www.swapflow.top/api/cli/posts?status=scheduled" \
  -H "X-API-Key: sf_your_api_key_here" | jq .

# Filter by platform and date range
curl -s "https://www.swapflow.top/api/cli/posts?platform=tiktok&from=2026-04-01&to=2026-04-30" \
  -H "X-API-Key: sf_your_api_key_here" | jq .
```

**Query parameters:**

| Parameter | Default | Description |
|-----------|---------|-------------|
| limit | 50 | Number of posts to return (max 100) |
| status | all | Filter: scheduled, published, failed, cancelled |
| platform | all | Filter by platform (twitter, tiktok, etc.) |
| from | — | Start date filter (ISO 8601) |
| to | — | End date filter (ISO 8601) |

---

### GET /api/cli/posts/:id

Get full details of a specific post.

```bash
curl -s "https://www.swapflow.top/api/cli/posts/POST_ID" \
  -H "X-API-Key: sf_your_api_key_here" | jq .
```

---

### PATCH /api/cli/posts/:id

Update a scheduled post. Only posts with `status: "scheduled"` can be updated.

```bash
curl -X PATCH "https://www.swapflow.top/api/cli/posts/POST_ID" \
  -H "X-API-Key: sf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Updated caption",
    "scheduledAt": "2026-04-02T12:00:00Z"
  }'
```

**Updatable fields:** `caption`, `scheduledAt`, `platformSettings`, `webhookUrl`

> To change the target connection or media, cancel the post and create a new one.

---

### DELETE /api/cli/posts/:id

Cancel a scheduled post. Only posts with `status: "scheduled"` can be cancelled.

```bash
curl -X DELETE "https://www.swapflow.top/api/cli/posts/POST_ID" \
  -H "X-API-Key: sf_your_api_key_here"
```

**Response:**

```json
{ "success": true, "status": "cancelled" }
```

---

## Parameters Reference

### POST /api/cli/publish

| Parameter | Required | Description |
|-----------|----------|-------------|
| connectionId | Yes | UUID of the target social connection |
| platform | Yes | Platform name (see Supported Platforms) |
| file | No | Media file to upload (multipart/form-data) |
| file1, file2, ... | No | Multiple image files for carousel/multi-image posts |
| mediaId | No | UUID of existing media from /api/media |
| mediaIds | No | JSON array of media UUIDs for multi-image posts |
| mediaUrl | No | Direct URL to media file |
| caption | No | Post text or caption |
| mediaType | No | video, image, or text (auto-detected from file) |
| tiktokUserConsent | TikTok only | Must be `true` to publish to TikTok |
| tiktokPrivacyLevel | No | SELF_ONLY, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, or PUBLIC_TO_EVERYONE |
| youtubePrivacy | No | public, private, or unlisted (default: private) |
| youtubeIsShorts | No | true for Shorts, false for long-form (default: true) |
| pinterestBoardId | Pinterest only | Pinterest board ID |
| snapchatType | No | spotlight or stories (default: spotlight) |

---

### POST /api/cli/posts

| Parameter | Required | Description |
|-----------|----------|-------------|
| connectionId | Yes | UUID of the target social connection |
| caption | Yes | Post text or caption |
| scheduledAt | No | ISO 8601 date for future publish (min 5 min ahead). Omit for immediate async publish |
| file | No | Media file to upload (multipart/form-data) |
| mediaId | No | UUID of existing media from /api/media |
| mediaUrl | No | Direct URL to media file |
| platformSettings | No | Platform-specific options as JSON (see below) |
| webhookUrl | No | HTTPS URL for publish/fail status callbacks |

#### Platform Settings

Pass platform-specific options via the `platformSettings` field:

```json
{
  "tiktok": { "privacyLevel": "PUBLIC_TO_EVERYONE", "disableComment": false },
  "youtube": { "privacyStatus": "public", "videoType": "shorts" },
  "instagram": { "postType": "reels" },
  "facebook": { "postType": "reels" },
  "snapchat": { "postType": "spotlight" },
  "pinterest": { "boardId": "123456789" }
}
```

---

## Webhooks

When you include a `webhookUrl` in your scheduled post, SwapFlow will send an HTTP POST to that URL when the post publishes or fails.

**Webhook payload:**

```json
{
  "postId": "uuid",
  "status": "published",
  "platform": "twitter",
  "url": "https://twitter.com/user/status/123",
  "error": null,
  "publishedAt": "2026-04-01T15:32:00Z"
}
```

**Verifying webhook signatures:**

Each webhook includes an `X-SwapFlow-Signature` header with an HMAC-SHA256 signature. Set `WEBHOOK_SIGNING_SECRET` in your environment and use it to verify:

```javascript
const crypto = require('crypto');
const signature = req.headers['x-swapflow-signature'];
const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.WEBHOOK_SIGNING_SECRET)
  .update(JSON.stringify(req.body))
  .digest('hex');
const isValid = signature === expected;
```

---

## Supported Platforms

| Platform | Platform Value |
|----------|---------------|
| Twitter / X | `twitter` |
| TikTok | `tiktok` |
| Instagram | `instagram-standalone` |
| Facebook | `facebook` |
| YouTube | `youtube` |
| Threads | `threads` |
| LinkedIn | `linkedin` |
| Pinterest | `pinterest` |
| Bluesky | `bluesky` |
| Telegram | `telegram` |
| Snapchat | `snapchat` |

---

## Rate Limits

API rate limits depend on your plan tier. Contact support for enterprise limits.

---

## Getting Started

1. Sign up at [swapflow.top](https://www.swapflow.top/sign-up)
2. Connect your social media accounts in the dashboard
3. Generate an API key at [Settings → API](https://www.swapflow.top/dashboard/settings/swapflow-api)
4. Start publishing!

For questions or support, visit [swapflow.top](https://www.swapflow.top).