{"openapi":"3.1.0","info":{"title":"MagicBox.Tools API","version":"1.0.0","description":"Agent-native API for submitting AI tools to the MagicBox.Tools directory and tracking submission status. Create an API key at /settings/api-keys."},"servers":[{"url":"https://magicbox.tools/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/sites":{"post":{"operationId":"submitSite","summary":"Submit a tool to the directory","description":"Members with remaining daily quota get queued directly (201). Otherwise returns 402 with a Stripe checkout_url — open it in a browser to pay; after payment the submission is queued automatically and the same site_id becomes trackable.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitRequest"}}}},"responses":{"201":{"description":"Queued via membership quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitQueued"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Payment required. Open checkout_url in a browser to complete the submission. Re-posting the same URL returns the same pending record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitPendingPayment"}}}},"409":{"description":"This URL or name has already been submitted. If it is yours, error.site_id contains the existing id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"operationId":"listSites","summary":"List your submissions","description":"Returns up to 100 of your submissions, newest first. Pending (unpaid) submissions are not included — query them by id.","responses":{"200":{"description":"Your submissions","content":{"application/json":{"schema":{"type":"object","properties":{"sites":{"type":"array","items":{"$ref":"#/components/schemas/Site"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sites/{siteId}":{"get":{"operationId":"getSite","summary":"Get one submission status","description":"Looks up the site table first, then unpaid pending submissions. Only returns your own submissions.","parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Submission found. status=pending_payment includes checkout_url.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Site"},{"$ref":"#/components/schemas/SubmitPendingPayment"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No submission found with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key in the format mb_live_... Create one at /settings/api-keys."}},"responses":{"BadRequest":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"SubmitRequest":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string","minLength":2,"maxLength":100,"description":"Tool display name"},"url":{"type":"string","format":"uri"},"email":{"type":"string","format":"email","description":"Contact email for review notifications. Defaults to your account email."},"plan":{"type":"string","enum":["basic","featured","pro"],"default":"basic","description":"basic $15.9 one-time; featured $19.9 one-time (featured badge); pro $29.9/mo subscription (sponsor slot). Member subscriptions cover basic (and featured for memberFeature tier) within daily quota."}}},"SubmitQueued":{"type":"object","properties":{"site_id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"queued"},"via":{"type":"string","const":"membership"},"quota":{"type":"object","properties":{"used_today":{"type":"integer"},"daily_limit":{"type":"integer"}}}}},"SubmitPendingPayment":{"type":"object","properties":{"site_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"url":{"type":"string"},"status":{"type":"string","const":"pending_payment"},"plan":{"type":"string","enum":["basic","featured","pro"]},"checkout_url":{"type":"string","format":"uri","description":"Stripe checkout link. Open in a browser to pay; expires in 24h."},"expires_at":{"type":"string","format":"date-time"},"submitted_at":{"type":"string","format":"date-time"},"reason":{"type":"string","enum":["no_membership","quota_exceeded","plan_not_covered","payment_pending"]}}},"Site":{"type":"object","properties":{"site_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"url":{"type":"string"},"status":{"type":"string","enum":["queued","crawling","crawl_failed","pending_review","live","rejected"],"description":"queued → crawling → pending_review → live. crawl_failed and rejected are terminal."},"is_feature":{"type":"boolean"},"is_sponsor":{"type":"boolean"},"submitted_at":{"type":"string"},"live_url":{"type":"string","description":"Public tool page, present when status=live"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"site_id":{"type":"string","description":"On 409: the existing submission id (only when it belongs to you)"}}}}}}}}