TwitterAPI X Reader

Portable skill and helper scripts for working with X (Twitter) through twitterapi.io.

🇷🇺 Читать на русском

Overview

This repository packages a reusable skill plus terminal helpers for reading tweets, X Articles, downloading tweet videos, and calling other documented twitterapi.io endpoints without relying on direct x.com rendering.

It is designed for people who want:

• a portable skill install in ~/.codex/skills/twitterapi-x-reader;
• simple terminal commands like xread, xapi, and xmedia;
• a stable path for research, summarization, and structured extraction from X.

This project is not affiliated with X Corp., Twitter, or twitterapi.io.

Maintainer: nicshik.

What Is Included

• SKILL.md for agent environments that support skill-style workflows
• agents/openai.yaml for UI metadata
• references/ with quickstart, human-readable notes, and research examples
• scripts/ with Python helpers
• bin/xread, bin/xapi, and bin/xmedia terminal wrappers
• install_portable.sh for install and update

Requirements

• Python 3.10 or newer
• zsh, rsync, and install for install_portable.sh
• a twitterapi.io API key

Installation

Portable Skill Install

From the repository root:

chmod +x ./install_portable.sh
./install_portable.sh

Then create your local key file if it does not already exist:

mkdir -p ~/.codex/skills/twitterapi-x-reader
printf '%s\n' 'TWITTERAPI_IO_KEY=your_key_here' > ~/.codex/skills/twitterapi-x-reader/.env.local

If your shell does not already include ~/.local/bin in PATH, add it.

CLI Package Install

If you only need the xread, xapi, and xmedia console scripts, install the package directly:

python -m pip install "git+https://github.com/nicshik/tweet-api-skill.git"

The package install does not install the Codex skill files. Use TWITTERAPI_IO_KEY or --api-key for authentication.

Quick Start

Fetch a tweet or article:

xread "https://x.com/ZenithTON/status/2046570503801119055"

Force article mode:

xread "2046570503801119055" --mode article

Download the best MP4 video from a tweet:

xmedia "https://x.com/Yoda4ever/status/2049680135658336270?s=20" --output-dir ./downloads

xmedia prints JSON with the saved file path, byte count, source media URL, bitrate, and media key. Downloads are limited to HTTPS URLs under video.twimg.com.

Call any documented endpoint:

xapi --method GET --path /oapi/my/info --query-json '{}'

xapi accepts official API paths by default. Full URLs are only accepted for https://api.twitterapi.io so the API key is not sent to arbitrary hosts.

Mutating HTTP methods are blocked unless you pass --allow-mutation:

xapi --method POST --path /twitter/post/create --body-json '{"text":"draft"}' --allow-mutation

Video Downloads

For an installed skill, video export is initiated with the global wrapper:

xmedia "<tweet-url-or-id>" --output-dir ./downloads

The direct skill-script equivalent is:

python3 ~/.codex/skills/twitterapi-x-reader/scripts/twitterapi_media.py "<tweet-url-or-id>" --output-dir ./downloads

The command writes one or more .mp4 files and prints JSON like:

{
  "kind": "media_download",
  "tweet_id": "2049680135658336270",
  "files": [
    {
      "path": "/absolute/path/to/2049680135658336270-media-1-2176000.mp4",
      "bytes": 5744965,
      "bitrate": 2176000,
      "media_key": "13_2049617901142118400",
      "url": "https://video.twimg.com/..."
    }
  ],
  "source": "twitterapi.io"
}

Useful flags:

• --output-dir ./downloads sets the destination directory.
• --first downloads only the first video media item.
• --filename name.mp4 sets the output name when exactly one file is selected.
• --overwrite replaces an existing file.

Practical Workflows

Read a tweet or X Article and then analyze it:

xread "https://x.com/ZenithTON/status/2046570503801119055"

Look up the author profile:

xapi --method GET --path /twitter/user/info --query-json '{"userName":"ZenithTON"}'

Pull the author's recent tweets:

xapi --method GET --path /twitter/user/last_tweets --query-json '{"userName":"ZenithTON","includeReplies":false}'

Inspect replies:

xapi --method GET --path /twitter/tweet/replies/v2 --query-json '{"tweetId":"2046570503801119055","queryType":"Latest"}'

Inspect quote tweets:

xapi --method GET --path /twitter/tweet/quotes --query-json '{"tweetId":"2046570503801119055","includeReplies":false}'

Search accounts by topic:

xapi --method GET --path /twitter/user/search --query-json '{"query":"TON AI"}'

Search tweets by topic:

xapi --method GET --path /twitter/tweet/advanced_search --query-json '{"query":"\"AI agents\" Telegram TON","queryType":"Top"}'

Download tweet video media for later processing:

xmedia "https://x.com/Yoda4ever/status/2049680135658336270?s=20" --output-dir ./downloads --overwrite

If a tweet has several video media items, xmedia downloads all of them by default. Use --first to download only the first item, or --filename custom-name.mp4 when exactly one item is selected.

For more detailed examples, see:

• references/research_examples.md
• references/capabilities.md
• references/api_quickstart.md
• references/endpoint_catalog.md

API Key Handling

This repository does not store API keys.

The expected local key file is:

~/.codex/skills/twitterapi-x-reader/.env.local

Example:

TWITTERAPI_IO_KEY=your_key_here

The scripts also accept --api-key, but environment variables or .env.local are preferred because command-line arguments can be recorded in shell history.

Development

Run the no-network tests:

python -m unittest discover -s tests

Check local documentation links:

python scripts/check_links.py

Verify the package entry points locally:

python -m pip install .
xapi --help
xread --help
xmedia --help

Validate the skill metadata with the Skill Creator validator when available:

python /path/to/skill-creator/scripts/quick_validate.py .

Support / Security

Use GitHub Issues for questions, bugs, and feature requests.

Report security vulnerabilities privately through SECURITY.md. Do not open public issues with API keys, .env.local, private account data, or exploit details.

Update Flow

After pulling new changes from this repository, refresh the portable install with:

./install_portable.sh

This updates the installed skill and global wrappers while preserving the local .env.local file.

Older local installs under ~/.codex/skills/twitterapi_x_reader are detected during installation. The installer copies the legacy .env.local into the new hyphen-case skill directory when needed, and the xread/xapi/xmedia wrappers still check the legacy path for compatibility.

Notes

• The default posture is read-only.
• Mutating API endpoints should only be used intentionally.
• Media downloads write local files and are limited to video.twimg.com.
• certifi is supported when available, but the scripts can also fall back to the system certificate store.
• See SECURITY.md before publishing logs, examples, or bug reports.

License

MIT