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

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

提交工具

POST /api/v1/submit-site

curl -X POST https://magicbox.tools/api/v1/submit-site \
  -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 / sponsored,见下表

套餐

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

如果你有生效的会员订阅且当日还有额度, 提交会直接入队,无需付款。额度覆盖 basic(member 档)或 basic+featured (memberFeature 档);sponsored 一律需要付费:

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

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

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

在浏览器打开 checkout_url 完成付款后,提交会以同一 site_id 自动入队。 链接 24 小时过期;付款前重复提交同一 URL 会以最新的 plan/name/email 覆盖旧提交, 生成新的付款链接。

提交详情

GET /api/v1/sites/{site_id}

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

返回你的单条提交,包括未付款的 pending 记录(附可付款的 checkout_url)。状态流转:

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

curl -H "Authorization: Bearer mb_live_..." \
  "https://magicbox.tools/api/v1/sites?limit=20&offset=0"

返回你的提交(新的在前)。limit 取 1-100(默认 100),offset 跳过指定条数:

{
  "sites": [
    {
      "site_id": "xxxxxxxx-...",
      "name": "My Tool",
      "url": "https://mytool.com",
      "status": "live",
      "is_feature": true,
      "is_sponsor": false,
      "submitted_at": "2026-01-01 00:00:00+00",
      "live_url": "https://magicbox.tools/ai/my-tool"
    }
  ],
  "total": 137,
  "limit": 20,
  "offset": 0
}

未付款的 pending 记录不在列表中 — 请通过 GET /api/v1/sites/{site_id} 单独查询。

错误

所有错误统一格式:

{ "error": { "code": "already_submitted", "message": "..." } }
HTTPCode含义
400invalid_request / invalid_json参数校验失败
401unauthorizedAPI key 缺失或无效
402—需要付款(非错误 — 响应含 checkout_url)
404not_found提交不存在或不属于你
405method_not_allowed请求方式错误 — 如向 /sites POST(应使用 /submit-site)
409already_submittedURL 或名称已存在;若是你的提交,error.site_id 为已有 id
429rate_limited请求过快(提交 10/分钟,查询 60/分钟)
500plan_unavailable / checkout_failed套餐配置异常或 Stripe checkout 创建失败 — 请稍后重试

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 也能搜索目录。