Endpoint
可用的 HTTP 方法和请求/响应示例
Base URL：https://api.skilltweet.com/api/v1。带 🔑 的端点需要 Creator API Key。
1. 创建创作者账号
POST /api/v1/creators
{
"handle": "your_handle",
"name": "Your Name",
"email": "you@example.com"
}
→ { "data": { "handle": "your_handle", "name": "Your Name", "email": "you@example.com", "created_at": "..." },
"meta": { "api_key": "sk_live_...", "note": "Save this key. It is shown once." } }
# key 只返回一次，保存在 SkillTweet CLI config 中。
2. 发布一个 Skill 🔑
POST /api/v1/listings
Authorization: Bearer $SKILLTWEET_API_KEY
Content-Type: application/json
{
"name": "Auto-Reply Safe",
"tagline": "Safety-checked reply drafts, human-approved before posting.",
"tags": ["Auto-Reply", "Safety"],
"price_usd": 9,
"api_calls_included": 10000,
"api_credit_usd": 0,
"skill_md": "---\nname: Auto-Reply Safe\ndescription: ...\n---\n# Auto-Reply Safe\n\n..."
}
→ { "data": { "id": "lst_...", "slug": "auto-reply-safe", ... },
"meta": { "request_id": "..." } }
3. 浏览所有 Skill
GET /api/v1/listings?tag=Auto-Reply&sort=top&limit=20
# 查询参数：tag / category / q / status(published|draft|all) / sort(new|top|selling) / limit(<=200)
→ { "data": [
{
"id": "lst_...",
"slug": "auto-reply-safe",
"name": "Auto-Reply Safe",
"tagline": "...",
"tags": ["Auto-Reply", "Safety"],
"price_usd": 9,
"api_calls_included": 10000,
"upvotes": 1,
"sales": 0,
"downloads": 0
},
...
],
"meta": { "count": 20, "request_id": "..." } }
4. 买一个 Skill (赠送 API Key)
POST /api/v1/purchases
Content-Type: application/json
{
"listing_id": "lst_...",
"buyer_email": "buyer@example.com"
}
→ { "data": {
"purchase_id": "pur_...",
"listing_id": "lst_...",
"listing_name": "Auto-Reply Safe",
"price_paid_usd": 9,
"platform_fee_usd": 0.9,
"creator_share_usd": 8.1,
"api_calls_included": 10000,
"entitlement": {
"api_key": "at_skill_...",
"calls_included": 10000,
"balance_usd": 0.9
},
"money_split": {
"clawmart_would_have_paid_creator_usd": 7.2,
"skilltweet_paid_creator_usd": 8.1,
"extra_to_creator_usd": 0.9
}
},
"meta": { "request_id": "..." } }
5. 创作者控制台 🔑
GET /api/v1/creators/your_handle/payouts
Authorization: Bearer $SKILLTWEET_API_KEY
→ { "data": {
"handle": "your_handle",
"lifetime": {
"sales": 1,
"one_time_earnings_usd": 8.1,
"api_royalty_usd": 0.27,
"total_usd": 8.37
},
"per_listing": [
{
"id": "lst_...",
"slug": "auto-reply-safe",
"sales": 1,
"one_time_earnings_usd": 8.1,
"api_royalty_usd": 0.27
}
],
"rates": {
"platform_fee_rate": 0.1,
"competitor_fee_rate": 0.2,
"api_royalty_rate": 0.3,
"api_price_per_1k_usd": 0.09
}
},
"meta": { "request_id": "..." } }
6. 其余端点
GET /api/v1/health # 服务状态
GET /api/v1/money # 费率 + 收益算例（站点和 CLI 共用同一份数字）
GET /api/v1/listings/:idOrSlug # 单个 Skill 详情
PATCH /api/v1/listings/:id 🔑 # 更新自己的 Skill
DELETE /api/v1/listings/:id 🔑 # 下架自己的 Skill
POST /api/v1/listings/:id/upvote # upvote
POST /api/v1/listings/:id/versions 🔑 # 发布新版本（买家自动更新，不重复收费）
GET /api/v1/creators/:handle # 创作者主页 + 公开数据
POST /api/v1/_reset # 仅本地开发：清空演示数据
哪些端点要 key。 只有创建/修改/下架自己的 Skill、发布新版本、读取自己的 payouts 需要 Authorization: Bearer sk_live_...（也接受 X-API-KEY）。浏览、详情、upvote、购买、创建账号都是公开的。
Money 拆分。 平台抽 10%，创作者拿 90%；买家后续的 API 调用收入，创作者再拿 30%。所有金额都是 USD，保留 2 位小数。
错误格式。 失败时返回 { "error": { "code": "...", "message": "..." }, "request_id": "..." }，HTTP 状态码：400 参数错误、401 未鉴权、404 不存在、409 冲突、405 方法不允许。
存储。 本地开发用 JSON 文件（api/store.js，数据落在 .data/listings.json），因为一个 curl 就能上架是硬需求，需要 Postgres 的商店不是这个产品。换成 D1 只需要替换这一个模块——每个函数都是 async，返回普通对象。