Getting Started with TweetsMash API

The TweetsMash API is a REST API at api.tweetsmash.com/v1 for your 𝕏 (Twitter) bookmarks and labels. Authenticate with a Bearer token and make your first request in a few minutes.

Before you start

Three things decide whether the API and MCP server will work for you:

• A plan that includes the API. The REST API, webhooks and the MCP server are part of the Yearly Pass. Free and Reader accounts can still call the API, but responses are limited to a small number of bookmarks with no pagination or advanced filters, and include an upgrade hint.
• An API token. Create one under Developer API in the app. Treat it like a password — it grants full access to your library. If you paste it somewhere public, revoke and regenerate it.
• Bookmarks (and, for some tools, a connected 𝕏 account). Import first — the API reads your Tweetsmash library, not 𝕏 directly. Tools that touch 𝕏 Lists or force a fresh pull additionally need your 𝕏 account connected at Connect 𝕏. Ask the MCP server get_connection_status to check this at any time.

Authentication

All API requests require authentication using your API key. Follow these steps to get your API key:

Quick Start Example

Here's a simple example of how to fetch your bookmarks using cURL:

cURL Command:

curl -X GET "https://api.tweetsmash.com/v1/bookmarks" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

Response Example:

{
  "status": true,
  "data": [
    {
      "post_id": "1938682607145034084",
      "tweet_details": {
        "text": "Your tweet content here...",
        "link": "https://twitter.com/username/status/1938682607145034084",
        "posted_at": "2025-06-27T19:35:27+00:00"
      },
      "author_details": {
        "name": "Author Name",
        "username": "username"
      }
    }
  ],
  "meta": {
    "next_cursor": "MTc1OTYxNw==",
    "limit": 20,
    "total_count": 396
  }
}

Rate Limits

To ensure fair usage, API requests are subject to rate limits:

Error Handling

The API returns standard HTTP status codes and error messages:

Troubleshooting

Next Steps

Now that you have your API key, explore the available endpoints: