https://github.com/nicshik/tweet-api-skill
Portable Codex skill and CLI helpers for reading X/Twitter data through twitterapi.io
https://github.com/nicshik/tweet-api-skill
agent-tools api-client cli-tool codex-skill python research social-media-research twitter twitterapi-io x-twitter
Last synced: 2 days ago
JSON representation
Portable Codex skill and CLI helpers for reading X/Twitter data through twitterapi.io
- Host: GitHub
- URL: https://github.com/nicshik/tweet-api-skill
- Owner: nicshik
- License: mit
- Created: 2026-04-22T06:04:33.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-04T08:22:40.000Z (26 days ago)
- Last Synced: 2026-05-04T09:35:59.630Z (26 days ago)
- Topics: agent-tools, api-client, cli-tool, codex-skill, python, research, social-media-research, twitter, twitterapi-io, x-twitter
- Language: Python
- Homepage: https://docs.twitterapi.io/
- Size: 62.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# TwitterAPI X Reader
[](https://github.com/nicshik/tweet-api-skill/actions/workflows/ci.yml)
[](LICENSE)
Portable skill and helper scripts for working with X (Twitter) through `twitterapi.io`.
[🇷🇺 Читать на русском](README.ru.md)
## 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`](https://github.com/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:
```bash
chmod +x ./install_portable.sh
./install_portable.sh
```
Then create your local key file if it does not already exist:
```bash
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:
```bash
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:
```bash
xread "https://x.com/ZenithTON/status/2046570503801119055"
```
Force article mode:
```bash
xread "2046570503801119055" --mode article
```
Download the best MP4 video from a tweet:
```bash
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:
```bash
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`:
```bash
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:
```bash
xmedia "" --output-dir ./downloads
```
The direct skill-script equivalent is:
```bash
python3 ~/.codex/skills/twitterapi-x-reader/scripts/twitterapi_media.py "" --output-dir ./downloads
```
The command writes one or more `.mp4` files and prints JSON like:
```json
{
"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:
```bash
xread "https://x.com/ZenithTON/status/2046570503801119055"
```
Look up the author profile:
```bash
xapi --method GET --path /twitter/user/info --query-json '{"userName":"ZenithTON"}'
```
Pull the author's recent tweets:
```bash
xapi --method GET --path /twitter/user/last_tweets --query-json '{"userName":"ZenithTON","includeReplies":false}'
```
Inspect replies:
```bash
xapi --method GET --path /twitter/tweet/replies/v2 --query-json '{"tweetId":"2046570503801119055","queryType":"Latest"}'
```
Inspect quote tweets:
```bash
xapi --method GET --path /twitter/tweet/quotes --query-json '{"tweetId":"2046570503801119055","includeReplies":false}'
```
Search accounts by topic:
```bash
xapi --method GET --path /twitter/user/search --query-json '{"query":"TON AI"}'
```
Search tweets by topic:
```bash
xapi --method GET --path /twitter/tweet/advanced_search --query-json '{"query":"\"AI agents\" Telegram TON","queryType":"Top"}'
```
Download tweet video media for later processing:
```bash
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:
```text
~/.codex/skills/twitterapi-x-reader/.env.local
```
Example:
```text
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:
```bash
python -m unittest discover -s tests
```
Check local documentation links:
```bash
python scripts/check_links.py
```
Verify the package entry points locally:
```bash
python -m pip install .
xapi --help
xread --help
xmedia --help
```
Validate the skill metadata with the Skill Creator validator when available:
```bash
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:
```bash
./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