# Posts API

List the Instagram, TikTok and YouTube accounts you connected, post a finished video on them at a time or now, and change, cancel or try again a post.

Post your finished videos on your own Instagram, TikTok and YouTube accounts, at a time you choose or now, as the app's Posts does. Connect the accounts in the app, on [Posts](/app/agent/posts): the API lists them and posts on them, and never connects one.

## List your accounts

`GET /api/v1/posts/accounts`

The accounts you connected. Needs **Posts: Read**.

```json
{
  "object": "list",
  "data": [
    {
      "id": "pa_8c1f2e7a90b34d6e",
      "object": "social_account",
      "platform": "youtube",
      "name": "Acme",
      "handle": "acme",
      "picture": "https://yt3.ggpht.com/...",
      "state": "ok",
      "connected": "2026-11-20T09:12:40.512Z"
    }
  ],
  "can_connect": ["instagram", "tiktok", "youtube", "facebook", "linkedin", "pinterest", "x"],
  "connect": "https://10xvid.com/app/agent/posts"
}
```

| Field | What it is |
|---|---|
| `id` | The account's id. Send it in `accounts` to post on it. |
| `platform` | `instagram`, `tiktok`, `youtube`, `facebook` (a Page), `linkedin` (a profile), `pinterest` or `x`. |
| `name`, `handle`, `picture` | How it shows on its platform. |
| `state` | `ok`, or `reconnect`: the platform no longer accepts the connection. Connect it again in the app before posting on it. |
| `connected` | When it was connected. |

`can_connect` names the platforms you can connect now, and `connect` is where.

## Schedule a post

`POST /api/v1/posts`

One finished video on one or more of your accounts, at a time or now: one post for each account. Needs **Posts: Write**.

