# tweetsmash-api

tweetsmash-api — a skill for integrating TweetSmash REST API into scripts and tools. Retrieve bookmarks, apply filters, paginate, and manage labels without browser automation.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 214 installs · ★ 655 repo stars
- Author: Pedro Nauck
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/pedronauck/skills/tree/HEAD/skills/mine/tweetsmash-api/SKILL.md
- Updated: 2026-10-20
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/tweetsmash-api

## What it does

This skill exposes TweetSmash REST API endpoints for programmatic bookmark management. Fetch bookmarks with optional filtering, step through pages using cursors, and add or remove labels from groups of tweets. Requests use standard HTTP with Bearer token authentication; complex filters are built by running the included `build-bookmarks-url.py` script.

Setup requires a TweetSmash API key in the `TWEETSMASH_API_KEY` environment variable. The skill includes reference docs for current endpoints, filter formats, and JSON templates for label mutations. Response handling checks status codes — `402` means your plan lacks API access, `429` triggers exponential backoff using `Retry-After` headers.

Best for server-side scripts that organize bookmarks automatically. Browser automation and other Twitter/X APIs are out of scope.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill tweetsmash-api -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tweetsmash-api/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tweetsmash-api/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill tweetsmash-api -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tweetsmash-api/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill tweetsmash-api -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tweetsmash-api/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pedronauck/skills skills/mine/tweetsmash-api
```

2. **Manually: put the files in place**
- File: `.github/skills/tweetsmash-api/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill tweetsmash-api -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pedronauck/skills --path skills/mine/tweetsmash-api
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tweetsmash-api/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill tweetsmash-api -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pedronauck/skills/tree/HEAD/skills/mine/tweetsmash-api/SKILL.md

## When to use it
- fetch bookmarks filtered by date, author, or keyword
- apply or remove a label across multiple bookmarked tweets
- paginate through bookmarks using cursor-based navigation
- handle rate limits and authentication errors gracefully
- build URL-encoded filter parameters without manual concatenation

## Example prompts
- Get my bookmarks from the past month and group them by author
- Add the label 'ai-research' to all bookmarks containing 'transformer' or 'llm'
- Iterate through bookmarks 50 at a time, save them to JSON, and pause before the next batch if rate-limited

## Similar
- [raindrop-api](https://affpapa.org/en/nevibecode/skills/raindrop-api.md) — skill · 511 installs
- [api-filtering-sorting](https://affpapa.org/en/nevibecode/skills/api-filtering-sorting.md) — skill · 438 installs
- [x-api-integration](https://affpapa.org/en/nevibecode/agents/x-api-integration.md) — subagent · ★ 26718 repo stars
- [recoup-platform-api-access](https://affpapa.org/en/nevibecode/skills/recoup-platform-api-access.md) — skill · 5500 installs
- [fieldtheory-cli-bookmarks](https://affpapa.org/en/nevibecode/skills/fieldtheory-cli-bookmarks.md) — skill · 635 installs
- [notion-api](https://affpapa.org/en/nevibecode/skills/notion-api.md) — skill · 106200 installs

From the same set: [pedronauck/skills](https://affpapa.org/en/nevibecode/by/pedronauck/skills.md) — 52 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
