Skip to content

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 map for POST /v1/posts
FieldLocationRequired / optional in examplesPurpose
contentTop levelRequired for single tweet / poll / media postText of the post
platformsTop levelRequired in examplesArray of platform targets
platforms[].platformInside platformsRequiredPlatform name, e.g. "twitter"
platforms[].accountIdInside platformsRequiredIdentifies the connected account
mediaItemsTop levelOptionalArray of { type, url } items
threadTop levelOptional, alternative to contentOrdered thread array of { content } blocks
platforms[].platformSpecificData.pollInside a platform targetOptional, poll onlyPoll options and duration
platforms[].platformSpecificData.poll.optionsInside pollRequired for a pollUp to 4 options in this contract
platforms[].platformSpecificData.poll.durationMinutesInside pollRequired for a pollDuration in minutes; contract maximum 10080 (7 days)
publishNowTop levelUsed for immediate publishingSet to true to publish now
scheduledForTop levelUsed instead of publishNow for schedulingTimestamp for scheduled publishing
timezoneTop levelUsed with scheduledForTimezone for the scheduled timestamp

Field names and example contract preserved; diagnostic checks are guidance, not observed API responses.

Failure matrix
FailureLikely causeCheck / fix
Authentication rejectedMissing or incorrect x-access-key headerRe-copy the key; confirm header name is exactly x-access-key
Account not foundaccountId does not match a connected accountRe-run GET /v1/connect/integrations and copy the correct id
Account not connectedAuthorization step never completedOpen the URL from GET /v1/connect/twitter, authorize, re-list integrations
Unsupported mediaBad mediaItems[].type, unreachable url, or count over stated limitValidate URL, use supported type, reduce count
Poll rejectedMore than 4 options or durationMinutes over 10080Trim options to at most 4; set duration within stated maximum
Scheduling rejectedMalformed scheduledFor, past timestamp, or invalid timezoneUse a valid future timestamp and recognized timezone name
Thread partially postedA middle thread item failedCheck which items posted before retrying
One platform fails in cross-postPer-platform constraint or unconnected accountInspect per-platform results; fix only the failing target

Field names and example contract preserved; diagnostic checks are guidance, not observed API responses.

Access-key header used on every request (illustrative_unexecuted)
-H "x-access-key: YOUR_API_KEY"
Get authorization URL for Twitter/X connection (illustrative_unexecuted)
curl {{API_BASE_URL}}/v1/connect/twitter \
  -H "x-access-key: YOUR_API_KEY"
List connected integrations to retrieve accountId (illustrative_unexecuted)
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
Post a basic text tweet (illustrative_unexecuted)
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
  }'
Post a tweet with mediaItems (illustrative_unexecuted)
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
  }'
Post a thread from a thread array (illustrative_unexecuted)
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
  }'
Post a poll with platformSpecificData poll (illustrative_unexecuted)
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
  }'
Schedule a tweet with scheduledFor timezone (illustrative_unexecuted)
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"
  }'
Cross-post to multiple platforms in one request (illustrative_unexecuted)
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
  }'