API 参考

通过 REST API、CLI 或 MCP 以编程方式向 MagicBox.Tools 提交 AI 工具

MagicBox.Tools 是 agent-native 的:你(或你的 AI agent)可以通过编程方式提交工具、 跟踪审核状态、搜索目录。

认证

在 设置 → API 密钥 创建 API key, 然后以 Bearer token 方式传递:

curl -H "Authorization: Bearer mb_live_..." https://magicbox.tools/api/v1/sites

密钥明文只在创建时显示一次,可随时在同一页面撤销。

提交工具

curl -X POST https://magicbox.tools/api/v1/sites \
  -H "Authorization: Bearer mb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Tool",
    "url": "https://mytool.com",
    "plan": "basic"
  }'
字段必填说明
name是工具展示名称(2-100 字符)
url是工具网站 URL
email否审核通知邮箱,默认使用账户邮箱
plan否basic(默认)/ featured / pro,见下表

套餐

Plan价格权益
basic$15.9 单次标准收录
featured$19.9 单次Featured 标识 + 优先展示
pro$29.9/月Sponsor 赞助位(订阅)

如果你有生效的会员订阅且当日还有额度,提交会直接入队并返回 201:

{
  "site_id": "xxxxxxxx-...",
  "status": "queued",
  "via": "membership",
  "quota": { "used_today": 1, "daily_limit": 1 }
}

否则返回 402 Payment Required 和 Stripe 付款链接:

{
  "site_id": "xxxxxxxx-...",
  "status": "pending_payment",
  "plan": "basic",
  "checkout_url": "https://checkout.stripe.com/c/pay/...",
  "expires_at": "2026-01-02T00:00:00.000Z",
  "reason": "no_membership"
}

在浏览器打开 checkout_url 完成付款后,提交会以同一 site_id 自动入队。 链接 24 小时过期;付款前重复提交同一 URL 会幂等返回同一条记录。

跟踪提交

curl -H "Authorization: Bearer mb_live_..." \
  https://magicbox.tools/api/v1/sites/{site_id}

状态流转:

pending_payment → queued → crawling → pending_review → live
                              ↓
                        crawl_failed          rejected
状态含义
pending_payment等待付款;响应含 checkout_url
queued已入队等待爬取
crawling爬取与处理中
crawl_failed爬取永久失败 — 请联系支持
pending_review已爬取,等待人工审核
live已上线;响应含 live_url
rejected审核未通过

GET /api/v1/sites 返回你最近 100 条提交(未付款的 pending 记录只能通过 GET /api/v1/sites/{site_id} 查询)。

错误

所有错误统一格式:

{ "error": { "code": "already_submitted", "message": "..." } }
HTTPCode含义
400invalid_request / invalid_json参数校验失败
401unauthorizedAPI key 缺失或无效
402—需要付款(非错误 — 响应含 checkout_url)
404not_found提交不存在或不属于你
409already_submittedURL 或名称已存在;若是你的提交,error.site_id 为已有 id
429rate_limited请求过快(提交 10/分钟,查询 60/分钟)

CLI

CLI 尚未发布到 npm,即将上线。当前请使用 REST API 或下方的 MCP server。

npx magicbox-tools-cli login              # 粘贴一次 API key
npx magicbox-tools-cli submit https://mytool.com --name "My Tool" --plan featured --open
npx magicbox-tools-cli status https://mytool.com
npx magicbox-tools-cli list

需要付款时,--open 会自动在浏览器打开付款链接。

MCP Server

将你的 AI agent(Claude Code、Cursor 等)通过 streamable HTTP 连接到 MagicBox MCP server:

claude mcp add --transport http magicbox https://magicbox.tools/api/mcp/mcp \
  --header "Authorization: Bearer mb_live_..."
Tool认证说明
submit_siteAPI key提交工具(与 REST API 同流程)
get_site_statusAPI key查询自己的提交状态
search_tools无需搜索目录
get_tool无需查看已收录工具详情

只读工具不需要 Authorization header — 不带 key 也能搜索目录。