{ "openapi": "3.1.0", "info": { "title": "Arete Diamond — Agent & Commerce API", "version": "1.1.0", "description": "Machine-readable index of public feeds and agentic surfaces. Two credentials are accepted interchangeably: an opaque `ak_` API key (`Authorization: Bearer ak_…`) and a short-lived JWT minted at /oauth/token. Reads are open; a credential raises rate limits and, when operator-granted, unlocks agentic checkout. See /.well-known/api-catalog and /auth.md for discovery and onboarding." }, "servers": [ { "url": "https://aretediamond.cz" } ], "paths": { "/feeds/chatgpt/products": { "get": { "summary": "ChatGPT / OpenAI Commerce product feed", "description": "Retail-only product feed (jewellery variants by default; a page of loose diamonds when `gem_type` is set). Open; b2c1 retail pricing, assets via the media proxy, never cost/supplier.", "operationId": "chatgptProductFeed", "security": [ {}, { "apiKeyBearer": [] }, { "oauthJwt": [ "read" ] } ], "parameters": [ { "name": "country", "in": "query", "required": false, "description": "Market for currency + VAT (ISO-3166 alpha-2). Default CZ.", "schema": { "type": "string", "default": "CZ", "example": "DE" } }, { "name": "locale", "in": "query", "required": false, "description": "Translation + URL locale; also selects the canonical .cz/.com host for product deep-links. Default en.", "schema": { "type": "string", "default": "en", "example": "cs" } }, { "name": "gem_type", "in": "query", "required": false, "description": "When set, returns a paginated page of loose diamonds of this family instead of jewellery.", "schema": { "type": "string", "enum": [ "natural-white", "natural-colored", "labgrown-white", "labgrown-colored" ] } }, { "name": "page", "in": "query", "required": false, "description": "Diamond page index (100 stones/page); only meaningful with `gem_type`.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "format", "in": "query", "required": false, "description": "`json` = official OpenAI Product array (default); `ndjson` = newline-delimited; `rich` = enriched agent envelope (only when the feed_rich flag is on, else falls back to json).", "schema": { "type": "string", "enum": [ "json", "ndjson", "rich" ], "default": "json" } } ], "responses": { "200": { "description": "Product feed", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } }, "application/x-ndjson": { "schema": { "type": "string" } } } } } } }, "/feeds/merchant-center/{market}": { "get": { "summary": "Google Merchant Center RSS feed", "operationId": "merchantCenterFeed", "security": [ {}, { "apiKeyBearer": [] }, { "oauthJwt": [ "read" ] } ], "parameters": [ { "name": "market", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "cz", "sk", "de", "gb" ] } } ], "responses": { "200": { "description": "RSS 2.0 XML feed", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/feeds/heureka/cz": { "get": { "summary": "Heureka.cz product XML feed", "operationId": "heurekaCzFeed", "security": [ {}, { "apiKeyBearer": [] }, { "oauthJwt": [ "read" ] } ], "responses": { "200": { "description": "Heureka SHOP XML", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/feeds/sklik/cz": { "get": { "summary": "Sklik / Zboží.cz jewellery product XML feed (CZ-only)", "description": "Active configurable jewellery models expanded over the metal×purity×center-gem matrix, one SHOPITEM per variant. b2c1 retail CZK incl. VAT; imagery proxied, never cost/supplier.", "operationId": "sklikCzJewelleryFeed", "security": [ {}, { "apiKeyBearer": [] }, { "oauthJwt": [ "read" ] } ], "responses": { "200": { "description": "Zboží SHOP XML", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/feeds/sklik/cz/diamonds/{origin}": { "get": { "summary": "Sklik loose-diamond feed page index (CZ-only)", "description": "Plain-text list of the paginated Sklik diamond feed page URLs + stone count, for registering each page as a scheduled-fetch feed.", "operationId": "sklikCzDiamondFeedIndex", "security": [ {}, { "apiKeyBearer": [] }, { "oauthJwt": [ "read" ] } ], "parameters": [ { "name": "origin", "in": "path", "required": true, "description": "Diamond origin — separate feeds for independent bidding.", "schema": { "type": "string", "enum": [ "natural", "lab" ] } } ], "responses": { "200": { "description": "Plain-text page-URL index", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/feeds/sklik/cz/diamonds/{origin}/{page}": { "get": { "summary": "Sklik loose-diamond XML feed page (CZ-only)", "description": "One paginated page of loose diamonds in Sklik/Zboží SHOP XML. b2c1 retail CZK incl. VAT, identical to the diamond PDP; cost columns never emitted.", "operationId": "sklikCzDiamondFeedPage", "security": [ {}, { "apiKeyBearer": [] }, { "oauthJwt": [ "read" ] } ], "parameters": [ { "name": "origin", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "natural", "lab" ] } }, { "name": "page", "in": "path", "required": true, "description": "1-based page index (see the origin index for the page count).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sklik SHOP XML", "content": { "application/xml": { "schema": { "type": "string" } } } }, "503": { "description": "Price cache warming / transient — retry (Retry-After)." } } } }, "/feeds/merchant-center/{market}/diamonds/{origin}": { "get": { "summary": "Google Merchant Center loose-diamond feed page index", "description": "Plain-text list of the paginated GMC diamond feed page URLs + stone count, for registering each page as a scheduled-fetch feed.", "operationId": "merchantCenterDiamondFeedIndex", "security": [ {}, { "apiKeyBearer": [] }, { "oauthJwt": [ "read" ] } ], "parameters": [ { "name": "market", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "cz", "sk", "de", "gb" ] } }, { "name": "origin", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "natural", "lab" ] } } ], "responses": { "200": { "description": "Plain-text page-URL index", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/feeds/merchant-center/{market}/diamonds/{origin}/{page}": { "get": { "summary": "Google Merchant Center loose-diamond RSS feed page", "description": "One paginated page of loose diamonds in GMC RSS 2.0. b2c1 retail margin → market currency (VAT-inclusive), identical to the diamond PDP; cost columns never emitted.", "operationId": "merchantCenterDiamondFeedPage", "security": [ {}, { "apiKeyBearer": [] }, { "oauthJwt": [ "read" ] } ], "parameters": [ { "name": "market", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "cz", "sk", "de", "gb" ] } }, { "name": "origin", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "natural", "lab" ] } }, { "name": "page", "in": "path", "required": true, "description": "1-based page index (see the origin index for the page count).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "RSS 2.0 XML feed", "content": { "application/xml": { "schema": { "type": "string" } } } }, "503": { "description": "Exchange rate unavailable / transient — retry (Retry-After)." } } } }, "/oauth/token": { "post": { "summary": "OAuth 2.0 client-credentials token", "description": "Exchange an `ak_` API key (client_secret) for a short-lived JWT. The token inherits the key's scope: `read` for self-service keys, `checkout` only for operator-granted keys.", "operationId": "oauthToken", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string", "description": "Your `ak_…` API key." }, "scope": { "type": "string", "enum": [ "read", "checkout" ] } } } } } }, "responses": { "200": { "description": "Access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer" }, "scope": { "type": "string" } } } } } }, "503": { "description": "Token exchange unavailable — no OAuth signing key provisioned." } } } }, "/acp/feed/diamonds": { "get": { "summary": "ACP diamond product feed", "operationId": "acpDiamondFeed", "security": [ {}, { "apiKeyBearer": [] }, { "oauthJwt": [ "read" ] } ], "responses": { "200": { "description": "JSON diamond feed", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/acp/checkout_sessions": { "post": { "summary": "Create ACP checkout session", "description": "Requires a trusted-tier credential (operator-issued `ak_` key or a `checkout`-scoped JWT) to reach `ready_for_payment`; other agents receive `not_ready_for_payment` with a signed `continue_url` into the human checkout. Payment itself is authorized by a separate buyer-approved payment token, never by an agent scope.", "operationId": "acpCreateCheckoutSession", "security": [ { "apiKeyBearer": [] }, { "oauthJwt": [ "checkout" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated idempotency key; replaying it returns the original session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpCreateCheckoutRequest" } } } }, "responses": { "200": { "description": "Existing session (idempotent replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpCheckoutSession" } } } }, "201": { "description": "Checkout session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpCheckoutSession" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "409": { "description": "Idempotency-Key reused with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } } } } }, "/acp/checkout_sessions/{id}": { "get": { "summary": "Retrieve an ACP checkout session", "operationId": "acpGetCheckoutSession", "security": [ { "apiKeyBearer": [] }, { "oauthJwt": [ "checkout" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checkout session id returned by create.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpCheckoutSession" } } } }, "404": { "description": "Unknown session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } } } } }, "/acp/checkout_sessions/{id}/cancel": { "post": { "summary": "Cancel an ACP checkout session", "operationId": "acpCancelCheckoutSession", "security": [ { "apiKeyBearer": [] }, { "oauthJwt": [ "checkout" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checkout session id returned by create.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session marked canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpCheckoutSession" } } } }, "404": { "description": "Unknown session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } } } } }, "/acp/checkout_sessions/{id}/complete": { "post": { "summary": "Complete an ACP checkout session", "description": "Finalize a `ready_for_payment` session with the buyer-approved payment token. Requires a trusted-tier credential (operator-issued `ak_` key or a `checkout`-scoped JWT) to reach `ready_for_payment`; other agents receive `not_ready_for_payment` with a signed `continue_url` into the human checkout. Payment itself is authorized by a separate buyer-approved payment token, never by an agent scope.", "operationId": "acpCompleteCheckoutSession", "security": [ { "apiKeyBearer": [] }, { "oauthJwt": [ "checkout" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checkout session id returned by create.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_data": { "type": "object", "description": "Buyer-approved, scoped, single-use payment token and provider metadata." } } } } } }, "responses": { "200": { "description": "Completed session (includes `order`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpCheckoutSession" } } } }, "400": { "description": "Not ready / payment declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } }, "404": { "description": "Unknown session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpError" } } } } } } }, "/mcp": { "post": { "summary": "Model Context Protocol JSON-RPC endpoint", "description": "JSON-RPC 2.0 transport for the arete-diamond MCP server (diamond search, detail lookup, jewellery options). Reads are open; a key/token raises rate limits and tier.", "operationId": "mcpJsonRpc", "security": [ {}, { "apiKeyBearer": [] }, { "oauthJwt": [ "read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "method": { "type": "string", "example": "tools/call" }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } } } } } } } } } }, "components": { "securitySchemes": { "apiKeyBearer": { "type": "http", "scheme": "bearer", "description": "An opaque `ak_`-prefixed API key sent as `Authorization: Bearer ak_…`. Self-service keys are read-scope; operator-issued keys carry the trusted checkout tier. Reads work without any key." }, "oauthJwt": { "type": "oauth2", "description": "A short-lived JWT obtained by exchanging an `ak_` key at /oauth/token. Accepted anywhere the `ak_` key is; the `checkout` scope is only issued for operator-granted keys.", "flows": { "clientCredentials": { "tokenUrl": "https://aretediamond.cz/oauth/token", "scopes": { "read": "Open catalogue, feeds, MCP search + higher rate limits", "checkout": "Agentic checkout tier (operator-granted keys only)" } } } } }, "schemas": { "AcpTotal": { "type": "object", "required": [ "type", "display_text", "amount" ], "properties": { "type": { "type": "string", "enum": [ "items_base_amount", "items_discount", "subtotal", "discount", "fulfillment", "tax", "fee", "total" ] }, "display_text": { "type": "string" }, "amount": { "type": "integer", "description": "Minor units (e.g. cents/haléře); major units for zero-decimal currencies." } } }, "AcpLineItem": { "type": "object", "required": [ "id", "item", "title", "base_amount", "discount", "subtotal", "tax", "total" ], "properties": { "id": { "type": "string" }, "item": { "type": "object", "required": [ "id", "quantity" ], "properties": { "id": { "type": "string" }, "quantity": { "type": "integer" } } }, "title": { "type": "string" }, "image_url": { "type": "string", "format": "uri", "description": "Proxied media URL — never a raw supplier host." }, "base_amount": { "type": "integer" }, "discount": { "type": "integer" }, "subtotal": { "type": "integer" }, "tax": { "type": "integer" }, "total": { "type": "integer" } } }, "AcpMessage": { "type": "object", "required": [ "type", "content_type", "content" ], "properties": { "type": { "type": "string", "enum": [ "info", "error" ] }, "code": { "type": "string" }, "param": { "type": "string", "description": "RFC-9535 JSONPath to the offending field." }, "content_type": { "type": "string", "enum": [ "plain", "markdown" ] }, "content": { "type": "string" } } }, "AcpLink": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "enum": [ "terms_of_use", "privacy_policy", "seller_shop_policies" ] }, "url": { "type": "string", "format": "uri" } } }, "AcpFulfillmentOption": { "type": "object", "required": [ "type", "id", "title", "subtotal", "tax", "total" ], "properties": { "type": { "type": "string", "enum": [ "shipping", "digital" ] }, "id": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "carrier": { "type": "string" }, "earliest_delivery_time": { "type": "string" }, "latest_delivery_time": { "type": "string" }, "subtotal": { "type": "integer" }, "tax": { "type": "integer" }, "total": { "type": "integer" } } }, "AcpCheckoutSession": { "type": "object", "required": [ "id", "status", "currency", "line_items", "totals" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "not_ready_for_payment", "ready_for_payment", "completed", "canceled" ] }, "currency": { "type": "string", "description": "ISO-4217, lowercase." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/AcpLineItem" } }, "fulfillment_options": { "type": "array", "items": { "$ref": "#/components/schemas/AcpFulfillmentOption" } }, "totals": { "type": "array", "items": { "$ref": "#/components/schemas/AcpTotal" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/AcpMessage" } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/AcpLink" } }, "payment_provider": { "type": "object", "properties": { "provider": { "type": "string", "example": "stripe" }, "supported_payment_methods": { "type": "array", "items": { "type": "string" } } } }, "buyer": { "type": "object" }, "fulfillment_address": { "type": "object" }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "permalink_url": { "type": "string", "format": "uri" } } } } }, "AcpCreateCheckoutRequest": { "type": "object", "required": [ "line_items" ], "properties": { "line_items": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Product/variant id from a feed or MCP search." }, "quantity": { "type": "integer", "minimum": 1, "default": 1 } } } }, "fulfillment_address": { "type": "object", "description": "Buyer shipping address; the country drives merchant-authoritative currency/VAT/FX." }, "buyer": { "type": "object" }, "context": { "type": "object" } } }, "AcpError": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request", "request_not_idempotent", "processing_error", "service_unavailable" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" } } } } } }