API Reference

MagicBox.Tools is agent-native: you (or your AI agent) can submit tools, track submission status, and search the directory programmatically.

Base URL: https://magicbox.tools/api/v1
OpenAPI spec: /api/v1/openapi.json
llms.txt: /llms.txt

Authentication

Create an API key at Settings → API Keys, then pass it as a Bearer token:

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

The key is shown only once at creation time. Keys can be revoked anytime from the same page.

Submit a tool

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"
  }'

Field	Required	Description
`name`	yes	Tool display name (2-100 chars)
`url`	yes	Tool website URL
`email`	no	Contact email for review notifications; defaults to your account email
`plan`	no	`basic` (default) / `featured` / `pro`, see below

Plans

Plan	Price	What you get
`basic`	$15.9 one-time	Standard listing
`featured`	$19.9 one-time	Featured badge + priority placement
`pro`	$29.9/mo	Sponsor slot (subscription)

If you have an active member subscription with remaining daily quota, the submission is queued directly and returns 201:

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

Otherwise the API returns 402 Payment Required with a Stripe checkout link:

{
  "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"
}

Open checkout_url in a browser to pay. After payment the submission is queued automatically under the same site_id. The link expires in 24 hours; re-posting the same URL returns the same pending record (idempotent).

Track a submission

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

Status flow:

pending_payment → queued → crawling → pending_review → live
                              ↓
                        crawl_failed          rejected

Status	Meaning
`pending_payment`	Waiting for payment; response includes `checkout_url`
`queued`	Queued for crawling
`crawling`	Being crawled and processed
`crawl_failed`	Crawl failed permanently — contact support
`pending_review`	Crawled, waiting for editorial review
`live`	Published; response includes `live_url`
`rejected`	Rejected by review

GET /api/v1/sites lists up to 100 of your submissions (unpaid pending submissions are only visible via GET /api/v1/sites/{site_id}).

Errors

All errors share one shape:

{ "error": { "code": "already_submitted", "message": "..." } }

HTTP	Code	Meaning
400	`invalid_request` / `invalid_json`	Validation failed
401	`unauthorized`	Missing or invalid API key
402	—	Payment required (not an error — includes `checkout_url`)
404	`not_found`	Submission not found or not yours
409	`already_submitted`	URL or name already exists; `error.site_id` present if it is yours
429	`rate_limited`	Slow down (submit: 10/min, read: 60/min)

CLI

The CLI is not yet published to npm — coming soon. Use the REST API or MCP server below in the meantime.

npx magicbox-tools-cli login              # paste your API key once
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 opens the checkout link in your browser automatically when payment is required.

MCP Server

Connect your AI agent (Claude Code, Cursor, etc.) to the MagicBox MCP server over streamable HTTP:

claude mcp add --transport http magicbox https://magicbox.tools/api/mcp/mcp \
  --header "Authorization: Bearer mb_live_..."

Tool	Auth	Description
`submit_site`	API key	Submit a tool (same flow as the REST API)
`get_site_status`	API key	Check one of your submissions
`search_tools`	none	Search the directory
`get_tool`	none	Get details of a listed tool

The Authorization header is optional for read-only tools — without it your agent can still search the directory.