> ## 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. # X (Twitter) Posting API Documentation | Kavenio Docs > Connect X accounts and publish posts, threads, replies, polls, images, GIFs, and videos. Review OAuth scopes, payloads, media limits, and errors. 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](https://kavenio.com/platforms/x) 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: ```json theme={null} { "profileId": "customer_user_123", "content": "Shipping a product update today.", "platforms": [ { "platform": "twitter", "accountId": "acc_123", "platformSpecificData": { "replySettings": "following" } } ], "publishNow": true } ``` ```bash theme={null} 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: ```json theme={null} { "content": "Thanks for the question. Here is the detail.", "platforms": [ { "platform": "twitter", "accountId": "acc_123", "platformSpecificData": { "replyToTweetId": "1800000000000000000" } } ], "publishNow": true } ``` Quote an existing post: ```json theme={null} { "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`. ```json theme={null} { "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. ```json theme={null} { "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: ```json theme={null} { "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`: ```json theme={null} { "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: ```json theme={null} { "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. | ## Official X API References * [Manage Posts](https://docs.x.com/x-api/posts/manage-tweets/introduction) * [OAuth 2.0 scopes and refresh tokens](https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code) * [Media upload best practices](https://docs.x.com/x-api/media/quickstart/best-practices)