{"openapi":"3.1.0","info":{"title":"BoxFetch Agent MCP","version":"0.1","summary":"Public agent-commerce API contract for BoxFetch. Purchases settle in internal BoxFetch credits (spend-only, not cash, not buyer-redeemable) and require a human BoxFetch account with credits and approval policy. Not an official Claude or ChatGPT listed connector. Seller external payout and buyer cash-out are not live.","description":"This OpenAPI document describes the stable, public, agent-facing BoxFetch MCP surface: the MCP endpoint plus discovery, manifest, OpenAPI, llms.txt, and the public marketplace showcase. Session-gated dashboard, admin, and seller routes are intentionally not described here.","contact":{"name":"BoxFetch MCP","url":"https://app.boxfetch.ai/boxfetch/agent-setup"},"x-status":{"settlementModel":"internal_boxfetch_credits","creditsAreCash":false,"creditsBuyerRedeemable":false,"buyerTopupRail":"stripe_checkout","buyerCreditsSpendOnly":true,"sellerExternalPayoutEnabled":false,"officialConnectorListed":false,"publicMediaDiscoveryEnabled":false}},"servers":[{"url":"https://app.boxfetch.ai","description":"Request origin"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"OAuth access token issued to the MCP client after discovery, dynamic registration, human consent, and PKCE. A pre-issued per-agent bearer exists only as an operator/development fallback. Purchases settle in internal BoxFetch credits."}},"schemas":{"Error":{"type":"object","required":["error","reasonCodes"],"additionalProperties":true,"properties":{"error":{"type":"string","description":"Stable machine-readable error code.","enum":["missing_authorization","malformed_authorization","malformed_token","invalid_signature","expired_token","token_not_registered","token_revoked","invalid_request","invalid_json","request_body_too_large","unknown_tool","missing_asset_id","missing_media_asset_id","missing_agent_id","missing_quoted_price","invalid_quoted_price","missing_idempotency_key","missing_purchase_id","missing_approval_request_id","idempotency_conflict","insufficient_credits","price_changed","native_settlement_failed","rate_limited","asset_unavailable","agent_not_found","agent_not_active","preview_not_allowed","purchase_not_allowed","content_not_found","not_entitled","mcp_tool_failed"]},"reasonCodes":{"type":"array","items":{"type":"string"},"description":"Secondary stable reason codes used by validation, auth, permission, idempotency, and rate-limit failures."},"retryAfterSeconds":{"type":"integer","minimum":0,"description":"Present on rate_limited errors. Number of seconds to wait before retrying."},"details":{"type":"object","additionalProperties":true}}},"JsonRpcError":{"type":"object","required":["jsonrpc","id","error"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"number"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":false,"properties":{"reasonCodes":{"type":"array","items":{"type":"string"}},"retryAfterSeconds":{"type":"number"},"details":{"type":"object","additionalProperties":true}}}}}}},"JsonRpcSuccess":{"type":"object","required":["jsonrpc","id","result"],"additionalProperties":false,"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"result":{"type":"object","additionalProperties":true,"description":"JSON-RPC result object. For tools/call, result may contain content: [{ type: \"text\", text: string }], structuredContent: object, and isError: boolean.","properties":{"content":{"type":"array","items":{"type":"object","required":["type","text"],"additionalProperties":false,"properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}}}},"structuredContent":{"type":"object","additionalProperties":true},"isError":{"type":"boolean"}}}}},"SearchAssetsInput":{"type":"object","additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":25,"default":12},"offset":{"type":"integer","minimum":0,"maximum":500,"description":"Zero-based offset for filtered search."},"query":{"type":"string","maxLength":200,"description":"Free-text problem or outcome."},"category":{"type":"string","maxLength":80},"contentKind":{"type":"string","maxLength":40},"free":{"type":"boolean","description":"Restrict to zero-price listings."},"maxPriceCredits":{"type":"string","pattern":"^\\d+$","description":"Inclusive maximum price in credits."},"licenseType":{"type":"string","maxLength":80},"trust":{"type":"string","enum":["verified"],"description":"Restrict to listings BoxFetch reports as verified."},"seller":{"type":"string","maxLength":120,"description":"Public seller display name filter."}}},"SearchAssetsOutput":{"type":"object","required":["assets","limit","returned","truncated"],"additionalProperties":true,"properties":{"assets":{"type":"array","items":{"type":"object","required":["assetId","title","kind","priceMicrousd"],"additionalProperties":true,"properties":{"assetId":{"type":"string","description":"Public asset identifier."},"title":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","description":"High-level content category (e.g. markdown, container)."},"category":{"type":"string"},"priceMicrousd":{"type":"string","pattern":"^\\d+$","description":"Current listed price in microUSD as a decimal string."},"sellerTrustScore":{"type":"number","minimum":0,"maximum":1},"listedAt":{"type":"string","format":"date-time"},"trustWorksBadge":{"type":"string","enum":["unverified","basic_checked","verified"],"description":"Public-safe Trust Works badge. Values: unverified, basic_checked, verified."},"trustWorksPublicLabel":{"type":"string","enum":["Unverified","Basic checked","Monaith verified"],"description":"Short public label for the asset's Trust Works status. This is not legal/IP certification."},"trustWorksVerificationTier":{"type":"string","enum":["unverified","basic","enhanced"],"description":"Public verification tier. v0 usually returns unverified or basic; enhanced is reserved for future founder/admin verification."},"trustWorksCheckedAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the latest Trust Works assessment if available."},"discoveryMode":{"type":"string","enum":["standard","limited"],"description":"Public-safe discovery mode. Limited means the asset is discoverable but constrained by Trust Works routing."},"discoveryLabel":{"type":"string","enum":["Standard discovery","Limited discovery"],"description":"Short public discovery label."},"discoveryMessage":{"type":["string","null"],"description":"Public-safe explanation of limited discovery, if applicable."}}}},"limit":{"type":"integer","minimum":1,"maximum":25},"returned":{"type":"integer","minimum":0},"truncated":{"type":"boolean"}}},"PreviewAssetInput":{"type":"object","required":["assetId"],"additionalProperties":false,"properties":{"assetId":{"type":"string"}}},"PreviewAssetOutput":{"type":"object","required":["assetId","title","previewText"],"additionalProperties":true,"properties":{"assetId":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"previewText":{"type":"string","description":"Buyer-safe excerpt only — never full content."},"contentKind":{"type":"string","description":"markdown | container"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0},"sha256":{"type":"string"},"sellerTrustScore":{"type":"number","minimum":0,"maximum":1},"priceMicrousd":{"type":"string","pattern":"^\\d+$"},"trustWorksBadge":{"type":"string","enum":["unverified","basic_checked","verified"],"description":"Public-safe Trust Works badge. Values: unverified, basic_checked, verified."},"trustWorksPublicLabel":{"type":"string","enum":["Unverified","Basic checked","Monaith verified"],"description":"Short public label for the asset's Trust Works status. This is not legal/IP certification."},"trustWorksVerificationTier":{"type":"string","enum":["unverified","basic","enhanced"],"description":"Public verification tier. v0 usually returns unverified or basic; enhanced is reserved for future founder/admin verification."},"trustWorksCheckedAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the latest Trust Works assessment if available."},"discoveryMode":{"type":"string","enum":["standard","limited"],"description":"Public-safe discovery mode. Limited means the asset is discoverable but constrained by Trust Works routing."},"discoveryLabel":{"type":"string","enum":["Standard discovery","Limited discovery"],"description":"Short public discovery label."},"discoveryMessage":{"type":["string","null"],"description":"Public-safe explanation of limited discovery, if applicable."}}},"QuoteAssetInput":{"type":"object","required":["assetId"],"additionalProperties":false,"properties":{"assetId":{"type":"string"}}},"QuoteAssetOutput":{"type":"object","required":["assetId","quotedPriceMicrousd","expiresAt"],"additionalProperties":true,"properties":{"assetId":{"type":"string"},"quoteId":{"type":"string","description":"Durable single-use quote id; pass to purchase_asset."},"quotedPriceMicrousd":{"type":"string","pattern":"^\\d+$"},"priceCredits":{"type":"string","pattern":"^\\d+$"},"currency":{"type":"string","default":"USD"},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"requiresApproval":{"type":"boolean"},"freshnessSeconds":{"type":"integer","minimum":0}}},"PurchaseAssetInput":{"type":"object","required":["idempotencyKey"],"additionalProperties":false,"properties":{"quoteId":{"type":"string","description":"Durable single-use quote id from quote_asset. Preferred; content- and price-bound at capture."},"assetId":{"type":"string","description":"Legacy path: required with quotedPriceMicrousd when no quoteId is given."},"quotedPriceMicrousd":{"type":"string","pattern":"^\\d+$","description":"Legacy path: required with assetId when no quoteId is given."},"userTask":{"type":"string","maxLength":300,"description":"Optional bounded, inert plain-text purpose surfaced in the human approval card."},"intendedUse":{"type":"string","maxLength":300,"description":"Optional bounded, inert plain-text intended use surfaced in the human approval card."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"description":"Required idempotency key. Also accepted as Idempotency-Key header."}}},"PurchaseAssetOutput":{"type":"object","additionalProperties":true,"properties":{"ok":{"type":"boolean"},"purchaseId":{"type":"string"},"quoteId":{"type":"string"},"approvalRequired":{"type":"boolean"},"approvalRequestId":{"type":"string"},"contentUrl":{"type":"string","description":"Legacy session route pointer. MCP agents should use get_asset_content with assetId and purchaseId."},"agentDownloadUrl":{"type":"string","description":"Bearer-authenticated MCP container download URL. Present only for captured container purchases; bytes are never returned inline."},"agentContainerRetrievalSupported":{"type":"boolean","description":"True when the container can be retrieved through agentDownloadUrl after entitlement."},"contentKind":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0},"sha256":{"type":"string"},"fullContentDemo":{"type":"string","description":"Legacy demo assets only. Markdown-backed assets use get_asset_content."}}},"GetPurchaseApprovalInput":{"type":"object","required":["approvalRequestId"],"additionalProperties":false,"properties":{"approvalRequestId":{"type":"string"}}},"GetPurchaseApprovalOutput":{"type":"object","required":["status"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["pending","declined","expired","captured"]},"purchaseId":{"type":"string"},"contentUrl":{"type":"string","description":"Legacy session route pointer. MCP agents should use get_asset_content with assetId and purchaseId."},"agentDownloadUrl":{"type":"string","description":"Bearer-authenticated MCP container download URL. Present only for captured container purchases; bytes are never returned inline."},"agentContainerRetrievalSupported":{"type":"boolean"},"contentKind":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0},"sha256":{"type":"string"},"fullContentDemo":{"type":"string"}}},"GetAssetContentInput":{"type":"object","required":["assetId"],"additionalProperties":false,"properties":{"assetId":{"type":"string"},"purchaseId":{"type":"string","description":"Optional. Narrows retrieval to one captured purchase; entitlement alone is otherwise sufficient."}}},"GetAssetContentOutput":{"type":"object","required":["ok","assetId","contentKind"],"additionalProperties":true,"properties":{"ok":{"type":"boolean"},"assetId":{"type":"string"},"contentKind":{"type":"string","description":"markdown for text assets; seller-declared kind for containers such as pdf, zip, image, or dataset."},"mimeType":{"type":"string"},"title":{"type":"string"},"markdown":{"type":"string","description":"Present for contentKind=markdown."},"fileName":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0},"sha256":{"type":"string"},"storageKind":{"type":"string"},"sellerDeclared":{"type":"boolean"},"notParsedOrScanned":{"type":"boolean"},"agentContainerRetrievalSupported":{"type":"boolean","description":"True for entitled container assets. Use agentDownloadUrl to retrieve bytes with the same bearer token."},"agentDownloadUrl":{"type":"string","description":"Bearer-authenticated MCP container download URL. Present for entitled container assets; get_asset_content returns metadata rather than bytes."},"usageInstructions":{"type":["string","null"],"description":"Seller-supplied guidance for how an entitled buyer or AI agent should use the unlocked container. Present only after purchase or entitlement; never returned in public preview or showcase output."}}},"BoxfetchMediaQuoteInput":{"type":"object","required":["mediaAssetId"],"additionalProperties":false,"properties":{"mediaAssetId":{"type":"string"}}},"BoxfetchMediaQuoteOutput":{"type":"object","required":["ok","mediaAssetId","purchaseEligible","alreadyEntitled","purchaseMode"],"additionalProperties":true,"properties":{"ok":{"type":"boolean"},"mediaAssetId":{"type":"string"},"marketplaceAssetId":{"type":["string","null"]},"title":{"type":["string","null"]},"mediaKind":{"type":["string","null"]},"priceCredits":{"type":["string","null"],"pattern":"^\\d+$"},"purchaseEligible":{"type":"boolean"},"alreadyEntitled":{"type":"boolean"},"watchPath":{"type":["string","null"]},"purchaseMode":{"type":"string","enum":["internal_credits_only"]},"approvalRequired":{"type":"boolean"},"issueCode":{"type":["string","null"]}}},"BoxfetchMediaPurchaseInput":{"type":"object","required":["mediaAssetId","idempotencyKey"],"additionalProperties":false,"properties":{"mediaAssetId":{"type":"string"},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128}}},"BoxfetchMediaPurchaseOutput":{"type":"object","required":["ok","status","mediaAssetId","purchaseMode","liveMoney","externalPayout"],"additionalProperties":true,"properties":{"ok":{"type":"boolean"},"status":{"type":"string","enum":["purchased","already_entitled","approval_required","insufficient_credits","blocked","manual_review_required"]},"mediaAssetId":{"type":"string"},"marketplaceAssetId":{"type":["string","null"]},"purchaseId":{"type":["string","null"]},"mediaEntitlementId":{"type":["string","null"]},"approvalRequestId":{"type":["string","null"]},"watchPath":{"type":["string","null"]},"libraryPath":{"type":"string"},"issueCode":{"type":["string","null"]},"purchaseMode":{"type":"string","enum":["internal_credits_only"]},"liveMoney":{"type":"boolean","const":false},"externalPayout":{"type":"boolean","const":false}}},"BoxfetchMediaAccessInput":{"type":"object","required":["mediaAssetId"],"additionalProperties":false,"properties":{"mediaAssetId":{"type":"string"}}},"BoxfetchMediaAccessOutput":{"type":"object","required":["ok","accessActive","mediaAssetId","watchState"],"additionalProperties":true,"properties":{"ok":{"type":"boolean"},"accessActive":{"type":"boolean"},"mediaAssetId":{"type":"string"},"marketplaceAssetId":{"type":["string","null"]},"title":{"type":["string","null"]},"watchState":{"type":"string"},"accessType":{"type":["string","null"]},"watchPath":{"type":["string","null"]},"issueCode":{"type":["string","null"]}}},"SubmitUsageFeedbackInput":{"type":"object","required":["assetId","purchaseId","rating","feedbackType"],"additionalProperties":false,"properties":{"assetId":{"type":"string"},"purchaseId":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"feedbackType":{"type":"string","description":"Stable category for the feedback (e.g. accuracy, usefulness)."},"note":{"type":"string","maxLength":1000}}},"SubmitUsageFeedbackOutput":{"type":"object","required":["ok"],"additionalProperties":true,"properties":{"ok":{"type":"boolean"},"reviewId":{"type":"string"},"reasonCodes":{"type":"array","items":{"type":"string"}}}},"SellerListListingsInput":{"type":"object","additionalProperties":false,"properties":{}},"SellerListListingsOutput":{"type":"object","required":["listings"],"additionalProperties":true,"properties":{"listings":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"SellerCreateListingInput":{"type":"object","required":["title","previewText"],"additionalProperties":false,"properties":{"title":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":5000},"category":{"type":"string","maxLength":80},"previewText":{"type":"string","maxLength":5000},"fullContentDemo":{"type":"string"},"licenseType":{"type":"string","maxLength":80},"status":{"type":"string","enum":["draft","listed","paused"]},"minPriceMicrousd":{"type":"string","pattern":"^\\d+$"},"maxPriceMicrousd":{"type":"string","pattern":"^\\d+$"},"basePriceMicrousd":{"type":"string","pattern":"^\\d+$"},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":12},"intendedUse":{"type":"string","maxLength":400},"workflowBenefit":{"type":"string","maxLength":400},"ownershipAttested":{"type":"boolean"}}},"SellerCreateListingOutput":{"type":"object","required":["ok"],"additionalProperties":true,"properties":{"ok":{"type":"boolean"},"asset":{"type":"object","additionalProperties":true}}},"SellerUpdateListingInput":{"type":"object","required":["assetId"],"additionalProperties":false,"properties":{"assetId":{"type":"string"},"title":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":5000},"category":{"type":"string","maxLength":80},"previewText":{"type":"string","maxLength":5000},"fullContentDemo":{"type":"string"},"licenseType":{"type":"string","maxLength":80},"status":{"type":"string","enum":["draft","listed","paused"]},"minPriceMicrousd":{"type":"string","pattern":"^\\d+$"},"maxPriceMicrousd":{"type":"string","pattern":"^\\d+$"},"basePriceMicrousd":{"type":"string","pattern":"^\\d+$"},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":12},"intendedUse":{"type":"string","maxLength":400},"workflowBenefit":{"type":"string","maxLength":400},"ownershipAttested":{"type":"boolean"}}},"SellerUpdateListingOutput":{"type":"object","required":["ok"],"additionalProperties":true,"properties":{"ok":{"type":"boolean"},"asset":{"type":"object","additionalProperties":true}}},"GetAgentBudgetInput":{"type":"object","additionalProperties":false,"properties":{}},"GetAgentBudgetOutput":{"type":"object","required":["balanceMicrousd","spendable"],"additionalProperties":true,"properties":{"balanceMicrousd":{"type":"string","pattern":"^\\d+$"},"currency":{"type":"string","default":"USD"},"periodSpendMicrousd":{"type":"string","pattern":"^\\d+$"},"spendable":{"type":"boolean"},"limits":{"type":"object","additionalProperties":true,"properties":{"sessionMicrousd":{"type":"string","pattern":"^\\d+$"},"dailyMicrousd":{"type":"string","pattern":"^\\d+$"},"askMeAboveMicrousd":{"type":"string","pattern":"^\\d+$"}}}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Required for purchase_asset calls. Accepted as either an HTTP header or the `idempotencyKey` body field on the tool input. Replays return the original outcome; conflicts are rejected.","schema":{"type":"string","minLength":8,"maxLength":128}}}},"paths":{"/llms.txt":{"get":{"summary":"Discovery file for AI clients (plain text).","security":[],"responses":{"200":{"description":"Plain text llms.txt.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/.well-known/boxfetch-mcp":{"get":{"summary":"Machine-readable discovery document (canonical well-known path).","security":[],"responses":{"200":{"description":"Discovery JSON.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/public/mcp/manifest":{"get":{"summary":"MCP connector manifest with tool JSON schemas.","security":[],"responses":{"200":{"description":"Connector manifest JSON.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/public/openapi":{"get":{"summary":"This OpenAPI 3.1 document.","security":[],"responses":{"200":{"description":"OpenAPI JSON.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/public/agentic/showcase":{"get":{"summary":"Public marketplace showcase. Approved + listed assets only. Never returns full content.","security":[],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":12}}],"responses":{"200":{"description":"Public marketplace summary. Prices are in internal BoxFetch credits.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/public/agentic/search":{"get":{"summary":"Anonymous buyer-visible marketplace search. No credential.","description":"Public-safe listing projections only: no full content, no provider URL, no signed URL, no storage key, no private seller identity. 10-20 results per page, two pages maximum, then a registration handoff. Cursors are server-signed and bound to the exact filter set.","security":[],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"contentKind","in":"query","required":false,"schema":{"type":"string"}},{"name":"free","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"trust","in":"query","required":false,"schema":{"type":"string","enum":["verified"]}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":10,"maximum":20}}],"responses":{"200":{"description":"A results page or the registration handoff.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or tampered cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Body includes retryAfterSeconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/agentic/items/{assetId}":{"get":{"summary":"Public-safe detail for one listing. No credential.","security":[],"parameters":[{"name":"assetId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Public item projection plus schema.org structured metadata.","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown, unlisted, unapproved, or deleted asset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/agentic/agents/register":{"post":{"summary":"Register a provisional agent identity. No credential.","description":"Creates an UNOWNED provisional agent and returns three separate values: a public opaque claimRequestId embedded in the exact human claim URL, a body-only claimPollSecret for the registering agent, and a human-readable fallback claimCode. The claim URL contains no secret and does not authorize the claim. The agent cannot claim itself. Secrets are never persisted raw. Rate-limited per client per hour on a durable counter.","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":80,"description":"Optional display name shown to the human."}}}}}},"responses":{"201":{"description":"Provisional agent created; public claim URL and separate polling secret returned.","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Registration rate limited. Body includes retryAfterSeconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Registration unavailable in this runtime.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/agentic/agents/claim-status":{"post":{"summary":"Poll a pending claim. Returns bounded state only; never a credential.","description":"POST only, so the polling secret stays out of URLs, access logs, referrers, and browser history. Returns pending while the human has not confirmed, and claimed once they have. It NEVER returns a credential in any state: after the claim, the agent connects to the protected MCP endpoint and completes the standard OAuth authorization it advertises.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claimPollSecret"],"additionalProperties":false,"properties":{"claimPollSecret":{"type":"string","minLength":16,"maxLength":256}}}}}},"responses":{"200":{"description":"Bounded claim state only. Never contains a credential.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Missing claim polling secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown claim polling secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/public":{"post":{"summary":"UNAUTHENTICATED MCP Streamable HTTP bootstrap endpoint.","description":"The cold-start MCP rail. An MCP client with no BoxFetch credential can complete initialize and tools/list here and call exactly five tools: boxfetch_discover, boxfetch_search_public, boxfetch_get_public_item, boxfetch_register_agent, boxfetch_check_claim_status. Nothing that purchases, reads entitled content, reads budgets, reads private previews, touches approvals, or reads human account data is reachable. A protected tool name returns 403 with the registration next action. Origin is validated. Initialize creates a durably bounded session, notifications/initialized activates it, DELETE releases it, and GET remains 405 because there is no server-initiated SSE stream.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"additionalProperties":true,"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"method":{"type":"string","enum":["initialize","notifications/initialized","tools/list","tools/call"]},"params":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"JSON-RPC success response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcSuccess"}}}},"202":{"description":"Notification accepted; no JSON-RPC result body."},"400":{"description":"Parse error, invalid request, invalid params, batch, or unsupported MCP-Protocol-Version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"403":{"description":"Disallowed Origin, or a protected tool name requested on the public rail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"406":{"description":"Accept header excludes application/json; this endpoint answers JSON only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"413":{"description":"Request body too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"429":{"description":"Registration rate limited. Body includes retryAfterSeconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}}}},"get":{"summary":"No server-initiated SSE stream.","security":[],"responses":{"405":{"description":"SSE not implemented."}}},"delete":{"summary":"No sessions are issued.","security":[],"responses":{"405":{"description":"Sessions not implemented."}}}},"/api/mcp/external":{"post":{"summary":"Custom external MCP tool API. Bearer-authenticated. Dispatches tool calls.","description":"Existing custom HTTP tool API for BoxFetch agents. Primary request shape is flattened `{ \"toolName\": \"search_assets\", ...tool input fields }`. The contract envelope `{ \"tool\": \"search_assets\", \"input\": {} }` and compatibility alias `{ \"name\": \"search_assets\", \"arguments\": {} }` are also accepted. Purchases settle in internal BoxFetch credits and require a funded human account. Above-threshold purchases pause for human approval. Rate-limited per token, per agent, per user, and per user/per tool. purchase_asset requires Idempotency-Key as a header or `idempotencyKey` body field.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["toolName"],"additionalProperties":true,"properties":{"toolName":{"type":"string","enum":["search_assets","preview_asset","quote_asset","purchase_asset","get_purchase_approval","get_asset_content","boxfetch_media_quote","boxfetch_media_purchase","boxfetch_media_access","submit_usage_feedback","seller_list_listings","seller_create_listing","seller_update_listing","get_agent_budget"],"description":"Tool name. Tool input fields are flattened into the same JSON object."}}},{"type":"object","required":["tool","input"],"additionalProperties":false,"properties":{"tool":{"type":"string","enum":["search_assets","preview_asset","quote_asset","purchase_asset","get_purchase_approval","get_asset_content","boxfetch_media_quote","boxfetch_media_purchase","boxfetch_media_access","submit_usage_feedback","seller_list_listings","seller_create_listing","seller_update_listing","get_agent_budget"]},"input":{"type":"object","additionalProperties":true}}},{"type":"object","required":["name","arguments"],"additionalProperties":false,"properties":{"name":{"type":"string","enum":["search_assets","preview_asset","quote_asset","purchase_asset","get_purchase_approval","get_asset_content","boxfetch_media_quote","boxfetch_media_purchase","boxfetch_media_access","submit_usage_feedback","seller_list_listings","seller_create_listing","seller_update_listing","get_agent_budget"]},"arguments":{"type":"object","additionalProperties":true}}}]},"examples":{"flattened":{"value":{"toolName":"search_assets","limit":5}},"envelope":{"value":{"tool":"search_assets","input":{"limit":5}}},"nameArguments":{"value":{"name":"search_assets","arguments":{"limit":5}}}}}}},"responses":{"200":{"description":"Tool result. Shape depends on `tool`.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (permission, approval required, or quote/idempotency conflict).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown asset or approval request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Body includes retryAfterSeconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp/standard":{"post":{"summary":"Protected MCP Streamable HTTP JSON-RPC endpoint.","description":"Streamable HTTP MCP JSON-RPC endpoint for a CLAIMED BoxFetch agent. Supports initialize, notifications/*, tools/list, and tools/call. Protocol revisions 2025-11-25 and 2025-06-18 are negotiated at initialize; an MCP-Protocol-Version header naming an unsupported revision is refused rather than downgraded. 2025-03-26 is NOT offered, because that revision requires JSON-RPC batch reception which this transport does not implement. Origin is validated on POST, GET, and DELETE. Authorization is standard MCP OAuth 2.1: a 401 carries a WWW-Authenticate challenge naming RFC 9728 protected-resource metadata, which leads to RFC 8414 authorization-server metadata, RFC 7591 dynamic client registration, and an authorization-code flow with mandatory PKCE (S256) and RFC 8707 resource binding. Tokens are scoped, agent-bound, expiring, and revocable; a tool outside the granted scope is refused with insufficient_scope. A manually configured bearer header remains only as an operator/development fallback. Initialize creates a protected durable session, notifications/initialized activates it, DELETE releases it, and GET remains 405 because there is no server-initiated SSE stream. JSON-RPC batching, resources, prompts, official connector claims, seller external payout, and buyer cash-out remain absent. A 401 also names the public bootstrap endpoint so an agent with no OWNER has a path forward.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"additionalProperties":true,"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"method":{"type":"string","enum":["initialize","notifications/initialized","tools/list","tools/call"]},"params":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"JSON-RPC success response for request messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcSuccess"}}}},"202":{"description":"Notification accepted; no JSON-RPC result body."},"400":{"description":"Parse error, invalid request, invalid params, batch, or unsupported MCP-Protocol-Version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"401":{"description":"Missing or invalid bearer token. Body names the public bootstrap endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"403":{"description":"Disallowed Origin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"406":{"description":"Accept header excludes application/json; this endpoint answers JSON only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"413":{"description":"Request body too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}},"429":{"description":"Rate limited. Body includes retryAfterSeconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcError"}}}}}},"get":{"summary":"No server-initiated SSE stream is offered.","security":[{"bearerAuth":[]}],"responses":{"405":{"description":"SSE not implemented."}}},"delete":{"summary":"No sessions are issued, so there is nothing to delete.","security":[{"bearerAuth":[]}],"responses":{"405":{"description":"Sessions not implemented."}}}}},"x-tools":[{"name":"search_assets","description":"List approved + listed marketplace assets discoverable by the calling agent. Returns capped, listed-only summaries.","requiresPurchase":false,"requiresIdempotencyKey":false},{"name":"preview_asset","description":"Return a buyer-safe preview for a listed asset. Never returns full Markdown body or container bytes.","requiresPurchase":false,"requiresIdempotencyKey":false},{"name":"quote_asset","description":"Issue a durable single-use purchase quote for a listed asset. The quote binds seller, price, and content identity; pass its quoteId to purchase_asset to settle it exactly once.","requiresPurchase":false,"requiresIdempotencyKey":false},{"name":"purchase_asset","description":"Settle a purchase through the native BoxFetch wallet rail. Prefer passing a durable quoteId from quote_asset (single-use, content-bound); the legacy assetId + quotedPriceMicrousd shape is still accepted. Requires an idempotency key. Above-threshold purchases return approvalRequired with an approvalRequestId.","requiresPurchase":false,"requiresIdempotencyKey":true},{"name":"get_purchase_approval","description":"Poll a human approval request created by purchase_asset. Returns pending, declined, expired, or captured, and returns unlocked content only after user approval + capture.","requiresPurchase":false,"requiresIdempotencyKey":false},{"name":"get_asset_content","description":"Retrieve unlocked content after a captured purchase. Markdown-backed assets return Markdown text; container-backed assets return metadata, usageInstructions, and agentDownloadUrl for bearer-authenticated byte retrieval. Bytes are never returned inline. BoxFetch does not parse, unzip, execute, render, or scan containers.","requiresPurchase":true,"requiresIdempotencyKey":false},{"name":"boxfetch_media_quote","description":"Return a safe quote for one explicit BoxFetch media id. No discovery, playback token, iframe, provider uid, R2 key, download URL, payout, or production-money data is returned.","requiresPurchase":false,"requiresIdempotencyKey":false},{"name":"boxfetch_media_purchase","description":"Purchase one explicit eligible BoxFetch media id through internal credits only, or return approval_required when existing MCP approval controls cannot safely capture media entitlement issuance. Never returns playback or provider data.","requiresPurchase":false,"requiresIdempotencyKey":true},{"name":"boxfetch_media_access","description":"Return safe media entitlement/watch status for one explicit BoxFetch media id. Does not issue Cloudflare playback, iframe src, provider uid, token, R2 key, bytes, or download URLs.","requiresPurchase":false,"requiresIdempotencyKey":false},{"name":"submit_usage_feedback","description":"Record validated usage feedback for a previously captured purchase. Rejected feedback returns reasonCodes and does not affect trust.","requiresPurchase":true,"requiresIdempotencyKey":false},{"name":"seller_list_listings","description":"List the calling seller-agent owner's marketplace listings (drafts included). Requires a claimed agent with canSell=true.","requiresPurchase":false,"requiresIdempotencyKey":false},{"name":"seller_create_listing","description":"Create a draft or published listing for the claimed seller-agent owner. Publication requires the owner's accepted seller terms, a per-listing ownership attestation, and a meaningful sample on paid listings; TrustWorks routing decides publish/correct/block.","requiresPurchase":false,"requiresIdempotencyKey":false},{"name":"seller_update_listing","description":"Update, publish, or pause an owned listing (metadata, price, content, status). Same publication gates and TrustWorks routing as creation.","requiresPurchase":false,"requiresIdempotencyKey":false},{"name":"get_agent_budget","description":"Read the calling agent's canonical BoxFetch wallet balance and rolling session/daily/monthly budget snapshot (internal BoxFetch credits, spend-only).","requiresPurchase":false,"requiresIdempotencyKey":false}],"security":[{"bearerAuth":[]}]}