{
  "openapi": "3.1.0",
  "info": {
    "title": "Dosricke Agent Commerce API",
    "version": "1.0.0",
    "description": "Public service discovery and commercial-terms API for Dosricke Ventures Pvt. Ltd. Prices expose INR major units and exact paise minor-unit fields. No endpoint creates a payment; final action is a contact handoff."
  },
  "servers": [{ "url": "https://agent.dosricke.ventures" }],
  "security": [],
  "tags": [{ "name": "Services" }, { "name": "Offers" }],
  "paths": {
    "/agents/": { "get": { "tags": ["Services"], "summary": "Open assistant service discovery instructions", "x-read-only": true, "x-state-change": false, "x-financial-commitment": false, "responses": { "200": { "description": "Server-rendered discovery form", "content": { "text/html": {} } } } } },
    "/agent/interest": { "get": { "tags": ["Services"], "summary": "Contact Dosricke about a service", "x-read-only": true, "x-state-change": false, "x-financial-commitment": false, "parameters": [{ "name": "sku", "in": "query", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Contact handoff page", "content": { "text/html": {} } }, "404": { "$ref": "#/components/responses/Error" } } } },
    "/agent": {
      "get": {
        "tags": ["Products"], "summary": "Search merchant products through server-rendered HTML", "operationId": "searchProductsHtml",
        "description": "Primary compatibility interface. Works through ordinary navigation without JavaScript, cookies, authentication or custom headers.",
        "x-read-only": true, "x-state-change": false, "x-financial-commitment": false,
        "parameters": [
          { "name": "query", "in": "query", "schema": { "type": "string", "maxLength": 240 } },
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "color", "in": "query", "schema": { "type": "string" } },
          { "name": "min_price", "in": "query", "schema": { "type": "number", "minimum": 0 } },
          { "name": "max_price", "in": "query", "schema": { "type": "number", "minimum": 0 } },
          { "name": "count", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } },
          { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["raw", "ranked"], "default": "raw" } }
        ],
        "responses": { "200": { "description": "Semantic HTML candidate set", "content": { "text/html": {} } }, "400": { "description": "Semantic HTML parameter error" }, "429": { "description": "Rate limit reached" } }
      }
    },
    "/api/agent/products": {
      "get": {
        "tags": ["Products"], "summary": "Search products", "operationId": "searchProducts",
        "x-read-only": true, "x-state-change": false, "x-financial-commitment": false, "x-user-confirmation-required": false, "x-reversible": true,
        "parameters": [
          { "$ref": "#/components/parameters/AgentName" }, { "$ref": "#/components/parameters/AgentVersion" }, { "$ref": "#/components/parameters/AgentSession" },
          { "$ref": "#/components/parameters/Category" }, { "$ref": "#/components/parameters/MaxPrice" }, { "$ref": "#/components/parameters/Availability" }, { "$ref": "#/components/parameters/Query" }, { "$ref": "#/components/parameters/DeliveryPostcode" }
        ],
        "responses": { "200": { "description": "Matching products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSearchResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/agent/products/{sku}": {
      "get": {
        "tags": ["Products"], "summary": "Get product details", "operationId": "getProduct", "x-read-only": true, "x-state-change": false, "x-financial-commitment": false, "x-user-confirmation-required": false, "x-reversible": true,
        "parameters": [{ "$ref": "#/components/parameters/AgentName" }, { "$ref": "#/components/parameters/AgentVersion" }, { "$ref": "#/components/parameters/AgentSession" }, { "$ref": "#/components/parameters/Sku" }, { "$ref": "#/components/parameters/DeliveryPostcode" }],
        "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailsResponse" } } } }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/agent/quote": {
      "post": {
        "tags": ["Offers"], "summary": "Request an expiring offer", "operationId": "requestQuote", "x-read-only": false, "x-state-change": true, "x-financial-commitment": false, "x-user-confirmation-required": false, "x-reversible": true,
        "parameters": [{ "$ref": "#/components/parameters/AgentName" }, { "$ref": "#/components/parameters/AgentVersion" }, { "$ref": "#/components/parameters/AgentSession" }], "requestBody": { "$ref": "#/components/requestBodies/QuoteRequest" },
        "responses": { "201": { "$ref": "#/components/responses/Offer" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/agent/negotiate": {
      "post": {
        "tags": ["Offers"], "summary": "Negotiate an offer", "operationId": "negotiateOffer", "x-read-only": false, "x-state-change": true, "x-financial-commitment": false, "x-user-confirmation-required": false, "x-reversible": true,
        "parameters": [{ "$ref": "#/components/parameters/AgentName" }, { "$ref": "#/components/parameters/AgentVersion" }, { "$ref": "#/components/parameters/AgentSession" }], "requestBody": { "$ref": "#/components/requestBodies/NegotiateRequest" },
        "responses": { "200": { "$ref": "#/components/responses/Offer" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/agent/hold": {
      "post": {
        "tags": ["Offers"], "summary": "Place a temporary hold", "operationId": "holdOffer", "x-read-only": false, "x-state-change": true, "x-financial-commitment": false, "x-user-confirmation-required": false, "x-reversible": true,
        "parameters": [{ "$ref": "#/components/parameters/AgentName" }, { "$ref": "#/components/parameters/AgentVersion" }, { "$ref": "#/components/parameters/AgentSession" }], "requestBody": { "$ref": "#/components/requestBodies/QuoteIdRequest" },
        "responses": { "201": { "$ref": "#/components/responses/Hold" }, "200": { "$ref": "#/components/responses/Hold" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "410": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/api/agent/offers/{quote_id}": {
      "get": {
        "tags": ["Offers"], "summary": "Verify an offer", "operationId": "verifyOffer", "x-read-only": true, "x-state-change": false, "x-financial-commitment": false, "x-user-confirmation-required": false, "x-reversible": true,
        "parameters": [{ "$ref": "#/components/parameters/AgentName" }, { "$ref": "#/components/parameters/AgentVersion" }, { "$ref": "#/components/parameters/AgentSession" }, { "$ref": "#/components/parameters/QuoteId" }],
        "responses": { "200": { "$ref": "#/components/responses/Offer" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    }
  },
  "components": {
    "parameters": {
      "AgentName": { "name": "Agent-Name", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 80 } },
      "AgentVersion": { "name": "Agent-Version", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 40 } },
      "AgentSession": { "name": "X-Agent-Session-ID", "in": "header", "required": false, "description": "Opaque session ID; do not include personal information.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$" } },
      "Sku": { "name": "sku", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 40 } },
      "QuoteId": { "name": "quote_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 160 } },
      "Category": { "name": "category", "in": "query", "schema": { "type": "string" } }, "MaxPrice": { "name": "max_price", "in": "query", "description": "Maximum INR major-unit price (0–10000000).", "schema": { "type": "number", "minimum": 0, "maximum": 10000000 } }, "Availability": { "name": "availability", "in": "query", "schema": { "type": "string", "enum": ["in_stock"] } }, "Query": { "name": "query", "in": "query", "schema": { "type": "string" } }, "DeliveryPostcode": { "name": "delivery_postcode", "in": "query", "schema": { "type": "string", "pattern": "^\\d{6}$" } }
    },
    "requestBodies": {
      "QuoteRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } },
      "NegotiateRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NegotiateRequest" } } } },
      "QuoteIdRequest": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteIdRequest" } } } }
    },
    "responses": {
      "Error": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
      "Offer": { "description": "Offer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferResponse" } } } },
      "Hold": { "description": "Temporary hold", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoldResponse" } } } }
    },
    "schemas": {
      "Envelope": { "type": "object", "required": ["schema_version", "generated_at", "merchant"], "properties": { "schema_version": { "type": "string", "const": "1.0" }, "generated_at": { "type": "string", "format": "date-time" }, "merchant": { "type": "string" } } },
      "Money": { "type": "object", "description": "INR amount in major units and exact paise minor units.", "properties": { "price": { "type": "number" }, "price_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "const": "INR" } } },
      "DeliveryEstimate": { "type": "object", "properties": { "earliest": { "type": "string", "format": "date" }, "latest": { "type": "string", "format": "date" }, "days": { "type": "integer" }, "confidence": { "type": "number" }, "same_day": { "type": "boolean" } } },
      "Product": { "allOf": [{ "$ref": "#/components/schemas/Money" }, { "type": "object", "required": ["sku", "name", "variant", "category", "product_type", "billing_period", "price_basis", "availability", "implementation_days", "capacity", "support_sla", "cancellation", "tax", "transaction_mode", "financial_commitment"], "properties": { "sku": { "type": "string" }, "name": { "type": "string" }, "variant": { "type": "string" }, "category": { "type": "string" }, "product_type": { "type": "string", "enum": ["service", "subscription"] }, "billing_period": { "type": "string" }, "price_basis": { "type": "string" }, "effective_monthly_price": { "type": ["number", "null"] }, "effective_monthly_price_minor": { "type": ["integer", "null"] }, "availability": { "const": "accepting_interest" }, "implementation_days": { "type": "integer" }, "capacity": { "type": "string" }, "support_sla": { "type": "string" }, "cancellation": { "type": "string" }, "tax": { "type": "string" }, "negotiable": { "type": "boolean" }, "transaction_mode": { "const": "contact_handoff" }, "financial_commitment": { "const": false }, "interest_url": { "type": "string" }, "product_url": { "type": "string" }, "agent_quote_url": { "type": ["string", "null"] } } }] },
      "ProductSearchResponse": { "allOf": [{ "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": ["status", "count", "products", "transaction_mode", "financial_commitment"], "properties": { "status": { "const": "ok" }, "transaction_mode": { "const": "contact_handoff" }, "financial_commitment": { "const": false }, "count": { "type": "integer" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }] },
      "ProductDetailsResponse": { "allOf": [{ "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": ["status", "transaction_mode", "financial_commitment", "product"], "properties": { "status": { "const": "ok" }, "transaction_mode": { "const": "contact_handoff" }, "financial_commitment": { "const": false }, "product": { "allOf": [{ "$ref": "#/components/schemas/Product" }, { "type": "object", "properties": { "description": { "type": "string" }, "specifications": { "type": "object", "additionalProperties": true }, "implementation_days": { "type": "integer" }, "capacity": { "type": "string" }, "support_sla": { "type": "string" }, "cancellation": { "type": "string" }, "tax": { "type": "string" }, "interest_url": { "type": "string" }, "human_confirmation_required": { "type": "boolean" }, "merchant": { "type": "object" } } }] } } }] },
      "QuoteIdRequest": { "type": "object", "required": ["quote_id"], "properties": { "quote_id": { "type": "string", "maxLength": 160 } }, "additionalProperties": false },
      "QuoteRequest": { "type": "object", "required": ["sku", "delivery_postcode"], "properties": { "sku": { "type": "string", "maxLength": 40 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 }, "delivery_postcode": { "type": "string", "pattern": "^\\d{6}$" }, "budget": { "type": "number", "minimum": 0, "description": "INR major units." }, "budget_minor": { "type": "integer", "minimum": 0 }, "priorities": { "type": "object", "additionalProperties": true } }, "additionalProperties": false },
      "NegotiateRequest": { "type": "object", "required": ["quote_id", "request"], "properties": { "quote_id": { "type": "string" }, "request": { "type": "object", "oneOf": [{ "required": ["target_price"] }, { "required": ["target_price_minor"] }], "properties": { "target_price": { "type": "number", "minimum": 0, "description": "INR major units." }, "target_price_minor": { "type": "integer", "minimum": 0, "description": "Exact integer paise." }, "tradeoffs": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } }, "additionalProperties": false },
      "OfferResponse": { "allOf": [{ "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": ["transaction_mode", "financial_commitment", "interest_url"], "properties": { "status": { "type": "string" }, "transaction_mode": { "const": "contact_handoff" }, "financial_commitment": { "const": false }, "quote_id": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "integer" }, "standard_price": { "type": "number" }, "standard_price_minor": { "type": "integer" }, "offer_price": { "type": "number" }, "offer_price_minor": { "type": "integer" }, "total_price": { "type": "number" }, "total_price_minor": { "type": "integer" }, "currency": { "const": "INR" }, "billing_period": { "type": "string" }, "price_basis": { "type": "string" }, "effective_monthly_price": { "type": ["number", "null"] }, "implementation_days": { "type": "integer" }, "capacity": { "type": "string" }, "support_sla": { "type": "string" }, "cancellation": { "type": "string" }, "tax": { "type": "string" }, "offer_expiry": { "type": "string", "format": "date-time" }, "negotiable": { "type": "boolean" }, "interest_url": { "type": "string" }, "human_confirmation_required": { "type": "boolean" }, "negotiation_round": { "type": "integer" }, "reason": { "type": "string" }, "verify_url": { "type": "string" }, "negotiation_status": { "type": "string" } } }] },
      "HoldResponse": { "allOf": [{ "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "status": { "type": "string" }, "quote_id": { "type": "string" }, "hold_id": { "type": "string" }, "hold_expires_at": { "type": "string", "format": "date-time" }, "payment_created": { "const": false }, "financial_commitment": { "const": false }, "reversible": { "const": true } } }] },
      "ErrorResponse": { "allOf": [{ "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": ["status", "error_code", "reason"], "properties": { "status": { "const": "error" }, "error_code": { "type": "string" }, "reason": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }] }
    }
  }
}