Twitter / X

Connect a Twitter account

Kick off the OAuth flow. Synposter sends back a URL to redirect the user to.

curl -X POST https://api.synposter.com/v1/connect/twitter \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUri": "https://yourapp.com/connected"
  }'

{
  "authUrl": "https://x.com/i/oauth2/authorize?response_type=code&client_id=..."
}

Redirect the user to authUrl. After approval, Synposter creates a connected-account record under the user's profile and redirects back to your redirectUri with accountId, profileId, and handle in the query string. See Connect a social account for the full flow.

Look up the account ID

List the accounts on a profile to find the one you just connected. The id on the record is what you pass to POST /v1/posts.

curl https://api.synposter.com/v1/accounts?profileId={profileId} \
  -H "x-api-key: YOUR_API_KEY"

Post a tweet

curl -X POST https://api.synposter.com/v1/posts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [
      {
        "id": "acc_abc123",
        "platform": "twitter"
      }
    ],
    "text": "Hello from Synposter 🚀"
  }'

Text tweet

The simplest case. Send text at the top level; X applies its own URL-shortening and emoji counting on top of the 280 limit.

{
  "accounts": [{ "id": "acc_abc123", "platform": "twitter"}],
  "text": "Just shipped a new feature."
}

Tweet with image

Pass a public media URL in the top-level media array. Synposter fetches the file and uploads it to X's media endpoint before publishing. Up to 4 images per tweet.

{
  "accounts": [{ "id": "acc_abc123", "platform": "twitter"}],
  "text": "Behind the scenes",
  "media": [
    { "type": "image", "url": "https://yourcdn.com/screenshot.png"}
  ]
}

If you don't host the file yourself, generate a presigned URL via POST /v1/media and reference its publicUrl.

Tweet with GIF

Same shape as an image, with type: "gif". X allows exactly 1 GIF per tweet, no mixing with images. The file size limit on X is 15 MB for animated GIFs.

{
  "accounts": [{ "id": "acc_abc123", "platform": "twitter"}],
  "text": "ship it",
  "media": [
    { "type": "gif", "url": "https://yourcdn.com/celebrate.gif"}
  ]
}

Thread (multi-tweet)

Publish a sequence of tweets that reply to each other in a chain. The top-level text is the first tweet; platformOptions.threadItems are tweets 2..N. Each item can carry its own text and optional media. Total chain length is capped at 25.

{
  "accounts": [{
    "id": "acc_abc123",
    "platform": "twitter",
    "platformOptions": {
      "threadItems": [
        { "text": "2/ Here's why it matters."},
        { "text": "3/ Try it free at synposter.com"}
      ]
    }
  }],
  "text": "1/ Just shipped 🚀"
}

Tweets are published sequentially. If item K fails (rate-limited, content rejected, etc.), items 1..K-1 stay live on X — there's no rollback. The per-account response lists every attempted tweet in order so you can decide whether to retry the failed tail.

Reply to a tweet

Set platformOptions.replyToTweetId to the X tweet id you want to reply to.

{
  "accounts": [{
    "id": "acc_abc123",
    "platform": "twitter",
    "platformOptions": {
      "replyToTweetId": "1748391029384756102"
    }
  }],
  "text": "Great point — agree completely."
}

Synposter doesn't pre-validate that the target tweet exists. If it's deleted or otherwise unreachable, X's rejection comes back as platform_rejected.

Reply with a thread

Combine replyToTweetId and threadItems to publish a thread that's a reply to an existing tweet. The first tweet replies to the target; subsequent items chain off the first.

{
  "accounts": [{
    "id": "acc_abc123",
    "platform": "twitter",
    "platformOptions": {
      "replyToTweetId": "1748391029384756102",
      "threadItems": [
        { "text": "2/ The full picture is..."},
        { "text": "3/ ...nuanced."}
      ]
    }
  }],
  "text": "1/ Reply"
}