{ "openapi": "3.1.0", "info": { "title": "Palate Agent API", "version": "0.1.0", "description": "Quote-first paid access to public, unlisted, and authorized private Palates. Agents discover channels, request a free quote, pay on a supported rail, then execute a raw or synthesized query with canonical Palate citations." }, "servers": [ { "url": "https://palate.inc", "description": "Production" } ], "tags": [ { "name": "Discovery" }, { "name": "Quotes" }, { "name": "Paid Queries" }, { "name": "MCP" } ], "components": { "securitySchemes": { "PrivyBearer": { "type": "http", "scheme": "bearer", "description": "Optional Privy bearer token. Required only when reading a private Palate as an authorized owner or team member." } }, "schemas": { "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "examples": ["not_found", "missing_query", "rate_limited", "invalid_payment_proof"] }, "message": { "type": "string" }, "resetAt": { "type": "string", "format": "date-time" }, "supportedRails": { "type": "array", "items": { "$ref": "#/components/schemas/SupportedRail" } } }, "additionalProperties": true }, "Channel": { "type": "object", "required": ["id", "kind", "label", "accessLevel", "ratePerMillionTokens", "status"], "properties": { "id": { "type": "string", "examples": ["podcast", "rss", "notion"] }, "kind": { "type": "string", "enum": ["youtube", "podcast_rss", "rss", "notion", "subtext"] }, "label": { "type": "string", "examples": ["Invest Like the Best"] }, "accessLevel": { "type": "string", "enum": ["public", "private"] }, "ratePerMillionTokens": { "type": "number", "description": "Dollars per one million Palate tokens." }, "status": { "type": "string", "enum": ["live", "syncing", "paused"] } }, "additionalProperties": false }, "EndpointManifest": { "type": "object", "required": ["channels", "quote", "query", "mcp"], "properties": { "channels": { "type": "string" }, "quote": { "type": "string" }, "query": { "type": "string" }, "mcp": { "type": "string" } }, "additionalProperties": false }, "DirectoryPalate": { "type": "object", "required": ["slug", "name", "description", "channels", "endpoints"], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } }, "endpoints": { "$ref": "#/components/schemas/EndpointManifest" } }, "additionalProperties": false }, "PalateRef": { "type": "object", "required": ["slug", "name"], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "Mode": { "type": "string", "enum": ["raw", "synthesized"], "default": "raw" }, "QuoteRequest": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "minLength": 1, "description": "One user-visible question." }, "mode": { "$ref": "#/components/schemas/Mode" }, "channelIds": { "type": "array", "items": { "type": "string" }, "description": "Optional subset of channel ids returned by the manifest." } }, "additionalProperties": false }, "QuoteLineItem": { "type": "object", "required": [ "channelId", "kind", "label", "accessLevel", "tokensRetrieved", "ratePerMillionTokens", "priceMillicents" ], "properties": { "channelId": { "type": "string" }, "kind": { "type": "string", "enum": ["youtube", "podcast_rss", "rss", "notion", "subtext"] }, "label": { "type": "string" }, "accessLevel": { "type": "string", "enum": ["public", "private"] }, "tokensRetrieved": { "type": "integer", "minimum": 0 }, "ratePerMillionTokens": { "type": "number", "description": "Dollars per one million Palate tokens." }, "priceMillicents": { "type": "integer", "description": "USD millicents. Divide by 100000 for USD." } }, "additionalProperties": false }, "SupportedRail": { "type": "object", "required": ["rail", "currency", "feeSponsored"], "properties": { "rail": { "type": "string", "enum": ["tempo", "x402_base"] }, "currency": { "type": "string", "examples": ["USDC", "pathUSD"] }, "chain": { "type": "string", "examples": ["base"] }, "feeSponsored": { "type": "boolean" } }, "additionalProperties": false }, "PaymentChallenge": { "type": "object", "required": ["status", "message"], "properties": { "status": { "type": "integer", "const": 402 }, "message": { "type": "string" } }, "additionalProperties": false }, "QuoteResponse": { "type": "object", "required": [ "palate", "query", "mode", "lineItems", "synthPlatformFeeMillicents", "totalUsdMillicents", "nonce", "expiresAt", "supportedRails", "challenge" ], "properties": { "palate": { "$ref": "#/components/schemas/PalateRef" }, "query": { "type": "string" }, "mode": { "$ref": "#/components/schemas/Mode" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteLineItem" } }, "synthPlatformFeeMillicents": { "type": "integer", "description": "Fixed platform synth fee in USD millicents. Present as 500 for synthesized mode and 0 for raw mode." }, "totalUsdMillicents": { "type": "integer" }, "nonce": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time" }, "supportedRails": { "type": "array", "items": { "$ref": "#/components/schemas/SupportedRail" } }, "challenge": { "$ref": "#/components/schemas/PaymentChallenge" } }, "additionalProperties": false }, "TempoPaymentProof": { "type": "object", "required": ["rail", "quoteNonce", "txHash"], "properties": { "rail": { "type": "string", "const": "tempo" }, "txHash": { "type": "string" }, "quoteNonce": { "type": "string", "description": "Nonce returned by the quote response that this payment satisfies." }, "walletAddress": { "type": "string" }, "payer": { "type": "string" }, "from": { "type": "string" }, "address": { "type": "string" } }, "additionalProperties": true }, "X402BasePaymentProof": { "type": "object", "required": ["rail", "quoteNonce", "facilitatorReceipt"], "properties": { "rail": { "type": "string", "const": "x402_base" }, "facilitatorReceipt": { "type": "string" }, "quoteNonce": { "type": "string", "description": "Nonce returned by the quote response that this payment satisfies." }, "walletAddress": { "type": "string" }, "payer": { "type": "string" }, "from": { "type": "string" }, "address": { "type": "string" } }, "additionalProperties": true }, "PaymentProof": { "oneOf": [ { "$ref": "#/components/schemas/TempoPaymentProof" }, { "$ref": "#/components/schemas/X402BasePaymentProof" } ] }, "QueryRequest": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "minLength": 1 }, "mode": { "$ref": "#/components/schemas/Mode" }, "channelIds": { "type": "array", "items": { "type": "string" } }, "paymentProof": { "$ref": "#/components/schemas/PaymentProof", "description": "Required for paid queries. True zero-dollar raw queries on free channels may omit payment proof and are still rate-limited." } }, "additionalProperties": false }, "Citation": { "type": "object", "required": ["itemId", "channelId", "chunkId", "text", "score", "palateUrl", "deeplink", "ordinal"], "properties": { "itemId": { "type": "string" }, "channelId": { "type": "string" }, "chunkId": { "type": "string" }, "text": { "type": "string" }, "publishedAt": { "type": "string", "format": "date-time" }, "score": { "type": "number" }, "palateUrl": { "type": "string", "format": "uri", "description": "Canonical Palate citation URL. Retrieved citations include a chunks query parameter such as //i/?chunks=." }, "deeplink": { "type": "string", "description": "Media timestamp or chunk anchor, for example ?t=2322 or #chunk-1." }, "sourceUrl": { "type": "string", "format": "uri", "description": "Original source URL when the cited item is public. Omitted for private channels." }, "ordinal": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "Receipt": { "type": "object", "required": [ "palateSlug", "walletAddress", "totalUsdMillicents", "cacheHit" ], "properties": { "palateSlug": { "type": "string" }, "walletAddress": { "type": "string" }, "totalUsdMillicents": { "type": "integer" }, "rail": { "type": "string", "enum": ["tempo", "x402_base"], "description": "Payment rail used for paid queries. Omitted for true zero-dollar raw queries on free channels." }, "paymentReceiptId": { "type": "string", "description": "Tempo tx hash or x402 facilitator receipt id." }, "cacheHit": { "type": "boolean", "description": "True when the same wallet, query, mode, and channel set returns the 60-second cached paid response." } }, "additionalProperties": false }, "QueryResponse": { "type": "object", "required": ["mode", "citations", "receipt"], "properties": { "mode": { "$ref": "#/components/schemas/Mode" }, "answer": { "type": "string", "description": "Present for synthesized queries." }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/Citation" } }, "receipt": { "$ref": "#/components/schemas/Receipt" } }, "additionalProperties": false }, "McpManifest": { "type": "object", "required": ["protocol", "palate", "tools", "skill"], "properties": { "protocol": { "type": "string", "const": "mcp" }, "palate": { "$ref": "#/components/schemas/PalateRef" }, "tools": { "type": "array", "items": { "type": "object", "required": ["name", "description"], "properties": { "name": { "type": "string", "enum": ["palate_list_channels", "palate_quote", "palate_query"] }, "description": { "type": "string" }, "inputSchema": { "type": "object", "description": "JSON Schema for the MCP tool arguments.", "additionalProperties": true } }, "additionalProperties": false } }, "skill": { "type": "string", "const": "/SKILL.md" } }, "additionalProperties": false }, "McpRequest": { "type": "object", "properties": { "jsonrpc": { "type": "string", "examples": ["2.0"] }, "id": { "description": "JSON-RPC request id.", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "method": { "type": "string", "description": "Supports initialize, tools/list, tools/call, or direct tool names.", "enum": [ "initialize", "notifications/initialized", "tools/list", "tools/call", "palate_list_channels", "palate_quote", "palate_query" ] }, "params": { "type": "object", "description": "For tools/call, pass { name, arguments }. For direct tool methods, pass tool arguments.", "additionalProperties": true }, "tool": { "type": "string", "description": "Compatibility alias for direct tool calls." }, "arguments": { "type": "object", "description": "Compatibility field for direct tool arguments.", "additionalProperties": true } }, "additionalProperties": true }, "McpResponse": { "type": "object", "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "description": "JSON-RPC response id.", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "result": { "description": "MCP result. tools/call returns content plus structuredContent; direct tool methods return the tool payload.", "additionalProperties": true }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } } }, "paths": { "/health": { "get": { "tags": ["Discovery"], "summary": "Return Worker health", "responses": { "200": { "description": "Worker health response", "content": { "application/json": { "schema": { "type": "object", "required": ["ok", "service", "environment"], "properties": { "ok": { "type": "boolean" }, "service": { "type": "string", "const": "palate-edge" }, "environment": { "type": "string" } }, "additionalProperties": false } } } } } } }, "/api/palates": { "get": { "tags": ["Discovery"], "summary": "List public directory Palates", "description": "Returns a paginated list of public Palates that opted into the directory. Production returns an empty list instead of bundled demo rows if Convex is unavailable.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum rows to return. Defaults to 50 and caps at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor returned as nextCursor. Current implementation uses a numeric offset string.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Directory rows with channels, rates, and endpoints.", "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryPalate" } }, "nextCursor": { "type": "string", "description": "Pass this as cursor to fetch the next page. Omitted on the last page." } }, "additionalProperties": false } } } } } } }, "/api/palates/{slug}/channels": { "get": { "tags": ["Discovery"], "summary": "Return one Palate channel manifest", "description": "Public and unlisted Palates are readable by slug. Private Palates require an authorized Privy bearer token or Privy cookie for the owner/team member.", "security": [ {}, { "PrivyBearer": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Channel manifest with dollars per one million Palate tokens.", "content": { "application/json": { "schema": { "type": "object", "required": ["slug", "name", "channels", "pricingUnit", "palateToken"], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } }, "pricingUnit": { "type": "string", "const": "dollars_per_million_palate_tokens" }, "palateToken": { "type": "string", "const": "ceil(charCount / 4)" } }, "additionalProperties": false } } } }, "404": { "description": "Unknown Palate, private Palate without authorization, or production Convex miss.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/palates/{slug}/quote": { "post": { "tags": ["Quotes"], "summary": "Return an itemized quote and 402 payment challenge", "description": "Quotes are free. Production Convex Palates fail closed if retrieval is unavailable and return no_relevant_content when no indexed chunks match the question. The successful quote response intentionally uses HTTP 402 because payment is required before query execution.", "security": [ {}, { "PrivyBearer": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "quote": { "value": { "query": "What is Patrick's actual take on founder-led culture after a CEO transition?", "mode": "raw" } } } } } }, "responses": { "402": { "description": "Quote with nonce, expiry, line items, total, supported rails, and payment challenge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "400": { "description": "Missing query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown Palate or private Palate without authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No indexed Palate content was relevant enough to price this question.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free quote rate limit exceeded. Retry-After is returned in seconds.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Production retrieval unavailable, so the Palate cannot be priced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/palates/{slug}/query": { "post": { "tags": ["Paid Queries"], "summary": "Execute a paid raw or synthesized query", "description": "Agents must reuse the same user-visible question, mode, channel set, and quote nonce they quoted, pay on a supported rail when the quote total is greater than zero, then submit proof before the quote expires. True zero-dollar raw queries on free channels may omit payment proof. Same wallet, normalized query, mode, and channel set are cached for 60 seconds.", "security": [ {}, { "PrivyBearer": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "examples": { "tempo": { "value": { "query": "What is Patrick's actual take on founder-led culture after a CEO transition?", "mode": "synthesized", "paymentProof": { "rail": "tempo", "quoteNonce": "quote-nonce-from-quote-response", "txHash": "0x...", "walletAddress": "0x..." } } }, "x402_base": { "value": { "query": "What is Patrick's actual take on founder-led culture after a CEO transition?", "mode": "raw", "paymentProof": { "rail": "x402_base", "quoteNonce": "quote-nonce-from-quote-response", "facilitatorReceipt": "receipt_...", "walletAddress": "0x..." } } }, "free_raw": { "value": { "query": "What public free-channel source chunks mention this topic?", "mode": "raw" } } } } } }, "responses": { "200": { "description": "Answer or raw chunks, citations, and receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "400": { "description": "Missing query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Missing/invalid payment proof or platform query limit reached.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown Palate or private Palate without authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No indexed Palate content was relevant enough to price this question.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Production retrieval unavailable, so the paid query cannot be priced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{slug}/mcp": { "get": { "tags": ["MCP"], "summary": "Return per-Palate MCP metadata", "description": "Returns the tool manifest for a single Palate. POST the same path with JSON-RPC MCP requests to list or call tools.", "security": [ {}, { "PrivyBearer": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "MCP tools for channel listing, quotes, and paid queries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpManifest" } } } }, "404": { "description": "Unknown Palate or private Palate without authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": ["MCP"], "summary": "Call per-Palate MCP tools", "description": "Accepts MCP-style JSON-RPC requests. Use tools/list to inspect tools, tools/call with palate_list_channels, palate_quote, or palate_query, or call those tool names directly as method values.", "security": [ {}, { "PrivyBearer": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRequest" }, "examples": { "toolsList": { "summary": "List tools", "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } }, "quote": { "summary": "Quote via tools/call", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "palate_quote", "arguments": { "query": "What is the expert's view on founder-led culture?", "mode": "synthesized" } } } }, "query": { "summary": "Paid query via direct method", "value": { "jsonrpc": "2.0", "id": 3, "method": "palate_query", "params": { "query": "What is the expert's view on founder-led culture?", "mode": "synthesized", "paymentProof": { "rail": "x402_base", "quoteNonce": "quote-nonce-from-quote-response", "facilitatorReceipt": "receipt_...", "walletAddress": "0x..." } } } } } } } }, "responses": { "200": { "description": "MCP JSON-RPC response. Tool errors are returned in JSON-RPC error fields or as tools/call results with isError=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpResponse" } } } }, "404": { "description": "Unknown Palate or private Palate without authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }