{"id":12210,"library":"twitter-openapi-typescript","title":"Twitter Internal API Client","description":"twitter-openapi-typescript is a TypeScript library that provides an implementation of Twitter's (now X's) *internal* API, allowing programmatic interaction with the platform without relying on the official, public API. It is currently in a pre-1.0 development phase, indicated by its `0.0.55` version, suggesting frequent updates and potential breaking changes without prior notice due to the nature of interacting with internal, undocumented endpoints. The library emphasizes ease of use with guest clients for public data access and supports authenticated clients via cookie-based login (`ct0`, `auth_token`). A key differentiator is its focus on the internal API, which offers capabilities beyond the public API, though at a higher risk of instability and account suspension. The project ships with full TypeScript types, enhancing developer experience.","status":"active","version":"0.0.55","language":"javascript","source_language":"en","source_url":"https://github.com/fa0311/twitter-openapi-typescript","tags":["javascript","twitter","api","typescript","scraper"],"install":[{"cmd":"npm install twitter-openapi-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add twitter-openapi-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add twitter-openapi-typescript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary class for initializing API access. The library is ESM-first, CJS `require` might lead to issues.","wrong":"const TwitterOpenApi = require('twitter-openapi-typescript').TwitterOpenApi;","symbol":"TwitterOpenApi","correct":"import { TwitterOpenApi } from 'twitter-openapi-typescript';"},{"note":"For advanced customization, direct instantiation of TwitterOpenApiClient might be preferred. Same ESM considerations apply.","wrong":"const { TwitterOpenApiClient } = require('twitter-openapi-typescript');","symbol":"TwitterOpenApiClient","correct":"import { TwitterOpenApiClient } from 'twitter-openapi-typescript';"},{"note":"The library exports named symbols, not a default export.","wrong":"import TwitterOpenApi from 'twitter-openapi-typescript';","symbol":"TwitterOpenApi","correct":"import { TwitterOpenApi } from 'twitter-openapi-typescript';"}],"quickstart":{"code":"import { TwitterOpenApi } from 'twitter-openapi-typescript';\n\nasync function getUserDetails() {\n  const api = new TwitterOpenApi();\n  // To avoid rate limits or access private data, you might need to log in:\n  // const client = await api.getClientFromCookies({\n  //   ct0: process.env.TWITTER_CT0 ?? '',\n  //   auth_token: process.env.TWITTER_AUTH_TOKEN ?? ''\n  // });\n  const client = await api.getGuestClient();\n  const response = await client.getUserApi().getUserByScreenName({ screenName: 'elonmusk' });\n  const userLegacy = response.data?.user?.legacy;\n  if (userLegacy) {\n    console.log(`@${userLegacy.screenName}`);\n    console.log(`Friends Count: ${userLegacy.friendsCount}, Followers Count: ${userLegacy.followersCount}`);\n  } else {\n    console.log('User not found or API response format changed.');\n  }\n}\n\ngetUserDetails();","lang":"typescript","description":"Demonstrates fetching a user's details (followers, friends count) using a guest client."},"warnings":[{"fix":"Monitor library updates and GitHub issues frequently. Be prepared to adapt your code to API changes or unexpected responses.","message":"This library relies on Twitter's undocumented internal APIs, which are subject to frequent and unannounced changes. This can lead to sudden breaking changes in the library's functionality, requiring updates or manual workarounds.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"Avoid modifying static variables unless absolutely necessary and with a full understanding of the implications. Use official API calls where possible.","message":"Modifying internal static variables (e.g., `TwitterOpenApi.fetchApi`, `TwitterOpenApi.twitter`, `TwitterOpenApi.bearer`) beyond what is explicitly documented can lead to account suspension by Twitter.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"Set the `sec-ch-ua-platform` header using `api.setAdditionalApiHeaders({'sec-ch-ua-platform': '\"Windows\"'})` (or other OS values) to match the token's origin.","message":"Authentication tokens are often bound to the operating system (specifically, the `sec-ch-ua-platform` header) that issued them. Using a token generated on Windows with a default Linux-configured client (or vice-versa) will result in authentication failures.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Pin to exact versions in `package.json` or frequently review release notes and test your integration after updates.","message":"The library is pre-1.0 (version 0.0.55), indicating that its API is not yet stable. Expect frequent updates, potential changes to method signatures, and evolving data structures without strict semantic versioning adherence.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Consult legal counsel to ensure compliance with the chosen license, especially for commercial or proprietary projects. Understand the implications of AGPLv3 for your codebase.","message":"The project is dual-licensed under a Custom License and GNU Affero General Public License v3.0 (AGPLv3). AGPLv3 is a strong copyleft license that requires distributing the source code of your application if it interacts with the AGPLv3-licensed library over a network.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `ct0` and `auth_token` are current and correctly passed to `getClientFromCookies()`. Check if the token's OS platform matches the client's `sec-ch-ua-platform` header.","cause":"Invalid, expired, or improperly configured authentication cookies/tokens.","error":"API request failed with status 401 Unauthorized"},{"fix":"Implement exponential backoff or introduce delays between requests. Consider using authenticated clients which might have higher rate limits than guest clients.","cause":"Twitter's internal API rate limits have been exceeded.","error":"API request failed with status 429 Too Many Requests"},{"fix":"Verify the `screenName` is correct. Check GitHub issues or the library's test cases for recent changes to API responses. Add robust error handling and null checks for API data.","cause":"The requested user does not exist, or Twitter's API response structure for user data has changed unexpectedly.","error":"User not found (or similar data parsing errors)"}],"ecosystem":"npm"}