tweetsmash-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

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.

使用本技能可在核对当前文档后直接调用TweetSmash REST API。选择端点前请先阅读

references/api-reference.md

。仅当需要书签筛选功能时再阅读

references/bookmarks-filters.md

。

Step 1: Validate Credentials and Scope

Confirm that a TweetSmash API key is available before making requests. Prefer
```
TWEETSMASH_API_KEY
```
in the shell environment.
Read
```
references/api-reference.md
```
to 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_KEY

on every request.

Use

Content-Type: application/json

for all examples in this skill. Keep the base URL as

https://api.tweetsmash.com/v1

If the task fetches bookmarks with filters, execute
```
python3 scripts/build-bookmarks-url.py
```
with the needed flags to generate a correctly encoded URL.
If the task adds labels, start from
```
assets/add-labels-body.json
```
and fill in
```
tweet_ids
```
plus either
```
label_id
```
or
```
label_name
```
.
If the task removes labels, start from
```
assets/remove-labels-body.json
```
and fill in
```
tweet_ids
```
plus
```
label_name
```
.

Step 3: Execute the Correct Endpoint

Fetch bookmarks with
```
GET /bookmarks
```
. Use the URL from
```
scripts/build-bookmarks-url.py
```
when filters, search, or cursors are present.
List labels with
```
GET /labels
```
when the task needs current label IDs, label names, or usage counts.
Add labels with
```
POST /labels/add
```
when the task needs to organize one or more bookmarked tweets.
Remove labels with
```
POST /labels/remove
```
when 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": true
```
before reporting success.
For bookmark reads, inspect
```
meta.next_cursor
```
,
```
meta.limit
```
, and
```
meta.total_count
```
when pagination matters.
For label mutations, confirm the success message matches the intended action.
If the task depends on label existence, call
```
GET /labels
```
again 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_cursor
```
so the next request can continue from the prior page.

步骤1：验证凭证与权限范围

步骤2：构建请求

所有请求都携带

Authorization: Bearer $TWEETSMASH_API_KEY

请求头。

本技能中的所有示例均使用
```
Content-Type: application/json
```
请求头，基础URL固定为
```
https://api.tweetsmash.com/v1
```
。
如果任务需要带筛选条件获取书签，携带所需参数执行
```
python3 scripts/build-bookmarks-url.py
```
来生成编码正确的URL。
如果任务需要添加标签，基于
```
assets/add-labels-body.json
```
文件填写
```
tweet_ids
```
以及
```
label_id
```
或
```
label_name
```
字段。
如果任务需要移除标签，基于
```
assets/remove-labels-body.json
```
文件填写
```
tweet_ids
```
和
```
label_name
```
字段。

步骤3：调用正确端点

步骤4：验证响应

步骤5：返回可用结果

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 --help
```
and rebuild the URL instead of manually concatenating query strings.
If a label mutation is ambiguous, list labels first with
```
GET /labels
```
and then rerun the mutation using the confirmed label identifier or label name.

如果鉴权失败返回
```
401
```
，确认Bearer Token存在、非空，且来自正确的TweetSmash账号。
如果API返回
```
402
```
，停止操作并上报当前套餐不支持请求的API访问权限。
如果API返回
```
429
```
，停止发送额外请求，留意文档规定的每个API密钥每小时最多100次请求的限制，稍后再重试。
如果手动拼接书签查询URL过于复杂，重新执行
```
python3 scripts/build-bookmarks-url.py --help
```
来重建URL，不要手动拼接查询字符串。
如果标签变更操作存在歧义，先调用
```
GET /labels
```
列出所有标签，再使用确认后的标签ID或标签名称重新执行变更操作。