X OAuth API Skill

Post to X (formerly Twitter) using the official X API with OAuth 1.0a authentication.

Overview

This skill provides direct access to X API v2 for posting tweets, managing threads, and monitoring mentions. No proxy or third-party service required — uses your X API credentials directly.

Use when:

• User says "post to X", "tweet this", "post on Twitter"
• Need to create threads or media posts
• Want to check mentions or engage with replies

Quick Start

1. Configure X API Credentials

Store these environment variables (from your X Developer Account):

X_API_KEY              # Consumer Key (API Key)
X_API_SECRET           # Consumer Secret
X_ACCESS_TOKEN         # Access Token
X_ACCESS_TOKEN_SECRET  # Access Token Secret
X_USER_ID              # Optional: Your numeric user ID (speeds up mentions)

Free Tier vs Paid Tier

Free tier supports:

• ✅ Posting tweets and threads
• ✅ Deleting tweets
• ✅ Account info lookup (x me)

Requires Basic+ tier:

• 🔒 Search tweets
• 🔒 Fetch mentions
• 🔒 Media uploads

2. Basic Usage

# Post a simple tweet
x post "Hello from X API"

# Post a thread
x thread "First tweet" "Second tweet" "Third tweet"

# Check mentions
x mentions --limit 10

# Search recent tweets
x search "AI agents" --limit 5

Commands

x post <text>

Post a single tweet.

Options:

• --reply-to <tweet-id> - Reply to a specific tweet
• --quote <tweet-id> - Quote tweet
• --media <file> - Attach image/video

x thread <tweet1> <tweet2> ...

Post a tweet thread.

x mentions [options]

Get recent mentions of your account.

Options:

• --limit <n> - Number of mentions (default: 10, max: 100)
• --since <tweet-id> - Only mentions after this ID
• --format json - Output as JSON

x search <query> [options]

Search recent tweets.

Options:

• --limit <n> - Number of results (default: 10, max: 100)
• --format json - Output as JSON

x delete <tweet-id>

Delete a tweet.

x me

Show current account info (name, username, follower counts, user ID).

API Rate Limits

Endpoint	Limit	Window
POST /2/tweets	200	15 min (Free tier)
GET /2/tweets/search/recent	100	15 min (Free tier)
GET /2/users/:id/mentions	100	15 min (Free tier)

Rate limits vary by access tier. See X API documentation for details.

Authentication

OAuth 1.0a is handled transparently. Just provide your credentials via environment variables. The skill will sign all requests automatically.

Troubleshooting

"Unauthorized" error

• Check X API credentials are correct
• Verify credentials are set in environment
• Ensure your app has write permissions in X Developer Portal

"Rate limit exceeded"

• Wait 15 minutes for limit to reset
• Reduce request frequency

"This endpoint requires a paid X API tier"

• Search and mentions require Basic+ tier on X API
• Free tier only supports posting, deleting, and account lookup

Requirements

• X Developer Account with API access
• OAuth 1.0a credentials configured
• Network access to api.twitter.com

Cost

Free. X API is free for basic usage. Check your app's rate limits in X Developer Portal.

Gotchas

• Free tier only supports posting, deleting, and account lookup — search, mentions, and media uploads require Basic+ tier ($100/month). Don't attempt these on free tier; you'll get a clear "requires paid tier" error.
• "Unauthorized" after credential rotation — X API keys are invalidated when you regenerate them in the Developer Portal. All 4 env vars must be updated together (X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET).
• Trailing newlines in env vars break auth — If you copy/paste credentials and include a trailing \n, OAuth signing will fail silently with a 401. Always verify with echo -n "$X_API_KEY" | xxd to confirm no whitespace.
• Rate limit 429s are per-endpoint — Hitting the limit on POST /2/tweets doesn't affect GET /2/users. Each endpoint has its own 15-minute window. Back off only the failing endpoint.
• App write permissions must be set before generating tokens — If you generate access tokens before enabling "Read and Write" in the Developer Portal, the tokens will be read-only. Regenerate tokens after changing permissions.