{ "openapi": "3.1.0", "info": { "title": "VOLT Agent + Catalog API", "version": "1.0.0", "description": "VOLT is a fictional demo storefront (staging, sandbox only — no real payment, no fulfilled orders). This document describes BOTH the public session API and the authenticated agent API. The API itself is VOLT-specific (SPEC-RESEARCH bucket (c)); OpenAPI 3.x is the standard description format. Agent auth uses VOLT demo API keys (bucket (c)) — not OAuth 2.1. Agent checkout is PREPARATION only (bucket (b) experimental adapter): no endpoint or scope can confirm a checkout session; completion is by a human in the browser. CLIENT REQUIREMENT: send a descriptive User-Agent header identifying your client on every request — default signatures of some HTTP libraries (notably Python-urllib) are blocked by this host's edge bot protection (Cloudflare error 1010) before the request reaches the store. COMPATIBILITY SEQUENCING: when an item depends on another product, verify the pair with the compatibility operation BEFORE adding the dependent item to a cart; add in dependency order, primary product first." }, "servers": [ { "url": "https://volt.webventureslab.com/api/v1" } ], "x-mcp-server": { "endpoint": "https://volt.webventureslab.com/mcp", "transport": "streamable-http", "methods": [ "POST" ], "protocol_versions": [ "2025-11-25 (initialize handshake era)", "2026-07-28 (stateless: server/discover + tools)" ], "auth": "The same VOLT demo agent Bearer keys and scopes as the agent API (bucket (c) VOLT-specific — NOT OAuth 2.1). tools/call requires a key; tools/list without a key lists the read-only tools.", "tools": [ "search_products", "get_product", "check_availability", "compare_products", "check_compatibility", "create_cart", "add_to_cart", "update_cart_item", "remove_cart_item", "get_cart", "prepare_checkout", "create_handoff" ], "note": "The MCP endpoint lives at the origin root, outside this document's /api/v1 server base, so it is declared as an extension rather than a path. Tools mirror the /agent/* operations 1:1 and call the same shared commerce functions. No confirm/pay tool exists." }, "tags": [ { "name": "discovery", "description": "Public discovery" }, { "name": "catalog", "description": "Public catalog (session not required for reads)" }, { "name": "commerce", "description": "Public session-bound sandbox commerce" }, { "name": "agent-catalog", "description": "Agent catalog reads — scope catalog:read" }, { "name": "agent-cart", "description": "Agent carts — scope cart:write" }, { "name": "agent-checkout", "description": "Agent checkout preparation — scope checkout:prepare. No confirm operation exists." }, { "name": "agent-authorization", "description": "Self-service agent key issuance (build .54): request → approval code emailed to the customer → customer approval page + code → one-time claim. VOLT-specific (bucket (c)) — not OAuth 2.1." } ], "paths": { "/": { "get": { "tags": [ "discovery" ], "summary": "Discovery document (this API's index, incl. the agent section)", "responses": { "200": { "description": "Discovery document", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/openapi.json": { "get": { "tags": [ "discovery" ], "summary": "This OpenAPI document", "responses": { "200": { "description": "OpenAPI document", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/categories": { "get": { "tags": [ "catalog" ], "summary": "Categories with product counts", "responses": { "200": { "description": "Categories", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products": { "get": { "tags": [ "catalog" ], "summary": "List products (VOLT-TX-* test fixtures are always excluded)", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products/{sku}": { "get": { "tags": [ "catalog" ], "summary": "Product details incl. specs, relations, policies", "parameters": [ { "$ref": "#/components/parameters/Sku" } ], "responses": { "200": { "description": "Product detail", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products/{sku}/specs": { "get": { "tags": [ "catalog" ], "summary": "Product specifications only", "parameters": [ { "$ref": "#/components/parameters/Sku" } ], "responses": { "200": { "description": "Specs", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search": { "get": { "tags": [ "catalog" ], "summary": "Search products (q, category, sort, max_price_cents, in_stock=1, f_{spec_key}_min= / f_{spec_key}= facets)", "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/compare": { "get": { "tags": [ "catalog" ], "summary": "Spec matrix for 1–3 SKUs (?skus=a,b,c)", "responses": { "200": { "description": "Comparison", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/compatibility": { "get": { "tags": [ "catalog" ], "summary": "Compatibility verdict for two SKUs (?a=&b=) — derived only from recorded relations/specs, never guessed", "responses": { "200": { "description": "Verdict", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cart": { "get": { "tags": [ "commerce" ], "summary": "Session cart view (totals recomputed from current catalog prices)", "security": [ { "VoltSession": [] } ], "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartView" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cart/items": { "post": { "tags": [ "commerce" ], "summary": "Add an item {sku, qty}", "security": [ { "VoltSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sku", "qty" ], "properties": { "sku": { "type": "string" }, "qty": { "type": "integer", "minimum": 1, "maximum": 99 } } } } } }, "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartView" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cart/items/{sku}": { "patch": { "tags": [ "commerce" ], "summary": "Set a cart line quantity {qty} (0 removes)", "security": [ { "VoltSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/Sku" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartView" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "commerce" ], "summary": "Remove a cart line", "security": [ { "VoltSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/Sku" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartView" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkout/sessions": { "post": { "tags": [ "commerce" ], "summary": "Create a sandbox checkout session from the session cart {shipping, ship_method}", "security": [ { "VoltSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Checkout session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionWrap" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkout/sessions/{id}": { "get": { "tags": [ "commerce" ], "summary": "Read an owned checkout session", "security": [ { "VoltSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionWrap" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkout/sessions/{id}/confirm": { "post": { "tags": [ "commerce" ], "summary": "HUMAN/session-only sandbox confirm {outcome: success|declined}. Not reachable by agent keys (sessions are bound to the owning session hash).", "security": [ { "VoltSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Order created", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkout/sessions/{id}/cancel": { "post": { "tags": [ "commerce" ], "summary": "Cancel an owned open checkout session", "security": [ { "VoltSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Checkout session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionWrap" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{order_number}": { "get": { "tags": [ "commerce" ], "summary": "Read an owned order", "security": [ { "VoltSession": [] } ], "parameters": [ { "name": "order_number", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/acp/feed": { "get": { "tags": [ "discovery" ], "summary": "ACP-format product feed export (spec-conformant artifact; OpenAI ingestion requires approved merchant onboarding — not claimed). Generated from live D1 at request time: one row per product with the nine required fields of OpenAI's Product Feed Spec (item_id, title, description, url, brand, seller_name, image_url, availability, price as a major-unit string like '79.99 USD'). ?format=jsonl (default) | csv | json. Public, no auth. VOLT-TX-* fixtures excluded.", "responses": { "200": { "description": "ACP-format feed (JSONL default)", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/search": { "get": { "tags": [ "agent-catalog" ], "summary": "Agent search — same engine and parameters as /search. Scope: catalog:read.", "security": [ { "AgentBearer": [] } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/products/{sku}": { "get": { "tags": [ "agent-catalog" ], "summary": "Agent product details + specs. Scope: catalog:read.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Sku" } ], "responses": { "200": { "description": "Product detail", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/products/{sku}/availability": { "get": { "tags": [ "agent-catalog" ], "summary": "Agent availability for one SKU {sku, stock:{status, available}}. Scope: catalog:read.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Sku" } ], "responses": { "200": { "description": "Availability", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/compare": { "get": { "tags": [ "agent-catalog" ], "summary": "Agent compare (?skus=a,b,c). Scope: catalog:read.", "security": [ { "AgentBearer": [] } ], "responses": { "200": { "description": "Comparison", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/compatibility": { "get": { "tags": [ "agent-catalog" ], "summary": "Agent compatibility (?a=&b=). Scope: catalog:read.", "security": [ { "AgentBearer": [] } ], "responses": { "200": { "description": "Verdict", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/carts": { "post": { "tags": [ "agent-cart" ], "summary": "Create (or return) the agent's own cart. Scope: cart:write.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartView" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/carts/{cart_id}": { "get": { "tags": [ "agent-cart" ], "summary": "Inspect the agent's own cart (another agent's cart id returns 404). Scope: cart:write.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartView" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/carts/{cart_id}/items": { "post": { "tags": [ "agent-cart" ], "summary": "Add an item {sku, qty} to the agent's cart. Scope: cart:write.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sku", "qty" ], "properties": { "sku": { "type": "string" }, "qty": { "type": "integer", "minimum": 1, "maximum": 99 } } } } } }, "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartView" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/carts/{cart_id}/items/{sku}": { "patch": { "tags": [ "agent-cart" ], "summary": "Set quantity {qty} (0 removes). Scope: cart:write.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Sku" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartView" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "agent-cart" ], "summary": "Remove a line. Scope: cart:write.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Sku" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartView" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/carts/{cart_id}/checkout-prepare": { "post": { "tags": [ "agent-checkout" ], "summary": "PREPARE a sandbox checkout session from the agent's cart (shared createCheckoutSession; server-computed totals). Optional {shipping, ship_method}; a documented demonstration shipping address is used when shipping is omitted. The session can only be completed by a human in the browser — there is NO agent confirm operation. Replay of the same Idempotency-Key returns the original session without creating a new one. Scope: checkout:prepare.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "name": "cart_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Prepared checkout session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionWrap" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/checkout-sessions/{checkout_session_id}/handoff": { "post": { "tags": [ "agent-checkout" ], "summary": "Create the Stage 4 human handoff for a prepared checkout session: mints a single-use bearer token (15-minute life, capped at the session expiry) and returns it ONCE with handoff.handoff_url (an ABSOLUTE URL, /handoff/{token} on this origin). Only the token SHA-256 hash is stored — the returned token is deterministically re-derived from the agent's credential on an idempotent replay and verified against the stored hash, never persisted. The customer opens the URL, sees the order re-priced from the live catalog, and approves or cancels on that page — approval (never an agent call) creates the simulated order via the shared checkout engine. IDEMPOTENT (build .50): replaying the same Idempotency-Key returns the EXISTING pending handoff — HTTP 200, the same handoff_url, token_returned: true, replayed: true — instead of minting a replacement. A mint with a different or no key supersedes any pending handoff for the same session, as before. Scope: checkout:prepare.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "name": "checkout_session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Idempotent replay: the existing handoff, same URL, token_returned: true", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Handoff created (raw token returned once)", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/handoffs": { "post": { "tags": [ "agent-checkout" ], "summary": "Alias of the handoff creation above, naming the session in the body: {checkout_session_id}. Same idempotent-replay semantics. Scope: checkout:prepare.", "security": [ { "AgentBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Idempotent replay: the existing handoff, same URL, token_returned: true", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Handoff created (raw token returned once)", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/keys/request": { "post": { "tags": [ "agent-authorization" ], "summary": "SELF-SERVICE KEY REQUEST (public, unauthenticated — this is the credential bootstrap). Body: {scopes: non-empty subset of [catalog:read, cart:write, checkout:prepare], label: human-readable purpose shown to the customer verbatim, agent_name?: string}. Any other scope — including anything confirm-shaped — is refused at request time (400 scope_not_available); no other scopes exist. Response 201: {request_id, approval_url, claim_token, expires_at, state:'pending', approval_email:'sent'}. The claim token (256-bit) is returned once; only its SHA-256 hash is stored. Pending requests expire in 15 minutes. APPROVAL CODE: creating a request emails a 6-digit approval code to the store's customer-contact email address; only its SHA-256 hash is stored and the code NEVER appears in any API response. The customer must enter that code on the approval page to approve or deny — an agent holding only the approval_url cannot approve its own request, and 5 incorrect code entries lock the request (terminal state 'locked'). If the approval email cannot be sent, creation fails closed: 502 approval_email_failed and the request is terminal (state 'email_failed'). Rate limits: per-IP creation limit + a global pending cap; bursts get structured 429s. Next: give approval_url to the customer (GET /agent-authorize/{request_id} — an HTML page, not part of this API document), then poll the claim operation.", "responses": { "201": { "description": "Request created (claim token returned once; approval code emailed to the customer, never returned)", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/keys/claim": { "get": { "tags": [ "agent-authorization" ], "summary": "CLAIM a self-service key (public; authenticated by the claim token, sent as Authorization: Bearer or the X-Claim-Token header). Query: ?request_id={id}. Before approval: 200 {state:'pending', expires_at}. After denial/expiry/lock/email-failure: 200 {state:'denied'|'expired'|'locked'|'email_failed'} (terminal). After approval: 200 {state:'approved', api_key, key_id, scopes, expires_at} returned EXACTLY ONCE with Cache-Control: no-store — the held raw key is wiped in the same operation. A second claim returns 200 {state:'claimed'} with no key material. Self-service keys live 7 days, use the same scopes/rate limits/revocation as operator-issued keys, and are recorded with source 'self_service'.", "parameters": [ { "name": "request_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Claim state, or the one-time key payload", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "AgentBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "VOLT agent key", "description": "VOLT demo API key (bucket (c) VOLT-specific — not OAuth 2.1). Format: volt_ak_<12 hex>_<48 hex>. Issued by the store operator OR self-service after customer approval (POST /agent/keys/request → approval page → GET /agent/keys/claim); only its SHA-256 hash is stored and the issuance source is recorded. Scopes: catalog:read, cart:write, checkout:prepare. No confirm scope exists." }, "VoltSession": { "type": "apiKey", "in": "header", "name": "X-Volt-Session", "description": "Browser session token (64 hex chars) or the volt_session cookie. Carts/orders/checkout sessions are bound to the SHA-256 hash of this token." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on all mutations. First execution's response is stored per (identity, scope, key); replays return it without re-executing." }, "Sku": { "name": "sku", "in": "path", "required": true, "schema": { "type": "string" } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Machine-readable error code" }, "detail": { "type": "string" }, "required_scope": { "type": "string" }, "retry_after": { "type": "integer" } } }, "ProductSummary": { "type": "object", "properties": { "sku": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "string" }, "category": { "type": "string" }, "kind": { "type": "string" }, "flagship": { "type": "boolean" }, "tagline": { "type": "string" }, "price_cents": { "type": "integer" }, "price": { "type": "string" }, "compare_at_cents": { "type": [ "integer", "null" ] }, "stock": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "in_stock", "low_stock", "out_of_stock" ] }, "available": { "type": "integer" } } }, "url": { "type": "string" }, "image": { "type": "string" } } }, "ProductList": { "type": "object", "properties": { "count": { "type": "integer" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } } }, "CartView": { "type": "object", "properties": { "cart_id": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object" } }, "item_count": { "type": "integer" }, "subtotal_cents": { "type": "integer" }, "shipping_cents": { "type": "integer" }, "total_cents": { "type": "integer" } } }, "CheckoutSession": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "confirming", "confirmed", "cancelled", "expired" ] }, "ship_method": { "type": "string" }, "subtotal_cents": { "type": "integer" }, "shipping_cents": { "type": "integer" }, "total_cents": { "type": "integer" }, "expires_at": { "type": "integer" }, "order_number": { "type": [ "string", "null" ] } } }, "CheckoutSessionWrap": { "type": "object", "properties": { "checkout_session": { "$ref": "#/components/schemas/CheckoutSession" }, "session": { "$ref": "#/components/schemas/CheckoutSession" } } } } } }