Threads Publishing API Documentation | Kavenio Docs

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

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

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.

{
  "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.

{
  "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:

{
  "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:

{
  "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.

​Quick Reference

​Create A Text Post

​Media Posts

​Thread Sequences

​Topic Tags

​Scheduling

​Unsupported

​Common Errors