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

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

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` / `sponsored`, see below

Plans

Plan	Price	What you get
`basic`	$15.9 one-time	Standard listing
`featured`	$19.9 one-time	Featured badge + priority placement
`sponsored`	$29.9/mo	Sponsor 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 receives 402 Payment Required with a Stripe checkout link:

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

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 before paying replaces the pending submission with a fresh checkout using your latest plan/name/email.

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 pending ones (with the checkout_url to pay). 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 — contact support
`pending_review`	Crawled, waiting for editorial review
`live`	Published; response includes `live_url`
`rejected`	Rejected 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 pending submissions are not included — query them individually 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
405	`method_not_allowed`	Wrong method — e.g. POST to `/sites` instead of `/submit-site`
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)
500	`plan_unavailable` / `checkout_failed`	Plan 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_..."

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.

Free AI Anime & Manga Generator