| Field | Needed | What it is |
|---|---|---|
| `video_id` | needed | The video to post: a finished video's `id`, or one of its files' `video_id` to choose the shape. With the video's `id`, its 9:16 file is posted when it has one. |
| `accounts` | needed | The ids of the accounts to post on, from [List your accounts](#list-your-accounts), up to 20. |
| `at` | needed | When it goes out: a time in ISO 8601 with its offset, such as `"2026-11-22T10:00:00+02:00"`, up to 180 days ahead (with no offset it is UTC); or `"now"`. |
| `text` | optional | The words: the caption on Instagram and TikTok, the description on YouTube. Instagram and TikTok take up to 2,200 characters, Instagram up to 30 hashtags and 20 @ mentions; YouTube up to 5,000 bytes, with no `<` or `>`; Facebook 5,000 characters, LinkedIn 3,000, a Pin's description 800, X 280 (a link counts 23). |
| `options` | for YouTube, TikTok and Pinterest | Each platform's choices under its name: `{"youtube": {...}, "tiktok": {...}, "pinterest": {...}}`. YouTube, TikTok and Pinterest each need some, below; what you leave out takes its default. |

### YouTube

| Option | Needed | What it is |
|---|---|---|
| `title` | needed | Up to 100 characters, with no `<` or `>`. |
| `kids` | needed | `true` when the video is made for kids, `false` when it is not. YouTube asks every uploader to say it. |
| `privacy` | optional | `"public"` (default), `"unlisted"` or `"private"`. |
| `kind` | optional | `"short"` or `"video"`. Default: a Short when the video is vertical or square and at most 3 minutes. |
| `synthetic` | optional | `true` when it shows realistic people, places or events that were made or changed. Default `false`. |
| `notify` | optional | `false` to post without telling the channel's subscribers. Default `true`. |

Posting on YouTube, you confirm that the video follows the [YouTube Terms of Service](https://www.youtube.com/t/terms), its Community Guidelines included, and does not break anyone's copyright or privacy.

### TikTok

| Option | Needed | What it is |
|---|---|---|
| `privacy` | needed | Who can see it: `"PUBLIC_TO_EVERYONE"`, `"MUTUAL_FOLLOW_FRIENDS"`, `"FOLLOWER_OF_CREATOR"` or `"SELF_ONLY"`. It has no default: TikTok asks that the person choose it. Which of these an account has depends on its settings on TikTok. |
| `consent` | needed | `true`, once the person has agreed to TikTok's [Music Usage Confirmation](https://www.tiktok.com/legal/page/global/music-usage-confirmation/en). Show them "By posting, you agree to TikTok's Music Usage Confirmation" first. |
| `comment` | optional | `true` to let people comment. Default `false`. |
| `duet` | optional | `true` to let people duet it. Default `false`. |
| `stitch` | optional | `true` to let people stitch it. Default `false`. |
| `aigc` | optional | `true` to label it as made with AI. Default `false`. |
| `promo` | optional | `true` when it promotes a brand, a product or a service. Then say which with `own`, `paid` or both. |
| `own` | optional | With `promo`: it promotes your own business. |
| `paid` | optional | With `promo`: a paid partnership (branded content). Its `privacy` cannot be `"SELF_ONLY"`, and the person agrees to TikTok's [Branded Content Policy](https://www.tiktok.com/legal/page/global/bc-policy/en) too. |
| `mode` | optional | `"inbox"` sends the video to the account's TikTok inbox as a draft, to finish and post in TikTok: nothing else is needed then. Default `"post"`. |

### Instagram

| Option | Needed | What it is |
|---|---|---|
| `kind` | optional | `"reel"` (default) or `"story"`. A story's video is at most 60 seconds. |
| `feed` | optional | `false` shows a reel in the Reels tab only. Default `true`: in the feed too. |

### Facebook

| Option | Needed | What it is |
|---|---|---|
| `kind` | optional | `"reel"` or `"video"`. Default: a Reel when the video is vertical and 3 to 90 seconds. |
| `title` | optional | A video's title (a Reel has none), up to 255 characters. |

### LinkedIn

| Option | Needed | What it is |
|---|---|---|
| `visibility` | optional | `"PUBLIC"` (default) or `"CONNECTIONS"`. |

### Pinterest

| Option | Needed | What it is |
|---|---|---|
| `board` | needed | The board the Pin goes on: its name as it shows on Pinterest, or its id. |
| `title` | optional | Up to 100 characters. |
| `link` | optional | Where the Pin leads, starting with `https://`. |

A video Pin runs 4 seconds to 5 minutes.

### X

No options. The text is at most 280 characters, a link counting 23.

cURL:

```bash
curl https://10xvid.com/api/v1/posts \
  -H "Authorization: Bearer $TENX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_id": "MV40XXRN514AA9",
    "accounts": ["pa_8c1f2e7a90b34d6e", "pa_41d09b6e2c7a5f13"],
    "at": "2026-11-22T10:00:00+02:00",
    "text": "Write while you talk.",
    "options": {
      "youtube": {"title": "Write while you talk", "kids": false},
      "tiktok": {"privacy": "PUBLIC_TO_EVERYONE", "consent": true}
    }
  }'
```

JavaScript:

```js
const res = await fetch('https://10xvid.com/api/v1/posts', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.TENX_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    video_id: 'MV40XXRN514AA9',
    accounts: ['pa_8c1f2e7a90b34d6e', 'pa_41d09b6e2c7a5f13'],
    at: '2026-11-22T10:00:00+02:00',
    text: 'Write while you talk.',
    options: { youtube: { title: 'Write while you talk', kids: false }, tiktok: { privacy: 'PUBLIC_TO_EVERYONE', consent: true } },
  }),
});
const { data: posts } = await res.json();
```

Python:

```python
res = requests.post(
    "https://10xvid.com/api/v1/posts",
    headers={"Authorization": f"Bearer {os.environ['TENX_API_KEY']}"},
    json={
        "video_id": "MV40XXRN514AA9",
        "accounts": ["pa_8c1f2e7a90b34d6e", "pa_41d09b6e2c7a5f13"],
        "at": "2026-11-22T10:00:00+02:00",
        "text": "Write while you talk.",
        "options": {"youtube": {"title": "Write while you talk", "kids": False}, "tiktok": {"privacy": "PUBLIC_TO_EVERYONE", "consent": True}},
    },
)
posts = res.json()["data"]
```

The answer is `201` with the posts, one for each account, each `"status": "scheduled"`. A post due now is sent at once. Nothing is kept when one of them is refused: `400` says what is missing or not right (a YouTube title, who can see a TikTok post, a time that has passed), `404` that the video is not finished or was removed, and `409` that an account must be connected again first.

## The post object

```json
{
  "id": "po_5e0b7d2c41a98f36",
  "object": "post",
  "batch": "pb_c93a01f4e8d27b65",
  "account": "pa_8c1f2e7a90b34d6e",
  "platform": "youtube",
  "status": "posted",
  "at": "2026-11-22T08:00:00.000Z",
  "video_id": "MV40XXRN514AA9-V1",
  "video_title": "Write while you talk",
  "text": "Write while you talk.",
  "options": { "kind": "short", "title": "Write while you talk", "privacy": "public", "kids": false, "synthetic": false, "notify": true },
  "link": "https://www.youtube.com/shorts/...",
  "error": null,
  "posted_at": "2026-11-22T08:01:12.381Z",
  "locked": true
}
```

| Field | What it is |
|---|---|
| `id` | The post's id. |
| `object` | Always `post`. |
| `batch` | The posts made by one call share it. |
| `account`, `platform` | Where it goes. |
| `status` | `scheduled`, `publishing` (the platform is taking it), `posted` or `failed`. |
| `at` | When it goes out. |
| `video_id` | The file posted, or `null` for a video uploaded in the app. |
| `video_title` | The video's title, when it has one. |
| `text`, `options` | As kept, checked against the platform's rules, each choice with its default. |
| `link` | The post on its platform, once `posted`. |
| `error` | A sentence saying why, when it `failed`. |
| `posted_at` | When it went out. |
| `locked` | `true` once part of it has reached the platform, or while it is being sent: it can no longer be changed or cancelled. |

## Get a post

`GET /api/v1/posts/{id}`

One post. Needs **Posts: Read**.

## List posts

`GET /api/v1/posts`

Your posts, scheduled, sent and failed, the latest time first. Needs **Posts: Read**.

| Query | What it is |
|---|---|
| `from` | Only posts due at or after this moment, as an ISO date or milliseconds. |
| `to` | Only posts due at or before this moment, as an ISO date or milliseconds. |

## Change a post

`PATCH /api/v1/posts/{id}`

Changes a post before it goes out: only what you send changes. Needs **Posts: Write**.

| Field | Needed | What it is |
|---|---|---|
| `at` | optional | A new time, as above, or `"now"`. |
| `text` | optional | New words. |
| `options` | optional | Its platform's choices, alone (`{"privacy": "unlisted"}`) or under the platform's name as above. Only the ones you send change. |
| `video_id` | optional | Another finished video. |

The answer is the post. A post that is `locked` or `posted` answers `409`. A post that `failed` and is not locked is scheduled again with the change: at the time you send, or else at its own time, at once when that has passed.

## Cancel a post

`DELETE /api/v1/posts/{id}`

A post that has not gone out is cancelled, and never goes out. A post that went out or failed is only taken off the list: what went out stays on its platform. Needs **Posts: Write**.

```json
{ "id": "po_5e0b7d2c41a98f36", "object": "post", "deleted": true, "cancelled": true }
```

`cancelled` is `true` when it had not gone out. A post on its way (`locked`, and `scheduled` or `publishing`) answers `409`.

## Try a post again

`POST /api/v1/posts/{id}/retry`

A post that `failed`, sent again now; what had reached the platform is kept, so a YouTube upload goes on where it stopped. Its account must be connected (`state` is `ok`). The answer is the post, `"status": "scheduled"`. Needs **Posts: Write**.
