API Reference

Submit AI tools to MagicBox.Tools programmatically via REST API, CLI, or MCP

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

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

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"
  }'
FieldRequiredDescription
nameyesTool display name (2-100 chars)
urlyesTool website URL
emailnoContact email for review notifications; defaults to your account email
plannobasic (default) / featured / sponsored, see below

Plans

PlanPriceWhat you get
basic$15.9 one-timeStandard listing
featured$19.9 one-timeFeatured badge + priority placement
sponsored$29.9/moSponsor slot (subscription)

Members with an active member subscription and remaining daily quota get queued directly — no payment step. Quota covers basic (member tier) or basic+featured (memberFeature tier); sponsored always requires payment:

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

Everyone else gets their submission saved as unpaid and receives 402 Payment Required with payment links:

{
  "site_id": "xxxxxxxx-...",
  "name": "My Tool",
  "url": "https://mytool.com",
  "status": "pending_payment",
  "is_feature": false,
  "is_sponsor": false,
  "submitted_at": "2026-01-01T00:00:00.000Z",
  "payment_url": "https://magicbox.tools/submit-plan?draft=xxxxxxxx-...&from=api",
  "plan": "basic",
  "checkout_url": "https://checkout.stripe.com/c/pay/...",
  "expires_at": "2026-01-02T00:00:00.000Z",
  "reason": "no_membership"
}

Open either link in a browser to pay:

  • checkout_url — Stripe checkout for the plan you chose; expires in 24 hours.
  • payment_url — never expires; sign in with the same account and pick any plan on the website.

After payment the submission is queued automatically under the same site_id. Unpaid submissions are kept: they show up in GET /api/v1/sites and in My Submissions on the website, and get one reminder email. Re-posting the same URL before paying keeps the same site_id, updates name/email and returns a fresh checkout for the latest plan.

Submission detail

GET /api/v1/sites/{site_id}

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

Returns one of your submissions, including unpaid ones (with payment_url, plus plan/checkout_url/expires_at within 24 hours of submitting). Status flow:

pending_payment → queued → crawling → pending_review → live
                              ↓
                        crawl_failed          rejected
StatusMeaning
pending_paymentWaiting for payment; response includes payment_url (and checkout_url within 24h)
queuedQueued for crawling
crawlingBeing crawled and processed
crawl_failedCrawl failed — contact support
pending_reviewCrawled, waiting for editorial review
livePublished; response includes live_url
rejectedRejected by review

List submissions

GET /api/v1/sites

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

Returns your submissions, newest first. limit is 1-100 (default 100), offset skips that many submissions:

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

Unpaid submissions are included with "status": "pending_payment" and a payment_url.

Errors

All errors share one shape:

{ "error": { "code": "already_submitted", "message": "..." } }
HTTPCodeMeaning
400invalid_request / invalid_jsonValidation failed
401unauthorizedMissing or invalid API key
402—Payment required (not an error — includes checkout_url and payment_url)
404not_foundSubmission not found or not yours
405method_not_allowedWrong method — e.g. POST to /sites instead of /submit-site
409already_submittedThis URL (or a variant: trailing slash, www, tracking params) was already submitted; error.site_id present if it is yours
429rate_limitedSlow down (submit: 10/min, read: 60/min)
500plan_unavailable / checkout_failedPlan misconfigured or Stripe checkout failed — retry later

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_..."
ToolAuthDescription
submit_siteAPI keySubmit a tool (same flow as the REST API)
get_site_statusAPI keyCheck one of your submissions
search_toolsnoneSearch the directory
get_toolnoneGet details of a listed tool

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