# Posting to social accounts


# Posting to social accounts

Second Studio publishes and schedules through accounts **you** connect. Supported platforms include
TikTok, Instagram, YouTube, LinkedIn, Facebook, X, Threads, Pinterest and Bluesky.

## Connect an account

```bash
curl -X POST https://frugal-anteater-681.convex.site/v1/social/connect -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"platform":"tiktok","redirectUrl":"https://your-site.com/connected"}'
# → { "authUrl": "https://…" }
```

Open `authUrl` in a browser and approve on the platform's own consent screen. You land back on
`redirectUrl` when it is done. Facebook Pages and LinkedIn organisations ask you to pick which page.
Then `GET /v1/social/accounts` lists it:

```json
{ "data": [ { "id": "6a62538d…", "platform": "tiktok", "username": "yourbrand", "displayName": "Your Brand", "status": null } ] }
```

Your accounts are isolated in their own profile. Nobody else's agent can see or post to them, and you
cannot target an account that is not yours.

## The approval model

Posting is public and hard to undo, so it is split across the two keys:

| | Agent key | Admin key |
|---|---|---|
| Draft a post | ✓ | ✓ |
| Approve or reject a post | — | ✓ |

1. An agent drafts: `POST /v1/posts` → status `pending_approval`.
2. A person reviews it (`GET /v1/posts`) and approves with the admin key:
   `POST /v1/posts/{id}/approve` → `scheduled` or `published`. Or rejects it, and its credit is refunded.

An account can opt into **auto-publish** (email peter@hellofaro.io), which skips approval. Even then, every post
must name its accounts explicitly.

## Rules enforced on every post

- **Name the account.** Each target needs the account's exact `id` and `platform` from
  `GET /v1/social/accounts`. Brands often own two accounts on one platform (consumer and business), and
  display names can be misleading. Unknown or mismatched accounts are refused, with the list of your
  real accounts in the error.
- **No accidental "now".** A `scheduledFor` time in the past is refused rather than published
  immediately. To post now, say `"publishNow": true`.
- **Explicit time zones.** `scheduledFor` must carry an offset (`2026-10-12T18:00:00-04:00`) or come with
  a `timezone` (`America/New_York`).
- Instagram videos post as Reels and YouTube videos as Shorts.

## Status

`pending_approval` → `approved` → `scheduled` → `published`, or `failed` (with `error`; the credit is
refunded) or `rejected`. Statuses update as the platform reports back.

## Before you post

- Captions are burned into the video for muted viewing; the post `caption` is the text under it.
- Make sure you have the rights to everything in the video and the claims in the caption.
- Never make earnings or income promises.