X (Twitter) Posting API Documentation | Kavenio Docs

Kavenio publishes to X, formerly Twitter, through connected user accounts. Use twitter as the platform value in API payloads; product UI may label the destination as X. The X adapter supports direct posts, replies, quote posts, polls, first comments, simple threads, and media upload from public Kavenio media URLs. For a product-level overview, see the X (Twitter) posting API page.

Quick Reference

Capability	Support
Platform key	`twitter`
OAuth scopes	`tweet.read`, `tweet.write`, `users.read`, `media.write`, `offline.access`
Text post	Supported
Reply	`replyToTweetId`
Quote post	`quoteTweetId`
Thread	`threadItems`
Poll	2-4 options, 5-10,080 minutes
First comment	`firstComment` creates a reply to the published post
Image upload	Up to 4 images
GIF upload	1 GIF
Video upload	1 video
Provider media IDs	`mediaIds` escape hatch
Native edit/unpublish	Not implemented

Create A Post

Create a normal X post with the shared posts API:

{
  "profileId": "customer_user_123",
  "content": "Shipping a product update today.",
  "platforms": [
    {
      "platform": "twitter",
      "accountId": "acc_123",
      "platformSpecificData": {
        "replySettings": "following"
      }
    }
  ],
  "publishNow": true
}

kavenio posts create \
  --profile-id customer_user_123 \
  --content "Shipping a product update today." \
  --publish-now \
  --platform twitter:acc_123 \
  --reply-settings following

replySettings can be following, mentionedUsers, subscribers, or verified. Replies cannot set replySettings.

Replies And Quotes

Reply to an existing post:

{
  "content": "Thanks for the question. Here is the detail.",
  "platforms": [
    {
      "platform": "twitter",
      "accountId": "acc_123",
      "platformSpecificData": {
        "replyToTweetId": "1800000000000000000"
      }
    }
  ],
  "publishNow": true
}

Quote an existing post:

{
  "content": "This is a useful thread.",
  "platforms": [
    {
      "platform": "twitter",
      "accountId": "acc_123",
      "platformSpecificData": {
        "quoteTweetId": "1800000000000000000"
      }
    }
  ],
  "publishNow": true
}

Quote posts cannot include media or polls.

Threads

Use threadItems for a reply chain created by one publish request. The root post uses the top-level content and optional top-level mediaItems; each thread item can include its own content and mediaItems.

{
  "content": "Launch notes, part 1.",
  "mediaItems": [
    {
      "type": "image",
      "url": "https://cdn.example.com/root.png",
      "mimeType": "image/png"
    }
  ],
  "platforms": [
    {
      "platform": "twitter",
      "accountId": "acc_123",
      "platformSpecificData": {
        "threadItems": [
          {
            "content": "Part 2 with a short demo.",
            "mediaItems": [
              {
                "type": "video",
                "url": "https://cdn.example.com/demo.mp4",
                "mimeType": "video/mp4"
              }
            ]
          },
          {
            "content": "Part 3 with the changelog link."
          }
        ]
      }
    }
  ],
  "publishNow": true
}

Threads cannot include polls. Each thread item must include text or media.

Media Upload

X media upload requires the media.write OAuth scope. Accounts connected before Kavenio added that scope must reconnect before uploading media. Text-only publishing continues to use tweet.write. If mediaItems are present and platformSpecificData.mediaIds is not supplied, Kavenio downloads each public media URL at publish time, uploads it to X, and attaches the returned provider media IDs to the post.

{
  "content": "New dashboard preview.",
  "mediaItems": [
    {
      "type": "image",
      "url": "https://cdn.example.com/dashboard.png",
      "mimeType": "image/png",
      "size": 532000
    }
  ],
  "platforms": [
    {
      "platform": "twitter",
      "accountId": "acc_123"
    }
  ],
  "publishNow": true
}

Supported media groups:

Media group	Limit
Images	Up to 4 images
GIF	Exactly 1 GIF
Video	Exactly 1 video

Images cannot be mixed with GIF or video. GIF and video cannot be mixed with each other. Supported media metadata:

Type	MIME types	Size limit
Image	JPEG, BMP, PNG, WebP, PJPEG, TIFF	5 MB
GIF	`image/gif`	15 MB
Video	`video/*`	512 MB

Media URLs must be public HTTP(S) URLs that return raw media bytes. Kavenio rejects private and localhost media URLs before provider upload.

Existing Provider Media

If you already uploaded media to X outside Kavenio, pass provider media IDs:

{
  "content": "Using an existing X media asset.",
  "platforms": [
    {
      "platform": "twitter",
      "accountId": "acc_123",
      "platformSpecificData": {
        "mediaIds": ["1800000000000000001"]
      }
    }
  ],
  "publishNow": true
}

When mediaIds are provided, Kavenio does not upload mediaItems for that target.

Polls

Polls live in platformSpecificData.poll:

{
  "content": "Which feature should we document next?",
  "platforms": [
    {
      "platform": "twitter",
      "accountId": "acc_123",
      "platformSpecificData": {
        "poll": {
          "options": ["Threads", "Analytics", "Webhooks"],
          "duration_minutes": 1440
        }
      }
    }
  ],
  "publishNow": true
}

Polls require 2-4 options. Each option can be up to 25 characters. Duration must be between 5 and 10,080 minutes. Polls cannot include media, quote posts, or threads.

Additional Fields

Field	Behavior
`firstComment`	Publishes the main post, then replies to it with the comment text.
`madeWithAi`	Sends the X `made_with_ai` flag.
`paidPartnership`	Sends the X `paid_partnership` flag.
`sensitiveMedia`	Accepted by the public contract for compatibility.
`longVideo`	Accepted by the public contract for compatibility.

Scheduling

Use Kavenio scheduling fields for scheduled X posts:

{
  "content": "Scheduled launch reminder.",
  "scheduledFor": "2027-06-16T10:00:00.000Z",
  "platforms": [
    {
      "platform": "twitter",
      "accountId": "acc_123"
    }
  ]
}

Scheduled media is uploaded when the scheduled publish job runs. Keep media URLs publicly fetchable until publish time.

Unsupported

Kavenio returns a validation or provider-unsupported error before calling X for these combinations:

more than 4 images
more than 1 GIF or 1 video
mixed image/GIF/video groups
media on quote posts
polls with media, quotes, or threads
reply posts with replySettings
document media
native provider edit or unpublish after publication

Common Errors

Error	Meaning
`X posts can include up to 4 images, 1 GIF, or 1 video.`	The media group is too large or mixes incompatible media types.
`X media upload supports image, GIF, and video media only.`	The target includes an unsupported media type such as `document`.
`X polls cannot include media.`	Remove `mediaItems` or `mediaIds` when using a poll.
`X quote posts cannot include media.`	Quote posts must be text-only in this adapter.
`X replies cannot set replySettings.`	Reply visibility is inherited from the reply context.
`Private and localhost media URLs are not allowed.`	Use a publicly reachable media URL.
`Connected X credential does not include media.write required for media uploads.`	Reconnect the X account to grant media upload access.

​Quick Reference

​Create A Post

​Replies And Quotes

​Threads

​Media Upload

​Existing Provider Media

​Polls

​Additional Fields

​Scheduling

​Unsupported

​Common Errors

​Official X API References