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

# Threads Publishing API Documentation | Kavenio Docs

> Publish Threads text posts, images, videos, carousels, topic tags, and reply chains with Kavenio. Review payloads, media rules, scheduling, and errors.

Kavenio publishes to Threads through connected Threads accounts. Threads uses
Meta's container flow: Kavenio creates a text, image, video, or carousel
container, then publishes that container.

Use `threads` as the platform value in post targets.

## Quick Reference

| Capability            | Support                                                                |
| --------------------- | ---------------------------------------------------------------------- |
| Platform key          | `threads`                                                              |
| Text post             | Supported                                                              |
| Image post            | Supported                                                              |
| Video post            | Supported                                                              |
| Carousel              | Up to 20 image/video items                                             |
| Thread sequence       | `threadItems`                                                          |
| Topic tag             | `topicTag`                                                             |
| Polls                 | Not supported                                                          |
| Post analytics        | `GET /v1/analytics` for views, likes, replies, reposts, quotes, shares |
| Native edit/unpublish | Not implemented                                                        |

## Create A Text Post

```json theme={null}
{
  "profileId": "customer_user_123",
  "content": "Shipping notes from today's release.",
  "platforms": [
    {
      "platform": "threads",
      "accountId": "acc_123"
    }
  ],
  "publishNow": true
}
```

```bash theme={null}
kavenio posts create \
  --profile-id customer_user_123 \
  --content "Shipping notes from today's release." \
  --publish-now \
  --platform threads:acc_123
```

Threads posts require text or media. If both are empty, Kavenio rejects the
target before calling Meta.

## Media Posts

Add `mediaItems` for image, video, or carousel posts. Kavenio passes public media
URLs to Threads containers; it does not upload binary media to Kavenio-specific
provider storage for this adapter.

```json theme={null}
{
  "content": "Product screenshots from the new release.",
  "mediaItems": [
    {
      "type": "image",
      "url": "https://cdn.example.com/screen-1.jpg",
      "mimeType": "image/jpeg",
      "altText": "Dashboard screenshot"
    },
    {
      "type": "image",
      "url": "https://cdn.example.com/screen-2.jpg",
      "mimeType": "image/jpeg",
      "altText": "Settings screenshot"
    }
  ],
  "platforms": [
    {
      "platform": "threads",
      "accountId": "acc_123",
      "platformSpecificData": {
        "topicTag": "Launch_2026"
      }
    }
  ],
  "publishNow": true
}
```

Media rules:

| Media    | Rule                                                     |
| -------- | -------------------------------------------------------- |
| Image    | `type: "image"` and optional `image/*` MIME metadata     |
| Video    | `type: "video"` and optional `video/*` MIME metadata     |
| Carousel | 2-20 image/video media items                             |
| Alt text | Sent for image and video media when `altText` is present |

Kavenio rejects document media, more than 20 media items, and MIME metadata that
does not match the media type.

## Thread Sequences

Use `platformSpecificData.threadItems` to create a Threads reply chain. Each item
is published in order; every item after the first is sent as a reply to the
previous published item.

```json theme={null}
{
  "content": "Internal summary for search and display only.",
  "platforms": [
    {
      "platform": "threads",
      "accountId": "acc_123",
      "platformSpecificData": {
        "topicTag": "APIDesign",
        "threadItems": [
          {
            "content": "A short thread on API design."
          },
          {
            "content": "Start with stable resource names and predictable errors."
          },
          {
            "content": "Then document retries, idempotency, and webhook behavior.",
            "mediaItems": [
              {
                "type": "image",
                "url": "https://cdn.example.com/webhook-flow.png",
                "mimeType": "image/png",
                "altText": "Webhook delivery flow"
              }
            ]
          }
        ]
      }
    }
  ],
  "publishNow": true
}
```

When `threadItems` is present, Kavenio publishes the items in
`threadItems`. The top-level `content` is useful for local display, search, and
cross-platform previews, but it is not sent as the root Threads post.

Do not combine top-level `mediaItems` with `threadItems`. Put media on the
specific thread item that should publish it.

If a later item fails after earlier items were published, Kavenio returns a
target failure with the already-created Threads IDs in provider failure details.
Do not blindly retry the same request as a new thread; inspect the target error
and reconcile first.

## Topic Tags

Use `topicTag` to send a Threads topic tag:

```json theme={null}
{
  "content": "Building cleaner automation APIs.",
  "platforms": [
    {
      "platform": "threads",
      "accountId": "acc_123",
      "platformSpecificData": {
        "topicTag": "APIDesign"
      }
    }
  ],
  "publishNow": true
}
```

`topicTag` can contain letters, numbers, and underscores only. Kavenio rejects
periods, ampersands, spaces, and other punctuation before provider calls.

## Scheduling

Threads uses Kavenio scheduling:

```json theme={null}
{
  "content": "Scheduled Threads update.",
  "scheduledFor": "2027-06-16T10:00:00.000Z",
  "platforms": [
    {
      "platform": "threads",
      "accountId": "acc_123"
    }
  ]
}
```

Scheduled media URLs must remain public and fetchable until the scheduled job
runs.

## Unsupported

Kavenio rejects these Threads combinations before provider calls:

* empty post with no text and no media
* document media
* more than 20 media items
* MIME metadata that does not match `image/*` or `video/*`
* top-level `mediaItems` when `threadItems` is present
* empty thread items
* invalid `topicTag` characters
* polls
* quote posts and replies to an existing external Threads post
* reply controls and reply approvals
* link, GIF, text, poll, and location attachments
* spoiler text entities
* ghost posts
* native provider edit or unpublish after publication

These are explicit Kavenio product boundaries, not claims that the Threads API
itself lacks the capabilities.

## Common Errors

| Error                                                                            | Meaning                                                     |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `Threads publishing requires content or media.`                                  | The post has no text and no media.                          |
| `Threads thread items require content or media.`                                 | A `threadItems[]` entry is empty.                           |
| `Threads thread publishing does not support top-level mediaItems in this slice.` | Move media into the relevant `threadItems[]` entry.         |
| `Threads carousel publishing supports at most 20 media items.`                   | Split the media into separate posts or reduce the carousel. |
| `Threads media publishing supports image and video only.`                        | Remove unsupported media types such as documents.           |
| `Threads topic tags can contain only letters, numbers, and underscores.`         | Use a plain topic tag such as `APIDesign`.                  |
| `Private and localhost media URLs are not allowed.`                              | Use a publicly reachable media URL.                         |