X API Knowledge

Post Creation

X API v2 endpoint for creating posts:

POST https://api.x.com/2/tweets
Authorization: Bearer {access_token}
Content-Type: application/json

{"text": "Hello world"}

With media:

{
  "text": "Check this out",
  "media": {
    "media_ids": ["1234567890"]
  }
}

Authentication

X uses OAuth 2.0 with PKCE (Proof Key for Code Exchange):

• •Authorization URL: https://x.com/i/oauth2/authorize
• •Token URL: https://api.x.com/2/oauth2/token
• •Access tokens expire in 2 hours
• •Refresh tokens valid for 6 months (requires offline.access scope)
• •The plugin auto-refreshes tokens before each API call

Required scopes: tweet.read tweet.write users.read media.write offline.access

Media Upload

Single-shot upload to POST https://api.x.com/2/media/upload:

• •Format: multipart/form-data
• •Fields: media_data (base64), media_category ("tweet_image")
• •Returns data.id (media ID string)

Constraints

• •Max 4 images per post
• •Images: max 5 MB (JPG, PNG, GIF, WEBP)
• •GIFs: max 15 MB, resolution max 1280x1080
• •Videos: max 512 MB, 0.5-140 seconds (requires chunked upload)

Post Content Guidelines

• •Free tier: 280 characters per post
• •Premium/X Blue: 25,000 characters
• •Hashtags: use sparingly, 2-3 max
• •@mentions count toward character limit
• •URLs are shortened to 23 characters by t.co
• •Line breaks are preserved

Free Tier Limits

• •1,500 posts per month
• •Write-only (cannot read timelines)
• •Media upload available with media.write scope
• •Rate limit: measured in 24-hour windows

Common Errors

• •401 Unauthorized: Token expired. The plugin auto-refreshes, but if refresh fails, re-run /x:setup.
• •403 Forbidden: Missing required scope or app permissions. Check User Authentication Settings in the developer portal.
• •429 Too Many Requests: Rate limited. Wait and retry.
• •400 Bad Request: Invalid payload. Check character count and media IDs.

Reply and Quote Posts

Reply:

{
  "text": "Great point!",
  "reply": {"in_reply_to_tweet_id": "1234567890"}
}

Quote:

{
  "text": "This is interesting",
  "quote_tweet_id": "1234567890"
}

Scripts Location

The X API scripts are at ${CLAUDE_PLUGIN_ROOT}/scripts/:

• •oauth-server.py - OAuth 2.0 PKCE flow with local callback server and auto token refresh
• •x-api.py - Post creation, media upload, auth check, token refresh