Rettiwt-API

Rettiwt-API supports a wide range of operations across several services. Key capabilities include:

• Direct Messages: Inbox access, conversation history, and deleting conversations.
• Jobs: Job details, location suggestions, and job searching.
• Lists: Managing members (add/remove), list details, member lists, muting/unmuting, and retrieving tweets from lists.
• Spaces: Retrieving space details.
• Tweets: Bookmarking, posting, scheduling, liking, retweeting, uploading media, searching, and streaming filtered tweets in pseudo-realtime. It also supports retrieving edit history, replies, and likers/retweeters.
• Users: Profile management (update profile, image, banner, username, password), following/unfollowing, retrieving timelines (media, replies, tweet), bookmarks, likes, notifications (pseudo-realtime), and user analytics (premium accounts only).

Rettiwt-API supports two authentication modes:

1. 'Guest' authentication (Default): Does not require logging in. It provides limited access to:

   • Tweet Details
   • Space Details
   • User Details (by username)
   • User Timeline

2. 'User' authentication: Requires an API_KEY generated from your Twitter/X account cookies. This grants access to the full suite of resources, including Direct Messages, Lists, Tweet posting/retweeting, User profile updates, and more.

You can provide a responseMiddleware function in the Rettiwt configuration. This function receives the raw AxiosResponse object, allowing you to access response headers (e.g., x-rate-limit-limit, x-rate-limit-remaining, x-rate-limit-reset) without blocking the main execution flow.

const rettiwt = new Rettiwt({
	responseMiddleware: (res): void => {
		console.log(`Rate limit: ${res.headers['x-rate-limit-limit']}`);
		console.log(`Rate limit remaining: ${res.headers['x-rate-limit-remaining']}`);
		console.log(`Rate limit reset timestamp (seconds): ${res.headers['x-rate-limit-reset']}`);
	},
});

You can start the playground using npm start. You can run this command from the root of the monorepo using the workspace flag, or directly from within the playground directory.

The main entry point for experimentation is index.js.

# From the monorepo root
npm start --workspace=playground

# From the playground directory
npm start

CLI Installation

To use Rettiwt-API as a command-line tool, install it globally:

npm install -g rettiwt-api

Verify the installation by running:

rettiwt help

Dependency Installation

To use Rettiwt-API in your own NodeJS project, install it locally:

npm install --save rettiwt-api
# or
yarn add rettiwt-api

If installed locally, you must prepend CLI commands with npx to execute them.

To experiment with different API features, edit the index.js file within the playground directory.

Because rettiwt-api is linked via npm workspaces, any changes you make to the source code in src will be immediately available in the playground (you may need to rebuild the source if necessary).

The Rettiwt Playground is a local development environment designed for testing and experimenting with rettiwt-api features.

Prerequisites

• Node.js: v22 or higher is recommended.
• npm: v7+ is recommended for workspace support.

Installation Steps

1. Install dependencies: From the root of the monorepo, run npm install. This installs dependencies for all workspaces, including playground and src.
2. Configure Environment: Create a .env file inside the playground directory and add your API key:

   API_KEY=your_api_key_here

The Rettiwt constructor accepts a configuration object with the following properties:

Hot-swappable properties: You can update apiKey, headers, and proxy on an existing instance using their respective setters.

To mask your IP address, you can pass a proxy configuration to the Rettiwt constructor. It supports HTTP/HTTPS and SOCKS proxies.

• HTTP/HTTPS Proxy: Pass a URL string or an AxiosProxyConfiguration object.
• SOCKS Proxy: Pass a SOCKS proxy URL string.

// HTTP/HTTPS proxy
const rettiwt = new Rettiwt({ apiKey: API_KEY, proxy: '<PROXY_URL_STRING_OR_CONFIG>' });

// SOCKS proxy
const rettiwt = new Rettiwt({ apiKey: API_KEY, proxy: '<PROXY_URL>' });

To troubleshoot unexpected behavior, enable debug logs by setting the logging property to true in the Rettiwt configuration. Logs will be printed to the console.

const rettiwt = new Rettiwt({ apiKey: API_KEY, logging: true });

The Rettiwt instance provides access to various public services organized by domain. Common services include:

• TweetService: For interacting with tweets, retweets, and likes.
• UserService: For managing user profiles, followers, and following.
• DirectMessageService: For handling DMs and inbox data.
• ListService: For managing tweet lists.
• SpaceService: For interacting with Twitter Spaces.
• JobService: For managing background jobs.
• FetcherService: For general fetching operations.