> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Social Media

> Connect Instagram, TikTok, Pinterest, Reddit, X and LinkedIn, then compose, schedule and publish posts for your apps and track how they perform.

**Social Media** lets you post about your apps on the networks your users use, from one place. Connect your accounts, write a post once, send it to several accounts, publish now or schedule it, and see likes, views and clicks once it's live.

> [!NOTE]
>
> Connecting accounts, publishing, scheduling and uploading media require the **Startup** plan or higher. In the dashboard it lives under **Growth → Social Media**.

***

## How it works

```
Connect accounts  →  upload media  →  compose post  →  publish now or schedule
                                                              │
                                              post goes live on each account
                                                              │
                                                  analytics in the post detail
```

* **One post, many accounts.** A post can go to several connected accounts at once. Each account gets its own status, so one failure doesn't block the rest.
* **Media library.** Upload images and videos once, organize them in folders, and reuse them across posts.
* **Calendar.** Scheduled and published posts show on a calendar. Change or cancel anything that hasn't gone out yet.
* **Automations.** Turn your App Store screenshots into TikTok slideshows or Pinterest pins on a schedule, with drafts you can review before they go out.

***

## Supported platforms

| Platform | What you can post | Needs media |
| - | - | - |
| **Instagram** | Feed posts, reels and stories | Yes |
| **TikTok** | Videos and photo slideshows | Yes |
| **Pinterest** | Image and video pins | Yes. See [Pinterest](https://docs.appeeky.com/docs/growth-channels-pinterest.md) |
| **Reddit** | Text, link and image posts to a subreddit | No |
| **X** | Text posts with optional images or video | No |
| **LinkedIn** | Text posts with optional images or video | No |

`GET /v1/connect/social/platforms` lists every platform and whether it can be connected right now.

***

## Connect an account

In the dashboard, open **Growth → Social Media → Accounts** (or **Settings → Social media**) and pick a platform. You sign in on the platform's own page and are sent back to Appeeky.

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/connect/social/platforms` | List supported platforms |
| GET | `/v1/connect/social/:platform/oauth/start` | Start connecting. Returns `authorizeUrl` to open in a browser (`?return_to=` optional) |
| GET | `/v1/connect/social/accounts` | List connected accounts |
| DELETE | `/v1/connect/social/accounts/:id` | Disconnect an account |
| GET | `/v1/connect/social/accounts/:id/pinterest/boards` | List Pinterest boards |
| POST | `/v1/connect/social/accounts/:id/pinterest/boards` | Create a Pinterest board (`name`, optional `description`) |

`:platform` is one of `instagram`, `tiktok`, `pinterest`, `reddit`, `twitter` (X) or `linkedin`.

If a platform connection expires, posts to that account fail with `ACCOUNT_NEEDS_RECONNECT`. Reconnect it from **Accounts**.

> [!NOTE]
>
> In a [team workspace](https://docs.appeeky.com/docs/workspaces.md), connecting and disconnecting accounts needs the **admin** role. Editors can post with accounts that are already connected.

***

## Compose and publish

| Method | Endpoint | Description |
| - | - | - |
| POST | `/v1/social/posts` | Create a post and publish it now, or schedule it |
| GET | `/v1/social/posts` | List posts |
| GET | `/v1/social/posts/:id` | One post with each account's status and its media |
| PATCH | `/v1/social/posts/:id` | Edit a post, save it as a draft or schedule it |
| PATCH | `/v1/social/posts/:id/media` | Replace a post's media |
| POST | `/v1/social/posts/:id/publish` | Publish a draft, scheduled or failed post now |
| DELETE | `/v1/social/posts/:id` | Cancel a post that hasn't gone out |

### Create a post

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/social/posts \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Build tiny routines without the overwhelm. New in Dibble 2.0.",
    "account_ids": ["c1d2e3f4-0000-4000-8000-000000000001", "c1d2e3f4-0000-4000-8000-000000000002"],
    "media_ids": ["a9b8c7d6-0000-4000-8000-000000000003"],
    "scheduled_for": "2026-11-10T09:00:00.000Z",
    "timezone": "Europe/Istanbul"
  }'
```

| Field | Required | Description |
| - | - | - |
| `content` | Yes | Post text |
| `account_ids` | Yes | Connected account ids from `/v1/connect/social/accounts` |
| `media_ids` | No | Media library ids. Required for Instagram, TikTok and Pinterest |
| `media_urls` | No | Public image or video URLs, instead of library media |
| `scheduled_for` | No | Future ISO time. Omit to publish right away |
| `timezone` | No | Your timezone for the calendar. Default `UTC` |
| `extra` | No | Platform options, see below |

Response (`201`) holds the post `id` and its `status`.

### Platform options

Set these in `extra`. They only apply to the matching platform.

| Platform | Field | Description |
| - | - | - |
| Reddit | `subreddit` | **Required.** Subreddit name, with or without `r/` |
| Reddit | `title` | Post title. Default: first line of `content` (max 300 characters) |
| Reddit | `link` | Makes it a link post |
| Reddit | `flairId` | Flair for subreddits that require one |
| Pinterest | `boardId`, `link`, `title`, `coverImageUrl` | See [Pinterest](https://docs.appeeky.com/docs/growth-channels-pinterest.md#create-a-pin) |
| Instagram | `placement` | `"story"` to post a story instead of a feed post |
| TikTok | `privacyLevel` | Default `PUBLIC_TO_EVERYONE` |
| TikTok | `allowComment`, `allowDuet`, `allowStitch` | Default `true` |

TikTok posts can't mix images and video. Several images become a photo slideshow.

### Edit, reschedule or save as draft

`PATCH /v1/social/posts/:id` takes the same fields as create, plus `intent`:

* `"draft"` (default) saves the post without publishing.
* `"schedule"` schedules it for `scheduled_for`.

You can edit posts that are `draft`, `scheduled`, `pending`, `failed` or `partial_failure`.

### Post status

| Status | Meaning |
| - | - |
| `draft` | Saved, not scheduled |
| `scheduled` | Waiting for its time |
| `pending` | Queued to publish |
| `publishing` | Being sent to the platforms |
| `published` | Live on every account |
| `partial_failure` | Live on some accounts, failed on others |
| `failed` | Failed on every account |
| `cancelled` | Cancelled before it went out |

`POST /v1/social/posts/:id/publish` returns `202` while publishing continues in the background. Poll `GET /v1/social/posts/:id` for the result. Retrying a `failed` or `partial_failure` post only resends to the accounts that didn't publish.

### List posts

`GET /v1/social/posts` supports:

| Param | Description |
| - | - |
| `status` | Filter by status |
| `from`, `to` | ISO range for calendar views. Pass both to get posts in the range (up to 500), without pagination |
| `page`, `limit` | Pagination. `limit` default 20, max 500 |

***

## Media library

Upload images and videos once and reuse them. Group them in folders, and nest folders inside folders.

| Method | Endpoint | Description |
| - | - | - |
| POST | `/v1/social/media/upload` | Upload one file (multipart field `file`, optional `folderId`) |
| GET | `/v1/social/media` | List media (`?type=image\|video`, `?folderId=`, `page`, `limit` up to 100) |
| PATCH | `/v1/social/media/:id` | Rename (`name`) or move (`folderId`) |
| DELETE | `/v1/social/media/:id` | Delete |
| GET | `/v1/social/folders` | Folders in a parent (`?parentId=`), or all with `?all=1` |
| POST | `/v1/social/folders` | Create a folder (`name`, optional `parentId`) |
| PATCH | `/v1/social/folders/:id` | Rename or move a folder |
| DELETE | `/v1/social/folders/:id` | Delete a folder |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/social/media/upload \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -F "file=@screenshot-1.png" \
  -F "folderId=f0e1d2c3-0000-4000-8000-000000000004"
```

* Images and videos up to **100 MB** each.
* Folder names are 1–80 characters. Use `root` (or omit the id) for the top level.
* Deleting a folder keeps its contents: files and subfolders move up one level.
* Media attached to a draft or scheduled post can't be deleted. Remove it from the post first.

***

## Analytics

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/social/posts/:id/analytics` | Metrics for each account the post went live on |

Each item has `platform`, `platformPostId`, `analytics`, `capturedAt` and `error`. `analytics` holds `likes`, `comments`, `shares`, `reposts`, `impressions`, `clicks`, `views`, `reach` and `saves`. Metrics a platform doesn't report are `0`.

* Metrics refresh automatically for posts published in the last 30 days.
* Opening a post refreshes metrics that are more than an hour old.
* When a refresh fails, you get the last known values and `error` says why.

In the dashboard, open any published post from **Calendar** or **Posts** to see its numbers.

***

## Automations

Automations draft posts from your tracked app's App Store screenshots on a schedule:

* **TikTok slideshows**: screenshots turned into photo slideshows.
* **Pinterest pins**: one screenshot per pin, with AI-written title and description.

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/social/automations` | List automations |
| POST | `/v1/social/automations` | Create one (`platform`: `tiktok` or `pinterest`) |
| PATCH | `/v1/social/automations/:id` | Update the schedule, or pause and resume |
| DELETE | `/v1/social/automations/:id` | Archive |
| POST | `/v1/social/automations/:id/generate` | Draft a post now |

See [Pinterest](https://docs.appeeky.com/docs/growth-channels-pinterest.md) for a full automation example.

***

## Dashboard

**Growth → Social Media**

| Tab | Purpose |
| - | - |
| **Calendar** | Scheduled and published posts by day |
| **Posts** | Every post with status, errors and publish now |
| **Library** | Your media and folders |
| **Automations** | TikTok slideshow and Pinterest pin series |
| **Accounts** | Connect and reconnect platforms |

***

## Credits

Creating, editing, publishing, uploading and other changes use **0 API credits**. Reading endpoints (`GET`) use **2 API credits** per call with an API key and are free from the dashboard. See [Rate Limits & Credits](https://docs.appeeky.com/docs/rate-limits.md).

***

## MCP: scheduled Reddit posts

The `growth_scheduled_posts_*` tools schedule posts on the **Reddit Growth** content calendar. They're part of [Reddit Growth](https://docs.appeeky.com/docs/growth-channels-reddit.md), not the Social Media posts above, and work only for Reddit.

| Tool | Description |
| - | - |
| `growth_scheduled_posts_list` | List scheduled Reddit posts (`status`, or `from`/`to` for a calendar range) |
| `growth_scheduled_posts_create` | Schedule a Reddit post (`subreddit`, `title`, `text`, `post_type`, `link_url`, `media_urls`, `scheduled_for`), or send it now with `publish_now` |
| `growth_scheduled_posts_cancel` | Cancel a pending scheduled post |
| `growth_scheduled_posts_retry` | Re-queue a failed post, optionally at a new `scheduled_for` |

`post_type` is `text`, `link`, `image` or `video`. All four tools use 0 API credits. `publish_now` needs a connected Reddit account with auto-posting turned on.

***

## Related

* [Pinterest](https://docs.appeeky.com/docs/growth-channels-pinterest.md): boards, pin fields and screenshot automations
* [Reddit Growth](https://docs.appeeky.com/docs/growth-channels-reddit.md): subreddit scanning, replies and scheduled posts
* [Growth Channels overview](https://docs.appeeky.com/docs/growth-channels.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.