{"openapi":"3.1.0","info":{"title":"Rummage by Zoey Prompts","version":"1.0.0","summary":"Search API built for AI agents.","description":"Rummage by Zoey Prompts rents the index and does the librarian work: web search piped through embeddings, a cross-encoder rerank, and quality signals — so every result arrives tagged with *why* it ranked and your agent can decide what to trust.\n\nStart at POST /v1/keys for a free key (500 searches/month, no card). Cache hits are free and never touch quota. Deep searches query both indexes and cost 2 quota units; everything else costs 1.\n\nAgents can also use Rummage natively over MCP: POST /mcp (Streamable HTTP, JSON-RPC 2.0) with tools `search` and `extract`.","contact":{"name":"That's Life Media","url":"https://zoeyprompts.com"},"license":{"name":"API Terms — see provider","url":"https://zoeyprompts.com/terms"}},"servers":[{"url":"https://ai-search-api.gamebox-cloud-staging.workers.dev","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Keys","description":"Self-serve API key signup."},{"name":"Search","description":"The librarian pipeline: search, rerank, signals."},{"name":"Extract","description":"Clean page text from URLs."},{"name":"Usage","description":"Quota and billing status."},{"name":"Billing","description":"Paid plans via Square checkout."},{"name":"System","description":"Health checks."}],"externalDocs":{"description":"Human-readable docs with quickstart and a signal glossary","url":"https://ai-search-api.gamebox-cloud-staging.workers.dev/docs"},"paths":{"/v1/keys":{"post":{"tags":["Keys"],"operationId":"signup","summary":"Get an API key (free, self-serve, no card)","description":"Public signup. One active key per email — signing up again rotates (revokes the old key, issues a new one), which doubles as 'I lost my key'. The key is shown ONCE and never stored in plaintext. Free tier: 100 searches/month. Limited to 3 signups per IP per 24h.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","examples":["you@example.com"]},"name":{"type":"string","maxLength":60,"description":"Optional label for the key."}}}}}},"responses":{"200":{"description":"Your new API key (shown once — save it now)","content":{"application/json":{"schema":{"type":"object","required":["key","key_id","quota_monthly"],"properties":{"key":{"type":"string","description":"Send as: Authorization: Bearer <key>","examples":["aisk_…"]},"key_id":{"type":"string","examples":["key_9f2ab41c0e77d3f1"]},"quota_monthly":{"type":"integer","examples":[500]},"rotated":{"type":"boolean","description":"True if a previous key for this email was revoked."},"message":{"type":"string"}}}}}},"400":{"description":"Bad request — invalid JSON or parameters.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"403":{"description":"Forbidden — e.g. a Pro+-only feature on a free key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"429":{"description":"Rate limited or monthly quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}}}}},"/v1/search":{"post":{"tags":["Search"],"operationId":"search","summary":"Search the web, reranked for AI consumers","description":"Runs the query against web indexes, then reranks with embeddings + a cross-encoder, and tags every result with quality signals (source type, authority, title match, freshness, demotions). Set depth to 'deep' for both indexes merged (costs 2 quota units). Set compact to true for token-efficient results (short snippets, signals dropped).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","maxLength":500,"examples":["how do vector databases handle hybrid search?"]},"max_results":{"type":"integer","minimum":1,"maximum":10,"default":8},"rewrite":{"type":"boolean","default":false,"description":"Let the model rewrite your query for better retrieval before searching."},"include_content":{"type":"boolean","default":false,"description":"Fetch and attach full cleaned page text per result."},"depth":{"type":"string","enum":["quick","deep"],"default":"quick","description":"quick: single index, 1 quota unit. deep: both indexes merged, 2 quota units — for research-grade queries."},"compact":{"type":"boolean","default":false,"description":"Trim snippets to ~150 chars at a sentence boundary and drop signals — minimal tokens for feeding results straight into an LLM."}}}}}},"responses":{"200":{"description":"Ranked results with signals","content":{"application/json":{"schema":{"type":"object","required":["query","results"],"properties":{"query":{"type":"string"},"search_query":{"type":"string","description":"The rewritten query, when rewrite=true changed it. Absent otherwise."},"upstream":{"type":"string","description":"tavily, brave, or both (deep).","examples":["tavily"]},"rerank":{"type":"string","enum":["cross-encoder","embedding","upstream"],"description":"Which rerank stage produced the order."},"extract_upstream":{"type":"string","description":"Present when include_content=true."},"cached":{"type":"boolean","description":"True when served from cache — free, no quota consumed."},"mock":{"type":"boolean","description":"True only if upstream is in mock mode."},"results":{"type":"array","items":{"type":"object","required":["title","url","snippet","relevance","signals"],"properties":{"title":{"type":"string","examples":["CORS · Cloudflare One docs"]},"url":{"type":"string","format":"uri","examples":["https://developers.cloudflare.com/cloudflare-one/"]},"snippet":{"type":"string","description":"Cleaned snippet — markup stripped. In compact mode, truncated at a sentence boundary (~150 chars)."},"relevance":{"type":"number","minimum":0,"maximum":1,"description":"Blended relevance after cross-encoder rerank + signal adjustments. Relative within the result set — treat 0.92 vs 0.87 as a nudge, not a landslide.","examples":[0.87]},"published_date":{"type":"string","description":"ISO date when the upstream provided one.","examples":["2026-10-20"]},"content":{"type":"string","description":"Full extracted page text. Present only when include_content=true."},"signals":{"type":"array","items":{"type":"string"},"description":"Why this result ranked, as plain tags. Always includes a source:* tag (docs, news, forum, code, video, reference, web). Others: authority:official-docs, authority:trusted-tld, authority:entity-match, match:title, match:title-strong, freshness:recent, freshness:stale, intent:troubleshooting-source, demoted:social-noise.","examples":[["source:docs","authority:official-docs","match:title-strong"]]}}}}}}}}},"400":{"description":"Bad request — invalid JSON or parameters.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"403":{"description":"Forbidden — e.g. a Pro+-only feature on a free key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"429":{"description":"Rate limited or monthly quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}}}}},"/v1/extract":{"post":{"tags":["Extract"],"operationId":"extract","summary":"Extract clean page text from URLs","description":"Returns readable text from up to 5 URLs — no nav bars, cookie banners, or ad slots. Each URL costs 1 extract unit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":5,"examples":[["https://example.com/article"]]}}}}}},"responses":{"200":{"description":"Extracted page contents","content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"type":"object","required":["url","content"],"properties":{"url":{"type":"string","format":"uri"},"content":{"type":"string","description":"Cleaned page text (empty string if extraction failed for that URL)."}}}},"upstream":{"type":"string","examples":["tavily"]},"mock":{"type":"boolean"}}}}}},"400":{"description":"Bad request — invalid JSON or parameters.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"403":{"description":"Forbidden — e.g. a Pro+-only feature on a free key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"429":{"description":"Rate limited or monthly quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}}}}},"/v1/usage":{"get":{"tags":["Usage"],"operationId":"usage","summary":"This month's usage against your quota","responses":{"200":{"description":"Usage stats","content":{"application/json":{"schema":{"type":"object","required":["key_id","month","searches_used","quota_monthly","plan"],"properties":{"key_id":{"type":"string"},"name":{"type":"string"},"month":{"type":"string","examples":["2026-10"]},"searches_used":{"type":"integer"},"extracts_used":{"type":"integer"},"quota_monthly":{"type":"integer","description":"Effective quota — plan quota when a plan is active, else the key's quota."},"plan":{"type":"string","enum":["free","pro","scale"],"examples":["free"]},"plan_expires_at":{"type":"integer","description":"Epoch ms, or null.","examples":[null]}}}}}},"400":{"description":"Bad request — invalid JSON or parameters.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"403":{"description":"Forbidden — e.g. a Pro+-only feature on a free key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"429":{"description":"Rate limited or monthly quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}}}}},"/v1/billing/checkout":{"post":{"tags":["Billing"],"operationId":"billing_checkout","summary":"Get a Square checkout link for a paid plan","description":"Creates a Square-hosted payment link for a 30-day plan. The new quota applies the moment payment completes; renewals extend from whichever is later — now, or the current expiry.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","enum":["pro","scale"],"description":"pro: $25/30 days, 5,000 searches/mo. scale: $120/30 days, 30,000 searches/mo."}}}}}},"responses":{"200":{"description":"Checkout link","content":{"application/json":{"schema":{"type":"object","required":["checkout_url","plan","price_cents","quota_monthly","days"],"properties":{"checkout_url":{"type":"string","format":"uri"},"plan":{"type":"string","examples":["pro"]},"price_cents":{"type":"integer","examples":[2000]},"quota_monthly":{"type":"integer","examples":[5000]},"days":{"type":"integer","examples":[30]}}}}}},"400":{"description":"Bad request — invalid JSON or parameters.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"403":{"description":"Forbidden — e.g. a Pro+-only feature on a free key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"429":{"description":"Rate limited or monthly quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}}}}},"/v1/billing/status":{"get":{"tags":["Billing"],"operationId":"billing_status","summary":"Current plan, quota, renewal, and plan catalog","responses":{"200":{"description":"Billing status","content":{"application/json":{"schema":{"type":"object","required":["plan","plan_active","quota_monthly","plans"],"properties":{"plan":{"type":"string","examples":["pro"]},"plan_active":{"type":"boolean"},"plan_expires_at":{"type":"integer","description":"Epoch ms, or null.","examples":[null]},"quota_monthly":{"type":"integer"},"plans":{"type":"object","description":"Available paid plans.","additionalProperties":{"type":"object","properties":{"name":{"type":"string","examples":["Rummage Pro — 5,000 searches/mo"]},"price_cents":{"type":"integer","examples":[2000]},"quota":{"type":"integer","examples":[5000]},"days":{"type":"integer","examples":[30]}}}}}}}}},"400":{"description":"Bad request — invalid JSON or parameters.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"403":{"description":"Forbidden — e.g. a Pro+-only feature on a free key.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}},"429":{"description":"Rate limited or monthly quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}}}}}}}},"/v1/health":{"get":{"tags":["System"],"operationId":"health","summary":"Service health (no auth)","security":[],"responses":{"200":{"description":"Health status","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","examples":[true]},"mock_upstream":{"type":"boolean"},"time":{"type":"string","format":"date-time"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (aisk_…)"}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Machine-readable code: bad_request, unauthorized, quota_exceeded, rate_limited, not_found, internal_error.","examples":["quota_exceeded"]},"message":{"type":"string","examples":["Monthly quota exceeded. Upgrade at POST /v1/billing/checkout."]}}},"SearchResult":{"type":"object","required":["title","url","snippet","relevance","signals"],"properties":{"title":{"type":"string","examples":["CORS · Cloudflare One docs"]},"url":{"type":"string","format":"uri","examples":["https://developers.cloudflare.com/cloudflare-one/"]},"snippet":{"type":"string","description":"Cleaned snippet — markup stripped. In compact mode, truncated at a sentence boundary (~150 chars)."},"relevance":{"type":"number","minimum":0,"maximum":1,"description":"Blended relevance after cross-encoder rerank + signal adjustments. Relative within the result set — treat 0.92 vs 0.87 as a nudge, not a landslide.","examples":[0.87]},"published_date":{"type":"string","description":"ISO date when the upstream provided one.","examples":["2026-10-20"]},"content":{"type":"string","description":"Full extracted page text. Present only when include_content=true."},"signals":{"type":"array","items":{"type":"string"},"description":"Why this result ranked, as plain tags. Always includes a source:* tag (docs, news, forum, code, video, reference, web). Others: authority:official-docs, authority:trusted-tld, authority:entity-match, match:title, match:title-strong, freshness:recent, freshness:stale, intent:troubleshooting-source, demoted:social-noise.","examples":[["source:docs","authority:official-docs","match:title-strong"]]}}}}}}