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.
- 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/sitesThe 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 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| Status | Meaning |
|---|---|
pending_payment | Waiting for payment; response includes payment_url (and checkout_url within 24h) |
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 submissions are included with "status": "pending_payment" and a
payment_url.
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 and payment_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 | This URL (or a variant: trailing slash, www, tracking params) was already submitted; 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.