Tweetsmash API
Apps & Automationtweetsmash-apiTweetsmash API is an Agent Skill for apps & automation published in the pedronauck/skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Uses the TweetSmash REST API to fetch bookmarks, inspect labels, and add or remove labels from saved tweets. Use when integrating TweetSmash into scripts, agents, workflows, cron jobs, or internal tools that need bookmark retrieval, filtering, pagination, or label management. Do not use for direct browser automation inside TweetSmash, unrelated X or Twitter APIs, or tasks that only need product marketing copy.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/pedronauck/skills/blob/HEAD/skills/mine/tweetsmash-api/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tweetsmash-api, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
TweetSmash API
Use this skill to work directly with the TweetSmash REST API after verifying the current docs. Read references/api-reference.md before choosing an endpoint. Read references/bookmarks-filters.md only when bookmark filtering is required.
Procedures
Step 1: Validate Credentials and Scope
- Confirm that a TweetSmash API key is available before making requests. Prefer
TWEETSMASH_API_KEYin the shell environment. - Read
references/api-reference.mdto confirm the current endpoint, required headers, rate limits, and status codes. - If the task requires bookmark filtering or pagination, read
references/bookmarks-filters.md.
Step 2: Build the Request
- Use
Authorization: Bearer $TWEETSMASH_API_KEYon every request. - Use
Content-Type: application/jsonfor all examples in this skill. Keep the base URL ashttps://api.tweetsmash.com/v1. - If the task fetches bookmarks with filters, execute
python3 scripts/build-bookmarks-url.pywith the needed flags to generate a correctly encoded URL. - If the task adds labels, start from
assets/add-labels-body.jsonand fill intweet_idsplus eitherlabel_idorlabel_name. - If the task removes labels, start from
assets/remove-labels-body.jsonand fill intweet_idspluslabel_name.
Step 3: Execute the Correct Endpoint
- Fetch bookmarks with
GET /bookmarks. Use the URL fromscripts/build-bookmarks-url.pywhen filters, search, or cursors are present. - List labels with
GET /labelswhen the task needs current label IDs, label names, or usage counts. - Add labels with
POST /labels/addwhen the task needs to organize one or more bookmarked tweets. - Remove labels with
POST /labels/removewhen the task needs to clean up or reclassify bookmarked tweets. - Use cURL for quick execution or translate the same request into the caller’s runtime only after the endpoint and payload are confirmed.
Step 4: Verify the Response
- Confirm that the response JSON contains
"status": truebefore reporting success. - For bookmark reads, inspect
meta.next_cursor,meta.limit, andmeta.total_countwhen pagination matters. - For label mutations, confirm the success message matches the intended action.
- If the task depends on label existence, call
GET /labelsagain after a mutation to verify the resulting state.
Step 5: Return a Usable Result
- Summarize the request method, endpoint, and effective filters or payload fields that were used.
- Return the response body or a structured summary, depending on the caller’s requested output format.
- If follow-up pagination is possible, expose
meta.next_cursorso the next request can continue from the prior page.
Error Handling
- If authentication fails with
401, confirm that the bearer token is present, non-empty, and taken from the correct TweetSmash account. - If the API returns
402, stop and report that the current plan does not permit the requested API access. - If the API returns
429, stop sending additional requests, note the documented limit of 100 requests per hour per API key, and retry later. - If a bookmark query becomes hard to assemble by hand, rerun
python3 scripts/build-bookmarks-url.py --helpand rebuild the URL instead of manually concatenating query strings. - If a label mutation is ambiguous, list labels first with
GET /labelsand then rerun the mutation using the confirmed label identifier or label name.