{
  "openapi": "3.1.0",
  "info": {
    "title": "TechCore Agent-Native API",
    "version": "1.0.0",
    "description": "Read-only catalog API for AI agents to browse Tech Core products, categories, brands, and run searches. Write operations (cart, checkout) require an authenticated session and are intentionally excluded from the public agent surface."
  },
  "servers": [
    {
      "url": "https://techcore.pk",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/products": {
      "get": {
        "summary": "List products",
        "operationId": "listProducts",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
          { "name": "brand", "in": "query", "schema": { "type": "string" }, "description": "Brand slug" },
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Category slug; includes subcategories" },
          { "name": "min_price", "in": "query", "schema": { "type": "integer" } },
          { "name": "max_price", "in": "query", "schema": { "type": "integer" } },
          { "name": "condition", "in": "query", "schema": { "type": "string", "enum": ["new", "refurbished", "open_box", "used"] } }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of products",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductListResponse" }
              }
            }
          }
        }
      }
    },
    "/api/products/{slug}": {
      "get": {
        "summary": "Get a product by slug",
        "operationId": "getProduct",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Product detail with images, reviews, related items",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }
              }
            }
          },
          "404": { "description": "Product not found" }
        }
      }
    },
    "/api/categories": {
      "get": {
        "summary": "List all active categories",
        "operationId": "listCategories",
        "responses": {
          "200": {
            "description": "Flat list of categories",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CategoryListResponse" }
              }
            }
          }
        }
      }
    },
    "/api/brands": {
      "get": {
        "summary": "List all brands",
        "operationId": "listBrands",
        "responses": {
          "200": {
            "description": "Flat list of brands",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BrandListResponse" }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "summary": "Full-text product search",
        "operationId": "searchProducts",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "Paginated search results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductListResponse" }
              }
            }
          },
          "400": { "description": "Missing query parameter" }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "summary": "MCP server discovery",
        "operationId": "mcpDiscovery",
        "responses": {
          "200": {
            "description": "Server capabilities",
            "content": { "application/json": {} }
          }
        }
      },
      "post": {
        "summary": "MCP JSON-RPC-style tool invocation",
        "operationId": "mcpInvoke",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["method"],
                "properties": {
                  "method": { "type": "string", "enum": ["tools/list", "tools/call"] },
                  "params": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string" },
                      "arguments": { "type": "object" }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "MCP response" } }
      }
    },
    "/api/acp": {
      "get": {
        "summary": "ACP capability discovery",
        "operationId": "acpDiscovery",
        "responses": { "200": { "description": "ACP capability list" } }
      }
    },
    "/api/x402": {
      "get": {
        "summary": "x402 payment-gated endpoint",
        "operationId": "x402Probe",
        "x-payment-info": {
          "intent": "charge",
          "method": "tempo",
          "amount": "0.01",
          "currency": "USD"
        },
        "responses": {
          "200": { "description": "Proof accepted" },
          "402": { "description": "Payment required for agent access" }
        }
      }
    },
    "/api/checkout": {
      "post": {
        "summary": "Create checkout session",
        "operationId": "createCheckoutSession",
        "x-payment-info": {
          "intent": "session",
          "method": "stripe",
          "amount": "0.00",
          "currency": "PKR"
        },
        "responses": {
          "200": { "description": "Checkout created" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Money": {
        "type": "integer",
        "description": "Price in PKR (integer, no fractional unit)."
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "sku": { "type": "string" },
          "description": { "type": "string", "nullable": true },
          "price_pkr": { "$ref": "#/components/schemas/Money" },
          "compare_at_price_pkr": { "type": "integer", "nullable": true },
          "stock_qty": { "type": "integer" },
          "condition": { "type": "string", "enum": ["new", "refurbished", "open_box", "used"] },
          "warranty_months": { "type": "integer" },
          "is_active": { "type": "integer" },
          "is_featured": { "type": "integer" },
          "brand_id": { "type": "integer", "nullable": true },
          "category_id": { "type": "integer" },
          "created_at": { "type": "string", "format": "date-time" },
          "primary_image_url": { "type": "string", "nullable": true },
          "brand_name": { "type": "string", "nullable": true }
        },
        "required": ["id", "name", "slug", "sku", "price_pkr", "stock_qty", "condition", "category_id"]
      },
      "ProductImage": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "product_id": { "type": "integer" },
          "url": { "type": "string" },
          "alt_text": { "type": "string", "nullable": true },
          "sort_order": { "type": "integer" },
          "is_primary": { "type": "integer" }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "parent_id": { "type": "integer", "nullable": true },
          "hero_image_url": { "type": "string", "nullable": true },
          "is_active": { "type": "integer" }
        }
      },
      "Brand": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "logo_url": { "type": "string", "nullable": true }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "page": { "type": "integer" },
          "limit": { "type": "integer" },
          "total": { "type": "integer" },
          "total_pages": { "type": "integer" }
        }
      },
      "ProductListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Product" }
          },
          "meta": { "$ref": "#/components/schemas/PaginationMeta" }
        }
      },
      "ProductDetailResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "product": { "$ref": "#/components/schemas/Product" },
              "images": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ProductImage" }
              },
              "reviews": { "type": "array", "items": { "type": "object" } },
              "avg_rating": { "type": "number", "nullable": true },
              "review_count": { "type": "integer" },
              "related": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/Product" }
              }
            }
          }
        }
      },
      "CategoryListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Category" }
          }
        }
      },
      "BrandListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Brand" }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            }
          }
        }
      }
    }
  }
}