# Posts & Threads

Text, image, video and carousel posts, thread sequences, topic tags and every platformSpecificData field.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

A plain post becomes a text post. Add `mediaItems` for an image, a video or a carousel.

Add `threadItems` in `platformSpecificData` for a chain of connected posts.

## Text post

Threads accepts text-only posts of up to 500 characters, with no media required.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: published } = await zernio.posts.createPost({
  body: {
    content: 'Hot take: the best API is the one with the best docs.',
    platforms: [
      { platform: 'threads', accountId: '66b2e19d8c3f5a7e9d0b1c2d' }
    ],
    publishNow: true
  }
});

console.log(published.post.platforms[0].platformPostUrl);
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

published = client.posts.create_post(
    content="Hot take: the best API is the one with the best docs.",
    platforms=[
        {"platform": "threads", "accountId": "66b2e19d8c3f5a7e9d0b1c2d"}
    ],
    publish_now=True
)

print(published["post"]["platforms"][0]["platformPostUrl"])
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/posts \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hot take: the best API is the one with the best docs.",
    "platforms": [
      {"platform": "threads", "accountId": "66b2e19d8c3f5a7e9d0b1c2d"}
    ],
    "publishNow": true
  }'
```
</Tab>
</Tabs>

Response (`201`):

```json
{
  "post": {
    "_id": "65f1c0a9e2b5af0012ab34cd",
    "status": "published",
    "platforms": [
      {
        "platform": "threads",
        "status": "published",
        "platformPostUrl": "https://www.threads.net/@yourhandle/post/..."
      }
    ]
  }
}
```

Every sample below changes only the `mediaItems` or the `platforms` entry of this request.

## Image post

A single image with an optional caption:

```json
"mediaItems": [
  { "type": "image", "url": "https://cdn.example.com/office.jpg" }
]
```

## Video post

A single video with an optional caption, at most 1 GB and 5 minutes:

```json
"mediaItems": [
  { "type": "video", "url": "https://cdn.example.com/launch.mp4" }
]
```

## Carousel

Up to 20 images in one swipeable post (10 items when a video is included):

```json
"mediaItems": [
  { "type": "image", "url": "https://cdn.example.com/feature1.jpg" },
  { "type": "image", "url": "https://cdn.example.com/feature2.jpg" },
  { "type": "image", "url": "https://cdn.example.com/feature3.jpg" }
]
```

## Thread sequence

`threadItems` publishes a chain of connected posts. The first item is the root post, and each later item is a reply to the one before it, in order.

Every item carries text, media, or both.

<Callout type="warn">
With `threadItems` set, the top-level `content` is stored for display and search only and is not published. The first post must be `threadItems[0]`.
</Callout>

```json
{
  "platform": "threads",
  "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
  "platformSpecificData": {
    "threadItems": [
      {
        "content": "Here is a thread about API design",
        "mediaItems": [{ "type": "image", "url": "https://cdn.example.com/cover.jpg" }]
      },
      { "content": "1/ First, REST principles." },
      {
        "content": "2/ Authentication. Here is what we recommend.",
        "mediaItems": [{ "type": "image", "url": "https://cdn.example.com/auth-diagram.jpg" }]
      },
      { "content": "3/ Finally, always version your API. /end" }
    ]
  }
}
```

## Topic tags

`topic_tag` sets the post's topic tag for discoverability. It is 1 to 50 characters and cannot contain periods (`.`) or ampersands (`&`).

It overrides the tag Threads would extract from hashtags in the content.

```json
{
  "platform": "threads",
  "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
  "platformSpecificData": { "topic_tag": "APIDesign" }
}
```

## Platform fields

All fields go in `platformSpecificData` on the Threads entry.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `topic_tag` | string | (from hashtags) | Topic tag for categorisation and discoverability. 1 to 50 characters, no periods (`.`) or ampersands (`&`). Overrides auto-extraction from content hashtags. |
| `firstComment` | string | | Posted right after publishing as a reply to the published post (with `threadItems`, a reply to the root post). Up to 500 characters. It is itself a Threads post, so it counts toward the 250 posts per 24 hours. |
| `threadItems` | Array\<\{content?, mediaItems?\}\> | | The complete sequence of posts in a thread. The first item becomes the root post and must be `threadItems[0]`. When set, the top-level `content` is for display and search only and is not published. `content` may be omitted when `mediaItems` is set. |