X Api

1---2name: x-api3description: X/Twitter API integration for posting tweets, threads, reading timelines, search, and analytics. Covers OAuth auth patterns, rate limits, and platform-native content posting. Use when the user wants to interact with X programmatically.4origin: ECC5---6 7# X API8 9Programmatic interaction with X (Twitter) for posting, reading, searching, and analytics.10 11## When to Activate12 13- User wants to post tweets or threads programmatically14- Reading timeline, mentions, or user data from X15- Searching X for content, trends, or conversations16- Building X integrations or bots17- Analytics and engagement tracking18- User says "post to X", "tweet", "X API", or "Twitter API"19 20## Authentication21 22### OAuth 2.0 Bearer Token (App-Only)23 24Best for: read-heavy operations, search, public data.25 26```bash27# Environment setup28export X_BEARER_TOKEN="your-bearer-token"29```30 31```python32import os33import requests34 35bearer = os.environ["X_BEARER_TOKEN"]36headers = {"Authorization": f"Bearer {bearer}"}37 38# Search recent tweets39resp = requests.get(40    "https://api.x.com/2/tweets/search/recent",41    headers=headers,42    params={"query": "claude code", "max_results": 10}43)44tweets = resp.json()45```46 47### OAuth 1.0a (User Context)48 49Required for: posting tweets, managing account, DMs, and any write flow.50 51```bash52# Environment setup — source before use53export X_CONSUMER_KEY="your-consumer-key"54export X_CONSUMER_SECRET="your-consumer-secret"55export X_ACCESS_TOKEN="your-access-token"56export X_ACCESS_TOKEN_SECRET="your-access-token-secret"57```58 59Legacy aliases such as `X_API_KEY`, `X_API_SECRET`, and `X_ACCESS_SECRET` may exist in older setups. Prefer the `X_CONSUMER_*` and `X_ACCESS_TOKEN_SECRET` names when documenting or wiring new flows.60 61```python62import os63from requests_oauthlib import OAuth1Session64 65oauth = OAuth1Session(66    os.environ["X_CONSUMER_KEY"],67    client_secret=os.environ["X_CONSUMER_SECRET"],68    resource_owner_key=os.environ["X_ACCESS_TOKEN"],69    resource_owner_secret=os.environ["X_ACCESS_TOKEN_SECRET"],70)71```72 73## Core Operations74 75### Post a Tweet76 77```python78resp = oauth.post(79    "https://api.x.com/2/tweets",80    json={"text": "Hello from Claude Code"}81)82resp.raise_for_status()83tweet_id = resp.json()["data"]["id"]84```85 86### Post a Thread87 88```python89def post_thread(oauth, tweets: list[str]) -> list[str]:90    ids = []91    reply_to = None92    for text in tweets:93        payload = {"text": text}94        if reply_to:95            payload["reply"] = {"in_reply_to_tweet_id": reply_to}96        resp = oauth.post("https://api.x.com/2/tweets", json=payload)97        tweet_id = resp.json()["data"]["id"]98        ids.append(tweet_id)99        reply_to = tweet_id100    return ids101```102 103### Read User Timeline104 105```python106resp = requests.get(107    f"https://api.x.com/2/users/{user_id}/tweets",108    headers=headers,109    params={110        "max_results": 10,111        "tweet.fields": "created_at,public_metrics",112    }113)114```115 116### Search Tweets117 118```python119resp = requests.get(120    "https://api.x.com/2/tweets/search/recent",121    headers=headers,122    params={123        "query": "from:affaanmustafa -is:retweet",124        "max_results": 10,125        "tweet.fields": "public_metrics,created_at",126    }127)128```129 130### Pull Recent Original Posts for Voice Modeling131 132```python133resp = requests.get(134    "https://api.x.com/2/tweets/search/recent",135    headers=headers,136    params={137        "query": "from:affaanmustafa -is:retweet -is:reply",138        "max_results": 25,139        "tweet.fields": "created_at,public_metrics",140    }141)142voice_samples = resp.json()143```144 145### Get User by Username146 147```python148resp = requests.get(149    "https://api.x.com/2/users/by/username/affaanmustafa",150    headers=headers,151    params={"user.fields": "public_metrics,description,created_at"}152)153```154 155### Upload Media and Post156 157```python158# Media upload uses v1.1 endpoint159 160# Step 1: Upload media161media_resp = oauth.post(162    "https://upload.twitter.com/1.1/media/upload.json",163    files={"media": open("image.png", "rb")}164)165media_id = media_resp.json()["media_id_string"]166 167# Step 2: Post with media168resp = oauth.post(169    "https://api.x.com/2/tweets",170    json={"text": "Check this out", "media": {"media_ids": [media_id]}}171)172```173 174## Rate Limits175 176X API rate limits vary by endpoint, auth method, and account tier, and they change over time. Always:177- Check the current X developer docs before hardcoding assumptions178- Read `x-rate-limit-remaining` and `x-rate-limit-reset` headers at runtime179- Back off automatically instead of relying on static tables in code180 181```python182import time183 184remaining = int(resp.headers.get("x-rate-limit-remaining", 0))185if remaining < 5:186    reset = int(resp.headers.get("x-rate-limit-reset", 0))187    wait = max(0, reset - int(time.time()))188    print(f"Rate limit approaching. Resets in {wait}s")189```190 191## Error Handling192 193```python194resp = oauth.post("https://api.x.com/2/tweets", json={"text": content})195if resp.status_code == 201:196    return resp.json()["data"]["id"]197elif resp.status_code == 429:198    reset = int(resp.headers["x-rate-limit-reset"])199    raise Exception(f"Rate limited. Resets at {reset}")200elif resp.status_code == 403:201    raise Exception(f"Forbidden: {resp.json().get('detail', 'check permissions')}")202else:203    raise Exception(f"X API error {resp.status_code}: {resp.text}")204```205 206## Security207 208- **Never hardcode tokens.** Use environment variables or `.env` files.209- **Never commit `.env` files.** Add to `.gitignore`.210- **Rotate tokens** if exposed. Regenerate at developer.x.com.211- **Use read-only tokens** when write access is not needed.212- **Store OAuth secrets securely** — not in source code or logs.213 214## Integration with Content Engine215 216Use `brand-voice` plus `content-engine` to generate platform-native content, then post via X API:2171. Pull recent original posts when voice matching matters2182. Build or reuse a `VOICE PROFILE`2193. Generate content with `content-engine` in X-native format2204. Validate length and thread structure2215. Return the draft for approval unless the user explicitly asked to post now2226. Post via X API only after approval2237. Track engagement via public_metrics224 225## Related Skills226 227- `brand-voice` — Build a reusable voice profile from real X and site/source material228- `content-engine` — Generate platform-native content for X229- `crosspost` — Distribute content across X, LinkedIn, and other platforms230- `connections-optimizer` — Reorganize the X graph before drafting network-driven outreach