X
Publish posts, threads, replies, quotes and polls to X with the Zernio API, then read analytics, retweet, bookmark, follow and answer DMs from the same account.
Publish text, images, GIFs, videos, threads, replies, quotes and polls to X (platform value twitter) with POST /v1/posts and platform: "twitter". The same account also serves analytics, retweets, bookmarks, follows, DMs and comments.
Quick reference
| Property | Value |
|---|---|
| Character limit | 280 (free) / 25,000 (Premium) |
| Images per post | 4 (or 1 GIF) |
| Videos per post | 1 |
| File limits | Formats, sizes and duration (see Media & Video) |
| Threads | Yes (threadItems) |
| Scheduling | Yes |
| Inbox (DMs) | Yes |
| Inbox (Comments) | Yes |
| Analytics | Yes |
Before you start
X requires a card on file. X bills every API call at its published price and Zernio passes that cost through with no markup, so GET /v1/connect/twitter returns 402 with reason: "twitter_passthrough" until the team has a payment method. The rates and the monthly spend cap are on X API usage.
A free X account is limited to 280 characters, a Premium account to 25,000. URLs count as 23 characters whatever their length and emojis count as 2. X also rejects a post whose text matches one it already has.
When you cross-post from a platform with a higher limit (LinkedIn 3,000, Facebook 63,206), set customContent on the X entry with a version under 280 characters. Otherwise the X copy fails at publish time with "Tweet text is too long".
Connect
Call GET /v1/connect/twitter with profileId (Get OAuth connect URL) and send the user's browser to the returned authUrl. The connecting accounts guide covers the flow and scopes in general; Account health reports what a connected account can do with the scopes the user granted.
import Zernio from '@zernio/node';
const zernio = new Zernio();
const { data: connect } = await zernio.connect.getConnectUrl({
path: { platform: 'twitter' },
query: { profileId: '66a1f0c2a4b9d3e8f1a2b3c4', redirect_url: 'https://myapp.com/callback' }
});
// Send the user's browser to connect.authUrlResponse (200):
{
"authUrl": "https://twitter.com/i/oauth2/authorize?client_id=...",
"state": "..."
}After approval the user lands on redirect_url with connected=twitter&profileId=...&accountId=... appended. That accountId is the value every sample in this section uses.
OAuth scopes
| Scope | What it enables |
|---|---|
tweet.read | Read posts (post confirmation, replies, analytics) |
tweet.write | Publish and delete posts |
users.read | Account identity and profile data |
offline.access | Refresh token for long-lived access |
media.write | Upload images and videos |
dm.read, dm.write | X direct messages in the inbox |
tweet.moderate.write | Hide and unhide replies (comment moderation) |
like.write | Like posts on your behalf |
bookmark.write | Bookmark posts |
follows.write | Follow accounts on your behalf |
Publish
Call POST /v1/posts with content, a platforms entry carrying platform: "twitter" and the accountId from the connect flow, and publishNow: true. Replace publishNow with scheduledFor and timezone to schedule instead.
const { data: published } = await zernio.posts.createPost({
body: {
content: 'Shipping day. The API is live.',
platforms: [
{ platform: 'twitter', accountId: '66b2e19d8c3f5a7e9d0b1c2d' }
],
publishNow: true
}
});
console.log(published.post.platforms[0].platformPostUrl);Response (201):
{
"post": {
"_id": "65f1c0a9e2b5af0012ab34cd",
"status": "published",
"platforms": [
{
"platform": "twitter",
"status": "published",
"platformPostId": "1852634789012345678",
"platformPostUrl": "https://twitter.com/acmecorp/status/1852634789012345678"
}
]
}
}Media, threads, replies, quotes and polls all change this one request. Posts & Editing has each of them.
In this section
Posts & Editing
Create a post, attach media, publish a thread or an Article, and edit a published post
Replies & Quotes
Reply to a post, reply with a thread and quote a post
Media & Video
Media requirements and long video uploads on Premium accounts
Fields, Geo & Polls
Geo-restriction, paid partnership and AI labels, sensitive media, reply settings and polls
Analytics & Engagement
Post analytics, retweets, bookmarks and follows
Inbox
Direct messages and comments in the inbox
Limits & Errors
Every platformSpecificData field, what X's API does not expose and common errors
Common errors
| Error | Cause | Fix |
|---|---|---|
402 with reason: "twitter_passthrough" on GET /v1/connect/twitter | The team has no card on file, and X charges for every API call. | Send the user to the dashboard_url in the response, then call connect again. Rates are on X API usage. |
?error=oauth_denied&platform=twitter appended to your redirect_url | The user denied consent, or X rejected the callback. | Start the flow again. Treat an unknown error value as a generic failure; new values are added without notice. |
401 on a later call for that account | X revoked or expired the token. | Reconnect the account. Account health reports it before a post fails. |
The publish-time errors are in Limits & Errors, and Error handling covers the envelope.
Related
- Connecting accounts: the OAuth flow and the
402billing gates. - Create post: every field of the request.
- Media uploads: upload images and videos instead of hosting them.
- Twitter engagement: retweet, bookmark, follow, search and look up posts.
- X API usage: pass-through rates and the spend cap.
Overview
Publish to 16 platforms with one request shape, and check what each platform's API exposes for analytics, the inbox, webhooks and ads before you build on it.
Posts & Editing
Create a post on X, attach images, a GIF or a video, publish a thread with threadItems, publish an Article and edit a published post.