{"openapi":"3.1.1","info":{"title":"BUFI public agent and developer API","version":"1.0.0","description":"Read published, opt-in workspace portfolios and canonical WebMCP tool definitions without credentials. Tool definitions cannot execute financial actions over HTTP. Private workspace APIs retain their existing access controls. Public OAuth issuance and sandbox credentials are not offered by this API."},"servers":[{"url":"/"}],"externalDocs":{"url":"/developers","description":"BUFI developer onboarding and examples"},"security":[],"paths":{"/api/public/agents":{"get":{"operationId":"listPublicWorkspaceAgents","summary":"List published BUFI workspace portfolios and services","description":"Read only portfolios explicitly published by active paid workspaces. No credential is required. An empty profiles array is a successful result. This endpoint does not expose private financial records or authorize any payment. Pagination scans at most 24 publication records, so filtering may return fewer profiles; follow nextOffset when present.","tags":["Public directory"],"security":[],"x-rate-limit":{"requests":60,"windowSeconds":60,"algorithm":"fixed-window","key":"client-ip","description":"Production uses the standard tier. Directory and per-workspace reads have separate IP keys. Local development bypasses the limiter."},"parameters":[{"name":"offset","in":"query","description":"Publication-record offset. Use pagination.nextOffset for the next page.","required":false,"schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"q","in":"query","description":"Optional search text, trimmed before validation.","required":false,"schema":{"type":"string","maxLength":120,"default":""}}],"responses":{"200":{"description":"Published profiles and pagination cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentDirectoryPage"}}}},"400":{"description":"Search exceeds 120 trimmed characters, or offset is outside 0–10000.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicAgentDirectoryProblem"}}}},"429":{"description":"The client IP exceeded the standard rate limit. Wait for Retry-After seconds before retrying.","headers":{"Retry-After":{"description":"Seconds until another request may be attempted.","schema":{"type":"integer","minimum":1}},"X-RateLimit-Remaining":{"description":"Remaining requests reported by the rate limiter.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentRateLimitError"}}}},"503":{"description":"Directory lookup or rate limiting is unavailable. Retry later; Retry-After is present when the rate limiter is unavailable.","headers":{"Retry-After":{"description":"Seconds to wait when the rate limiter is unavailable.","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentDirectoryError"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicAgentDirectoryProblem"}}}}}}},"/api/public/agents/{teamId}/{surface}":{"get":{"operationId":"readPublicWorkspaceAgentSurface","summary":"Read a published workspace profile, services or discovery document","description":"Anonymous read of a workspace that has explicitly opted into publication and still has an active paid plan. profile returns the published portfolio; services returns its service catalog and quoteEndpoint; agent-card.json returns an A2A 0.3.0 card; x402 returns an empty discovery catalog because inquiries are free and this route is not payment-gated. The a2a surface accepts POST only, so a GET returns 405. Creating a quote request requires authenticated workspace access and is outside this read-only operation.","tags":["Public directory"],"security":[],"x-rate-limit":{"requests":60,"windowSeconds":60,"algorithm":"fixed-window","key":"client-ip","description":"Production uses the standard tier. Directory and per-workspace reads have separate IP keys. Local development bypasses the limiter."},"parameters":[{"name":"teamId","in":"path","description":"Workspace UUID obtained from the public directory.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"surface","in":"path","description":"Public surface to read. a2a is recognized but does not support GET.","required":true,"schema":{"type":"string","enum":["profile","services","agent-card.json","x402","a2a"]}}],"responses":{"200":{"description":"The response shape depends on the requested surface.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PublicWorkspaceAgentProfile"},{"$ref":"#/components/schemas/PublicWorkspaceAgentServices"},{"$ref":"#/components/schemas/PublicWorkspaceAgentCard"},{"$ref":"#/components/schemas/PublicWorkspaceX402Catalog"}]}}}},"404":{"description":"Invalid UUID or surface, or the workspace is not currently published.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicAgentDirectoryProblem"}}}},"405":{"description":"GET is not supported by the a2a surface.","headers":{"Allow":{"description":"Supported methods for the a2a surface.","schema":{"type":"string","const":"POST, OPTIONS"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicAgentDirectoryProblem"}}}},"429":{"description":"The client IP exceeded the standard rate limit. Wait for Retry-After seconds before retrying.","headers":{"Retry-After":{"description":"Seconds until another request may be attempted.","schema":{"type":"integer","minimum":1}},"X-RateLimit-Remaining":{"description":"Remaining requests reported by the rate limiter.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentRateLimitError"}}}},"503":{"description":"Directory lookup or rate limiting is unavailable. Retry later; Retry-After is present when the rate limiter is unavailable.","headers":{"Retry-After":{"description":"Seconds to wait when the rate limiter is unavailable.","schema":{"type":"integer","const":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentDirectoryError"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/PublicAgentDirectoryProblem"}}}}}}},"/api/public/tools":{"get":{"operationId":"listPublicToolContracts","summary":"List BUFI browser tool contracts","description":"Read the canonical public tool schemas for planning browser actions. This endpoint exposes definitions only, contains no workspace data, and never registers or executes a tool.","security":[],"responses":{"200":{"description":"Public tool catalog with browser invocation guidance.","content":{"application/json":{"schema":{"type":"object","required":["product","invocation","guidance","docs","count","tools"],"properties":{"product":{"type":"string","const":"BUFI"},"invocation":{"type":"string","const":"in-page-webmcp"},"guidance":{"type":"string"},"docs":{"type":"string"},"count":{"type":"integer","minimum":0},"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolContract"}}},"additionalProperties":false}}}}}}},"/api/public/tools/{name}":{"get":{"operationId":"getPublicToolContract","summary":"Read one BUFI browser tool contract","description":"Look up one contract by its exact tool name. A returned definition does not imply that the tool is active in the current browser page.","security":[],"parameters":[{"name":"name","in":"path","required":true,"description":"Exact name from listPublicToolContracts, for example read_public_invoice.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Canonical public browser tool contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolContract"}}}},"404":{"description":"No tool has that name; use the catalog to select an existing contract.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"schemas":{"PublicAgentDirectoryError":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}},"PublicAgentDirectoryProblem":{"type":"object","required":["type","title","status","error","code","message","detail","hint"],"properties":{"type":{"type":"string","const":"about:blank"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"error":{"type":"string","description":"Legacy error message retained for existing clients."},"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string"},"detail":{"type":"string"},"hint":{"type":"string","description":"Suggested recovery action."},"instance":{"type":"string","description":"Requested URL path."}}},"PublicAgentRateLimitError":{"type":"object","required":["error","message","retryAfter"],"properties":{"error":{"type":"string","const":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string"},"retryAfter":{"type":"integer","description":"Rate limiter reset delta in seconds."}}},"PublicAgentPortfolioItem":{"type":"object","required":["id","title","description","url"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":1000},"url":{"type":"string","format":"uri","maxLength":2048,"pattern":"^https://"},"imageUrl":{"type":"string","format":"uri","maxLength":2048,"pattern":"^https://"}}},"PublicAgentMarketplaceService":{"type":"object","required":["id","name","description","price","currency","unit","imageUrl"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"price":{"type":"number","minimum":0},"currency":{"type":"string"},"unit":{"type":["string","null"]},"imageUrl":{"type":["string","null"],"pattern":"^https://"}}},"PublicAgentPaymentScore":{"type":"object","description":"Optional fresh confidential CRE report for this workspace. Null when a trusted fresh report is unavailable; do not infer a score.","required":["score","asOf","expiresAt","evidenceCommitment","chainId","receiver","workflowId","source"],"properties":{"score":{"type":"number","minimum":0,"maximum":100},"asOf":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"evidenceCommitment":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"chainId":{"type":"integer","minimum":1},"receiver":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"workflowId":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"source":{"type":"string","const":"confidential-cre"}}},"PublicWorkspaceAgentProfile":{"type":"object","required":["headline","summary","portfolioItems","serviceProductIds","meetingUrl","teamId","name","agentAddress","services","portfolioUrl","agentCardUrl","paymentScore"],"properties":{"headline":{"type":"string","maxLength":120},"summary":{"type":"string","maxLength":2000},"portfolioItems":{"type":"array","maxItems":12,"items":{"$ref":"#/components/schemas/PublicAgentPortfolioItem"}},"serviceProductIds":{"type":"array","maxItems":50,"uniqueItems":true,"items":{"type":"string","format":"uuid"}},"meetingUrl":{"type":["string","null"],"format":"uri","maxLength":2048,"pattern":"^https://"},"teamId":{"type":"string","format":"uuid"},"name":{"type":"string"},"agentAddress":{"type":["string","null"],"pattern":"^0x[0-9a-fA-F]{40}$"},"services":{"type":"array","items":{"$ref":"#/components/schemas/PublicAgentMarketplaceService"}},"portfolioUrl":{"type":"string","description":"Relative URL of the public portfolio."},"agentCardUrl":{"type":"string","description":"Relative URL of the public A2A card."},"paymentScore":{"anyOf":[{"$ref":"#/components/schemas/PublicAgentPaymentScore"},{"type":"null"}]}}},"PublicAgentDirectoryPage":{"type":"object","required":["profiles","pagination"],"properties":{"profiles":{"type":"array","maxItems":24,"items":{"$ref":"#/components/schemas/PublicWorkspaceAgentProfile"}},"pagination":{"type":"object","required":["offset","limit","nextOffset"],"properties":{"offset":{"type":"integer","minimum":0,"maximum":10000},"limit":{"type":"integer","const":24},"nextOffset":{"type":["integer","null"],"minimum":0}}}}},"PublicWorkspaceAgentServices":{"type":"object","required":["services","quoteEndpoint"],"properties":{"services":{"type":"array","items":{"$ref":"#/components/schemas/PublicAgentMarketplaceService"}},"quoteEndpoint":{"type":"string","format":"uri","description":"Authenticated inquiry endpoint; publishing this URL does not grant access."}}},"PublicWorkspaceAgentCard":{"type":"object","required":["protocolVersion","version","name","description","url","preferredTransport","supportedInterfaces","capabilities","defaultInputModes","defaultOutputModes","skills","securitySchemes","documentationUrl","metadata"],"properties":{"protocolVersion":{"type":"string","const":"0.3.0"},"version":{"type":"string","const":"1.0.0"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"preferredTransport":{"type":"string","const":"JSONRPC"},"supportedInterfaces":{"type":"array","items":{"type":"object","required":["url","transport"],"properties":{"url":{"type":"string","format":"uri"},"transport":{"type":"string","const":"JSONRPC"}}}},"capabilities":{"type":"object","required":["streaming","pushNotifications"],"properties":{"streaming":{"type":"boolean","const":false},"pushNotifications":{"type":"boolean","const":false}}},"defaultInputModes":{"type":"array","items":{"type":"string","const":"application/json"}},"defaultOutputModes":{"type":"array","items":{"type":"string","const":"application/json"}},"skills":{"type":"array","items":{"type":"object","required":["id","name","description","tags"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"security":{"type":"array","items":{"type":"object","properties":{"workspace":{"type":"array","maxItems":0,"items":{"type":"string"}}}}}}}},"securitySchemes":{"type":"object","required":["workspace"],"properties":{"workspace":{"type":"object","required":["type","scheme"],"properties":{"type":{"type":"string","const":"http"},"scheme":{"type":"string","const":"bearer"}}}}},"documentationUrl":{"type":"string","format":"uri"},"metadata":{"allOf":[{"$ref":"#/components/schemas/PublicWorkspaceAgentProfile"},{"type":"object","required":["quoteEndpoint","x402DiscoveryUrl"],"properties":{"quoteEndpoint":{"type":"string","format":"uri"},"x402DiscoveryUrl":{"type":"string","format":"uri"}}}]}}},"PublicWorkspaceX402Catalog":{"type":"object","required":["x402Version","items","pagination"],"properties":{"x402Version":{"type":"integer","const":2},"items":{"type":"array","maxItems":0,"items":{}},"pagination":{"type":"object","required":["limit","offset","total"],"properties":{"limit":{"type":"integer","const":0},"offset":{"type":"integer","const":0},"total":{"type":"integer","const":0}}}}},"ToolContract":{"type":"object","required":["name","title","description","inputSchema","stableKey"],"properties":{"name":{"type":"string","description":"Unique in-page WebMCP tool name."},"title":{"type":"string"},"description":{"type":"string"},"stableKey":{"type":"string"},"inputSchema":{"type":"object","description":"The canonical JSON Schema accepted by the active browser tool.","additionalProperties":true},"annotations":{"type":"object","properties":{"readOnlyHint":{"type":"boolean"},"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"},"untrustedContentHint":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"Problem":{"type":"object","required":["type","title","status","detail","code","hint"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}}