X (Twitter) API

Postproxy publishes tweets, native polls, and tweet chains (threads) to X. X is a bring-your-own-keys integration — you connect your own developer app. There is no comment or direct-message API.

Every request below uses the base URL https://api.postproxy.dev and an Authorization: Bearer YOUR_API_KEY header. Replace YOUR_API_KEY and the example IDs with your own.

At a glance

Platform ID	twitter
Formats	post (default), poll
Character limit	280 (free) / 25,000 (paid); polls always 280
Media	Optional (post); not allowed (poll)
Placements	None
Comments	No
Direct messages	No
Post chains	Yes

Publishing

Formats

Format	Description
post	Tweet (default). Content type is inferred from the attached media
poll	Tweet with a native poll

Tweet (post)

The post format has no custom parameters.

Media	Max size	Formats	Count	Duration
Image	5 MB	jpg, png, webp, gif	4	—
Video	512 MB	mp4, mov	1	1 s – 140 s

• Text-only tweets are allowed; media is optional.
• Images and video cannot be mixed.
• Minimum image dimensions 4×4 px; minimum video dimensions 32×32 px.

# Tweet with an image
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": { "body": "Just shipped a new feature! Check it out 🎉" },
       "profiles": ["prof_abc123"],
       "media": ["https://example.com/image.jpg"],
       "platforms": { "twitter": {} }
     }'

Poll (poll)

Parameter	Type	Required	Description
format	string	Yes	"poll"
poll_options	array of strings	Yes	2–4 choices, max 25 characters each
poll_duration_minutes	integer	Yes	5 to 10,080 (7 days)

Polls are capped at 280 characters and cannot include media or be part of a thread.

# Poll
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": { "body": "Which framework do you prefer?" },
       "profiles": ["prof_abc123"],
       "platforms": {
         "twitter": {
           "format": "poll",
           "poll_options": ["Rails", "Django", "Laravel", "Other"],
           "poll_duration_minutes": 1440
         }
       }
     }'

Post chains (threads)

X supports threads for the post format. Pass a thread array of follow-up tweets; each child can carry its own media. Polls cannot be threaded.

# A tweet thread
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": { "body": "1/ A short thread on what we learned 🧵" },
       "profiles": ["prof_abc123"],
       "thread": [
         { "body": "2/ Ship small, ship often." },
         { "body": "3/ Talk to users every week.", "media": ["https://example.com/chart.png"] }
       ]
     }'

Comments

Not supported through the API.

Direct messages

Not supported.

Webhooks

Subscribe with the Webhooks API:

curl -X POST "https://api.postproxy.dev/api/webhooks" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://example.com/webhooks/postproxy",
       "events": ["platform_post.published", "platform_post.failed", "platform_post.insights"]
     }'

Events relevant to X:

Event	When
post.processed	A post is ready to publish
platform_post.published	A post was published to the platform
platform_post.failed	A post failed to publish (retries exhausted)
platform_post.failed_waiting_for_retry	A publish attempt failed; will retry
platform_post.insights	New analytics snapshot
profile.connected / .disconnected	Connection state changed
profile.stats	New profile stats snapshot
media.failed	A media attachment failed to process

Notes

• The character limit depends on your X account tier: 280 on free, 25,000 on paid. Polls are always capped at 280.
• X requires your own API keys — see the X bring-your-own-keys guide.
• poll, media, and threads are mutually exclusive.