{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"SANIKB Public Agent API","version":"1.0.0","summary":"Read-only SANIKB product discovery and agent resources.","description":"Use this API when an agent needs to discover public SANIKB products, resolve a product handle, or read SANIKB's public MCP resources. Catalog calls are read-only and proxy only the fixed origin https://sanikb.com. This API does not place orders, expose customer data, or confirm negotiated commercial terms.","contact":{"name":"SANIKB","url":"https://sanikb.com/pages/contact"}},"servers":[{"url":"https://sanikb-agent-api.vercel.app","description":"Current SANIKB agent service"}],"externalDocs":{"description":"SANIKB developer guide","url":"https://sanikb-agent-api.vercel.app/developers"},"tags":[{"name":"Catalog","description":"Validated, cached, read-only public product data."},{"name":"Discovery","description":"Machine-readable API and MCP discovery documents."},{"name":"MCP","description":"Stateless Streamable HTTP endpoint supporting legacy initialization and MCP 2026-07-28 discovery."}],"paths":{"/api/catalog/products":{"get":{"tags":["Catalog"],"summary":"List public SANIKB products","description":"Returns one deterministic page of public storefront products. Use the returned handles with the product-detail operation.","operationId":"listCatalogProducts","x-agent-when-to-use":"Use first when the user has not supplied an exact, validated SANIKB product handle.","parameters":[{"name":"limit","in":"query","description":"Maximum products to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"page","in":"query","description":"One-based storefront page number.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1}}],"responses":{"200":{"description":"A page of public products.","headers":{"Cache-Control":{"description":"Shared-cache policy for public catalog data.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductListResponse"}}}},"400":{"description":"A query parameter is invalid or unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"405":{"description":"The HTTP method is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"The storefront returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"504":{"description":"The storefront did not respond before the timeout.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/catalog/products/{handle}":{"get":{"tags":["Catalog"],"summary":"Get one public SANIKB product","description":"Resolves an exact lowercase product handle. A missing product is a real HTTP 404 with a JSON recovery hint.","operationId":"getCatalogProductByHandle","x-agent-when-to-use":"Use after listCatalogProducts or when the user supplied an exact SANIKB handle.","parameters":[{"name":"handle","in":"path","required":true,"description":"Lowercase, hyphen-separated SANIKB storefront handle.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}}],"responses":{"200":{"description":"The requested public product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"description":"The product handle is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No public product has this handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"405":{"description":"The HTTP method is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"The storefront returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"504":{"description":"The storefront did not respond before the timeout.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/mcp":{"post":{"tags":["MCP"],"summary":"Send one MCP JSON-RPC message","description":"Stateless Streamable HTTP transport. Legacy clients may initialize using MCP 2025-11-25 or earlier. MCP 2026-07-28 clients use server/discover and per-request metadata headers. The server advertises resources only.","operationId":"sendMcpMessage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"One JSON-RPC result or error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"202":{"description":"A notification was accepted; the response has no body."},"400":{"description":"Malformed JSON-RPC or modern MCP metadata mismatch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"403":{"description":"The browser Origin is not trusted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"404":{"description":"A modern MCP method is not implemented.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"405":{"description":"Use HTTP POST for MCP messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}}}}},"/openapi.json":{"get":{"tags":["Discovery"],"summary":"Get this OpenAPI document","operationId":"getOpenApiDocument","responses":{"200":{"description":"OpenAPI 3.1 JSON document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/mcp/server-card.json":{"get":{"tags":["Discovery"],"summary":"Get the MCP discovery card","operationId":"getMcpServerCard","responses":{"200":{"description":"Experimental well-known discovery location using server.json fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServerCard"}}}}}}},"/developers":{"get":{"tags":["Discovery"],"summary":"Read the developer guide","operationId":"getDeveloperGuide","responses":{"200":{"description":"Server-rendered HTML developer guide.","content":{"text/html":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ErrorEnvelope":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"$ref":"#/components/schemas/Error"}},"example":{"error":{"code":"PRODUCT_NOT_FOUND","message":"No public SANIKB product was found for the requested handle.","resolution":"List products and retry with a returned handle."}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message","resolution"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Short human-readable description."},"resolution":{"type":"string","description":"Concrete recovery step for agents."},"details":{"type":"object","additionalProperties":true,"description":"Safe structured context; never contains credentials."}}},"ProductListResponse":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["products"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"ProductResponse":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["product"],"properties":{"product":{"$ref":"#/components/schemas/Product"}}},"meta":{"type":"object","additionalProperties":false,"required":["source"],"properties":{"source":{"type":"string","format":"uri"}}}}},"ListMeta":{"type":"object","additionalProperties":false,"required":["count","limit","page","source"],"properties":{"count":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":50},"page":{"type":"integer","minimum":1,"maximum":1000},"source":{"type":"string","format":"uri"}}},"Product":{"type":"object","additionalProperties":false,"required":["id","title","handle","url","descriptionHtml","vendor","productType","publishedAt","updatedAt","tags","variants","images"],"properties":{"id":{"type":["string","null"]},"title":{"type":["string","null"]},"handle":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"},"descriptionHtml":{"type":["string","null"]},"vendor":{"type":["string","null"]},"productType":{"type":["string","null"]},"publishedAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"tags":{"type":"array","items":{"type":"string"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/ProductImage"}}}},"ProductVariant":{"type":"object","additionalProperties":false,"required":["id","title","sku","price","compareAtPrice","available","position","options"],"properties":{"id":{"type":["string","null"]},"title":{"type":["string","null"]},"sku":{"type":["string","null"]},"price":{"type":["string","null"]},"compareAtPrice":{"type":["string","null"]},"available":{"type":["boolean","null"]},"position":{"type":["integer","null"]},"options":{"type":"array","items":{"type":"string"}}}},"ProductImage":{"type":"object","additionalProperties":false,"required":["id","src","alt","width","height","position"],"properties":{"id":{"type":["string","null"]},"src":{"type":["string","null"],"format":"uri"},"alt":{"type":["string","null"]},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"position":{"type":["integer","null"]}}},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"method":{"type":"string"},"params":{"type":"object","additionalProperties":true}},"additionalProperties":false},"JsonRpcResponse":{"type":"object","required":["jsonrpc","id"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"result":{"type":"object","additionalProperties":true},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true}},"additionalProperties":false}},"additionalProperties":false},"McpServerCard":{"type":"object","required":["$schema","name","description","version","remotes"],"properties":{"$schema":{"type":"string","format":"uri"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"websiteUrl":{"type":"string","format":"uri"},"remotes":{"type":"array","minItems":1,"items":{"type":"object","required":["type","url"],"properties":{"type":{"const":"streamable-http"},"url":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}}}}