Post on Twitter/X With an API: A Practical Guide
Learn to post on Twitter/X with an API, from connecting an account to sending text, images, threads and polls. This guide uses a unified social posting contract; it is distinct from calling the native Twitter API directly. The examples show the exact request paths and fields, with {{API_BASE_URL}} as the configurable API origin. Use the field map and failure checks to prepare requests before integration.
Request contract at a glance
The workflow uses GET /v1/connect/twitter to begin account authorization, GET /v1/connect/integrations to retrieve connected account IDs, and POST /v1/posts to publish or schedule. Every call carries an x-access-key header. In a posting request, platforms selects the destination accounts; content supplies shared text, while thread supplies an ordered sequence of posts. Poll settings live inside the Twitter target’s platformSpecificData object.
What you need
Prepare an API access key and a Twitter/X account you can authorize. After connecting the account, retrieve its accountId before composing a posting payload. Keep the key on the server or in a protected development environment, outside shared repositories and client-delivered code. The example credentials and account IDs are placeholders.
Step 1: Set the access-key header
Send your key in x-access-key, as shown in the authentication example. Copy the header name exactly and replace YOUR_API_KEY with your own credential. If authentication is rejected, check that the key belongs to the intended project, is complete, and has not been exposed. Do not place the key in a shared screenshot or a URL query string.
Step 2: Authorize Twitter/X and retrieve accountId
Request an authorization URL with GET /v1/connect/twitter, open the returned URL in a browser, and complete account authorization. Then call GET /v1/connect/integrations. The id on the intended connected account becomes accountId in subsequent requests. The general connection route is GET /v1/connect/{platform}. If the list contains several accounts, match both the platform and account identity rather than taking the first ID. An empty list means there is no connected integration to select; complete authorization before posting.
Step 3: Post tweets with a text payload
The basic text example sends content, a platforms array containing platform: "twitter" and accountId, and publishNow: true to POST /v1/posts. Keep your text at the top level when every selected target should receive it. Inspect the result before assuming the post is live. If authentication succeeded but a target failed, check the connected account ID and that target’s returned error.
Attach images or video with mediaItems
Add mediaItems for attachments. Each illustrated item contains type and a public url. The contract described here supports up to four images or one video for a tweet; it accepts media URLs for the publishing service to upload. Check that each URL is accessible without your browser session and returns the intended file. To isolate a media failure, test the URL and type before combining multiple attachments. These API-contract limits do not establish current limits for every native Twitter/X API product.
Build an ordered thread
Use thread instead of the single-post content field for a sequence of content blocks. Each item is published as a reply to its predecessor, so array order determines reading order. Review the complete sequence before sending. If processing stops partway through, inspect which items already published before retrying; resending the whole sequence can duplicate earlier posts. Any rate-limit anecdote inside the example’s literal post text is sample content, not a service limit or a verified current platform policy.
Add a poll inside platformSpecificData
Place poll under platformSpecificData on the Twitter entry in platforms. Its options array supplies the choices, and durationMinutes supplies the duration. This contract describes up to four options and a maximum durationMinutes of 10080, equivalent to seven days. The example uses 1440 minutes. Keep these settings on the intended platform target rather than adding poll at the request’s top level. Check the count, duration and nesting before submission; the source contract does not specify a minimum duration here.
Schedule with scheduledFor and timezone
For the scheduled example, omit publishNow and send scheduledFor with timezone. The timestamp example uses a local datetime together with America/New_York. Check the date, local time and timezone together so daylight-saving changes do not shift your intended publication time. After submission, read the stored schedule/status rather than treating request construction as confirmation of publication. Scheduling and immediate publication are different modes; do not copy publishNow: true from the immediate example into this scheduled payload.
Cross-post through one platforms array
To publish shared content to several networks, add a destination entry for each account in platforms. The example targets Twitter, LinkedIn and Facebook with one image. Each accountId must belong to the matching connected account. This contract also describes per-platform scheduling through scheduledFor on individual entries, so destinations can use different publication times. Check each target’s text and media requirements; automatic adaptation does not make arbitrary content suitable for every destination. Inspect each platform result separately when one succeeds and another fails.
Diagnose failures without guessing error codes
The failure matrix maps common symptoms to concrete input checks. It adds diagnostic steps without inventing HTTP error codes that this tutorial does not define. Separate authentication, account connection, payload shape, media access and scheduling checks so you can change the failing input instead of retrying blindly. For complete options, continue to the Twitter platform reference and Create Post documentation. The examples remain unexecuted integration examples; exact backend matching and runtime validation belong to implementation.
| Field | Location | Required / optional in examples | Purpose |
|---|---|---|---|
| content | Top level | Required for single tweet / poll / media post | Text of the post |
| platforms | Top level | Required in examples | Array of platform targets |
| platforms[].platform | Inside platforms | Required | Platform name, e.g. "twitter" |
| platforms[].accountId | Inside platforms | Required | Identifies the connected account |
| mediaItems | Top level | Optional | Array of { type, url } items |
| thread | Top level | Optional, alternative to content | Ordered thread array of { content } blocks |
| platforms[].platformSpecificData.poll | Inside a platform target | Optional, poll only | Poll options and duration |
| platforms[].platformSpecificData.poll.options | Inside poll | Required for a poll | Up to 4 options in this contract |
| platforms[].platformSpecificData.poll.durationMinutes | Inside poll | Required for a poll | Duration in minutes; contract maximum 10080 (7 days) |
| publishNow | Top level | Used for immediate publishing | Set to true to publish now |
| scheduledFor | Top level | Used instead of publishNow for scheduling | Timestamp for scheduled publishing |
| timezone | Top level | Used with scheduledFor | Timezone for the scheduled timestamp |
Field names and example contract preserved; diagnostic checks are guidance, not observed API responses.
| Failure | Likely cause | Check / fix |
|---|---|---|
| Authentication rejected | Missing or incorrect x-access-key header | Re-copy the key; confirm header name is exactly x-access-key |
| Account not found | accountId does not match a connected account | Re-run GET /v1/connect/integrations and copy the correct id |
| Account not connected | Authorization step never completed | Open the URL from GET /v1/connect/twitter, authorize, re-list integrations |
| Unsupported media | Bad mediaItems[].type, unreachable url, or count over stated limit | Validate URL, use supported type, reduce count |
| Poll rejected | More than 4 options or durationMinutes over 10080 | Trim options to at most 4; set duration within stated maximum |
| Scheduling rejected | Malformed scheduledFor, past timestamp, or invalid timezone | Use a valid future timestamp and recognized timezone name |
| Thread partially posted | A middle thread item failed | Check which items posted before retrying |
| One platform fails in cross-post | Per-platform constraint or unconnected account | Inspect per-platform results; fix only the failing target |
Field names and example contract preserved; diagnostic checks are guidance, not observed API responses.
-H "x-access-key: YOUR_API_KEY"curl {{API_BASE_URL}}/v1/connect/twitter \
-H "x-access-key: YOUR_API_KEY"curl {{API_BASE_URL}}/v1/connect/integrations \
-H "x-access-key: YOUR_API_KEY"curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "twitter", "accountId": "your-account-id" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "twitter", "accountId": "your-account-id" }
],
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/screenshot.png" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"thread": [
{ "content": "A short example update." },
{ "content": "A short example update." },
{ "content": "A short example update." },
{ "content": "A short example update." },
{ "content": "A short example update." }
],
"platforms": [
{ "platform": "twitter", "accountId": "your-account-id" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{
"platform": "twitter",
"accountId": "your-account-id",
"platformSpecificData": {
"poll": {
"options": ["Monday", "Wednesday", "Friday", "Never"],
"durationMinutes": 1440
}
}
}
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "twitter", "accountId": "your-account-id" }
],
"scheduledFor": "2026-04-20T14:00:00",
"timezone": "America/New_York"
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "twitter", "accountId": "acc_tw_123" },
{ "platform": "linkedin", "accountId": "acc_li_456" },
{ "platform": "facebook", "accountId": "acc_fb_789" }
],
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/launch.png" }
],
"publishNow": true
}'