# x-api-rs

> High-performance Twitter/X API Python client built with Rust + PyO3
> Current version: 1.0.8 (2026-04-17)
>
> Also ships `twitter-cli` — a command-line binary for AI agents. See [CLI docs](/latest/cli/).

x-api-rs provides a complete async Python interface to the Twitter/X platform, including direct messaging, media upload, tweet management, user profiles, inbox conversations, community features, and account privacy settings. It uses Rust for performance and JA3/TLS fingerprint emulation for anti-detection.

**Important:** This is a native Rust extension (PyO3) — no `__init__.py` exists. All modules are compiled into a single binary. Do not rely on static Python source analysis for module discovery.

## Installation

```
pip install x-api-rs
```

## Quick Start

```python
import asyncio
from x_api_rs import Twitter

async def main():
    # All clients are created asynchronously
    client = await Twitter.create(cookies_string)

    # Access modules via attributes
    result = await client.dm.send_message("user_id", "Hello!")
    result = await client.posts.create_tweet(text="Hello World!")
    result = await client.user.get_profile("elonmusk")
    result = await client.upload.image(image_bytes, "tweet_image")

asyncio.run(main())
```

## Modules

- [DM (Direct Messages)](/latest/api/dm/): Send single/batch messages, v1 and v2 APIs, message encoding/decoding
- [Upload](/latest/api/upload/): Image and video upload with 3-phase flow (INIT → APPEND → FINALIZE)
- [Posts](/latest/api/posts/): Create/delete tweets, like/unlike, retweet, get timelines
- [User](/latest/api/user/): Profile queries, edit profile, avatar/banner, followers/following, follow/unfollow
- [Inbox](/latest/api/inbox/): DM inbox updates, XChat conversations, conversation count
- [Communities](/latest/api/communities/): Search communities, join communities
- [Settings](/latest/api/settings/): Account privacy settings, sensitive content settings, search safety
- [Search](/latest/api/search/): Search tweets (top/latest), users, media, and Lists with cursor pagination
- [Transaction](/latest/api/transaction/): Generate X-Client-Transaction-Id headers
- [Configuration](/latest/api/configuration/): ClientProfile browser identity (TLS+HTTP), proxy, HTTP/2 retry

## CLI (twitter-cli)

For AI agents that prefer shell + JSONL over embedding a Python runtime:

- [CLI Overview](/latest/cli/): Installation, 4-source auth chain, JSONL output envelope
- [Getting Started](/latest/cli/getting-started/): `cargo install x-api-rs --features cli`
- [Output Schema](/latest/cli/output-schema/): `Envelope<T>` + `BatchLine` + 12 `ErrorCode` variants
- [Full Reference](/latest/cli/llms-full.txt): All 15 commands with success/failure examples

## Key Design Points

- **All I/O methods are async** — use `await` for every API call
- **Client creation is async** — use `await Twitter.create(cookies)`, NOT `Twitter(cookies)`
- **Strongly typed results** — every method returns a typed result object (e.g., `DMResult`, `TweetResult`)
- **Module access** — `client.dm`, `client.posts`, `client.user`, `client.upload`, `client.inbox`, `client.communities`, `client.settings`, `client.search`
- **Standalone clients** — each module can also be used independently: `await DMClient.create(cookies)`

## Full API Reference

See [llms-full.txt](llms-full.txt) for the complete API with all method signatures, parameters, return types, and attributes.

## Documentation

- Website: https://x-api-rs.es007.com
- GitHub: https://github.com/Robin528919/x-api-rs
- PyPI: https://pypi.org/project/x-api-rs/
