x-api

X API

Programmatic interaction with X (Twitter) for posting, reading, searching, and analytics.

Check the current X developer documentation for endpoint availability, account access, pricing, quotas, and required scopes before implementation. OAuth 2.0 user-context authorization can support writes when the app and user grant the required scopes; an app-only bearer token is for operations permitted to application authentication and does not authorize user actions. Publishing is an external side effect and requires explicit user instruction.

When to Activate

• User wants to post tweets or threads programmatically
• Reading timeline, mentions, or user data from X
• Searching X for content, trends, or conversations
• Building X integrations or bots
• Analytics and engagement tracking
• User says "post to X", "tweet", "X API", or "Twitter API"

Authentication

OAuth 2.0 Bearer Token (App-Only)

Best for: read-heavy operations, search, public data.

# Environment setup
export X_BEARER_TOKEN="your-bearer-token"

import os
import requests

bearer = os.environ["X_BEARER_TOKEN"]
headers = {"Authorization": f"Bearer {bearer}"}

# Search recent tweets
resp = requests.get(
    "https://api.x.com/2/tweets/search/recent",
    headers=headers,
    params={"query": "claude code", "max_results": 10}
)
tweets = resp.json()

OAuth 1.0a (User Context)

Required for: posting tweets, managing account, DMs.

# Environment setup — source before use
export X_API_KEY="your-api-key"
export X_API_SECRET="your-api-secret"
export X_ACCESS_TOKEN="your-access-token"
export X_ACCESS_SECRET="your-access-secret"

import os
from requests_oauthlib import OAuth1Session

oauth = OAuth1Session(
    os.environ["X_API_KEY"],
    client_secret=os.environ["X_API_SECRET"],
    resource_owner_key=os.environ["X_ACCESS_TOKEN"],
    resource_owner_secret=os.environ["X_ACCESS_SECRET"],
)

Core Operations

Post a Tweet

resp = oauth.post(
    "https://api.x.com/2/tweets",
    json={"text": "Example post text"}
)
resp.raise_for_status()
tweet_id = resp.json()["data"]["id"]