{
  "openapi": "3.1.1",
  "info": {
    "title": "Kirpi Toka Agent Catalog API",
    "version": "1.1.0",
    "description": "Verified read-only discovery and catalog subset of the existing Shopify UCP/MCP service. This document does not register an OAuth client or grant permissions. Public discovery needs no token. Authenticated clients must be registered with Shopify and use authorization code with PKCE. The OAuth scope below is advertised by the live Shopify authorization server. Cart, checkout, account and order operations are outside this read-only description. Read-only Ajax product lookup is also documented. See /developers for the provider-controlled versioning policy. HTTP and JSON-RPC errors are different layers; generic platform errors are not guaranteed to be JSON."
  },
  "servers": [
    {
      "url": "https://kirpitoka.com"
    }
  ],
  "externalDocs": {
    "url": "https://kirpitoka.com/developers",
    "description": "Kirpi Toka quickstart, permissions, errors and version policy"
  },
  "paths": {
    "/.well-known/ucp": {
      "get": {
        "operationId": "discoverCommerce",
        "summary": "Discover current commerce capabilities",
        "security": [],
        "responses": {
          "200": {
            "description": "Live Shopify UCP merchant profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpProfile"
                }
              }
            }
          }
        },
        "description": "Public UCP discovery. Read supported_versions and use the service schema matching the negotiated version. No authentication is needed for this profile."
      }
    },
    "/.well-known/oauth-protected-resource": {
      "get": {
        "operationId": "discoverProtectedResource",
        "summary": "Discover the existing Shopify resource authorization server",
        "security": [],
        "responses": {
          "200": {
            "description": "RFC 9728 protected resource metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "resource",
                    "authorization_servers"
                  ],
                  "properties": {
                    "resource": {
                      "type": "string",
                      "format": "uri"
                    },
                    "authorization_servers": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "description": "RFC 9728 resource metadata. Discover the issuer before authenticating; this document does not grant a token or permission."
      }
    },
    "/api/ucp/mcp": {
      "post": {
        "operationId": "readCatalogViaMcp",
        "summary": "List tools or call catalog reading tools",
        "description": "Existing Shopify MCP JSON-RPC transport. Discover tools before calling the read-only catalog subset. Valid UCP profile configuration and authorization can be required; anonymous tools/list does not authorize tool execution. Inspect error even on HTTP 200.",
        "security": [
          {},
          {
            "ShopifyCatalogOAuth": [
              "dev.ucp.shopping.catalog.search:read"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "jsonrpc",
                      "id",
                      "method"
                    ],
                    "properties": {
                      "jsonrpc": {
                        "const": "2.0"
                      },
                      "id": {
                        "type": [
                          "string",
                          "integer"
                        ]
                      },
                      "method": {
                        "const": "tools/list"
                      },
                      "params": {
                        "type": "object"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "jsonrpc",
                      "id",
                      "method",
                      "params"
                    ],
                    "properties": {
                      "jsonrpc": {
                        "const": "2.0"
                      },
                      "id": {
                        "type": [
                          "string",
                          "integer"
                        ]
                      },
                      "method": {
                        "const": "tools/call"
                      },
                      "params": {
                        "type": "object",
                        "required": [
                          "name",
                          "arguments"
                        ],
                        "properties": {
                          "name": {
                            "const": "search_catalog"
                          },
                          "arguments": {
                            "$schema": "https://json-schema.org/draft/2020-12/schema",
                            "type": "object",
                            "properties": {
                              "meta": {
                                "type": "object",
                                "description": "Metadata for UCP agent profile discovery.",
                                "properties": {
                                  "ucp-agent": {
                                    "type": "object",
                                    "properties": {
                                      "profile": {
                                        "type": "string",
                                        "format": "uri",
                                        "description": "Agent profile URI for UCP discovery."
                                      }
                                    },
                                    "required": [
                                      "profile"
                                    ]
                                  }
                                },
                                "required": [
                                  "ucp-agent"
                                ]
                              },
                              "catalog": {
                                "type": "object",
                                "description": "Catalog search parameters.",
                                "properties": {
                                  "query": {
                                    "type": "string",
                                    "description": "Search query string."
                                  },
                                  "context": {
                                    "type": "object",
                                    "description": "Buyer signals for localization and personalization.",
                                    "additionalProperties": true,
                                    "properties": {
                                      "address_country": {
                                        "type": "string",
                                        "description": "Country code in ISO 3166-1 alpha-2 format."
                                      },
                                      "address_region": {
                                        "type": "string",
                                        "description": "Region or state."
                                      },
                                      "postal_code": {
                                        "type": "string",
                                        "description": "Postal code."
                                      },
                                      "language": {
                                        "type": "string",
                                        "description": "Language tag in IETF BCP 47 format."
                                      },
                                      "currency": {
                                        "type": "string",
                                        "description": "Currency code in ISO 4217 format."
                                      },
                                      "intent": {
                                        "type": "string",
                                        "description": "Buyer intent."
                                      }
                                    }
                                  },
                                  "signals": {
                                    "type": "object",
                                    "description": "Platform environment data.",
                                    "additionalProperties": true,
                                    "properties": {
                                      "dev.ucp.buyer_ip": {
                                        "type": "string",
                                        "description": "Buyer IP address."
                                      },
                                      "dev.ucp.user_agent": {
                                        "type": "string",
                                        "description": "Buyer user agent."
                                      }
                                    }
                                  },
                                  "filters": {
                                    "type": "object",
                                    "description": "Narrowing criteria for catalog results.",
                                    "additionalProperties": true,
                                    "properties": {
                                      "categories": {
                                        "type": "array",
                                        "description": "Category filters combined with OR logic.",
                                        "items": {
                                          "type": "string"
                                        }
                                      },
                                      "price": {
                                        "type": "object",
                                        "description": "Price range filter.",
                                        "properties": {
                                          "min": {
                                            "type": "integer",
                                            "description": "Minimum price in minor currency units."
                                          },
                                          "max": {
                                            "type": "integer",
                                            "description": "Maximum price in minor currency units."
                                          }
                                        }
                                      },
                                      "available": {
                                        "type": "boolean",
                                        "description": "Filter by availability. Default true (only sale-ready items).",
                                        "default": true
                                      }
                                    }
                                  },
                                  "pagination": {
                                    "type": "object",
                                    "description": "Pagination parameters.",
                                    "properties": {
                                      "cursor": {
                                        "type": "string",
                                        "description": "Pagination cursor."
                                      },
                                      "limit": {
                                        "type": "integer",
                                        "description": "Number of results to return.",
                                        "default": 10,
                                        "minimum": 1
                                      }
                                    }
                                  }
                                }
                              }
                            },
                            "required": [
                              "meta",
                              "catalog"
                            ]
                          }
                        }
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "jsonrpc",
                      "id",
                      "method",
                      "params"
                    ],
                    "properties": {
                      "jsonrpc": {
                        "const": "2.0"
                      },
                      "id": {
                        "type": [
                          "string",
                          "integer"
                        ]
                      },
                      "method": {
                        "const": "tools/call"
                      },
                      "params": {
                        "type": "object",
                        "required": [
                          "name",
                          "arguments"
                        ],
                        "properties": {
                          "name": {
                            "const": "lookup_catalog"
                          },
                          "arguments": {
                            "$schema": "https://json-schema.org/draft/2020-12/schema",
                            "type": "object",
                            "properties": {
                              "meta": {
                                "type": "object",
                                "description": "Metadata for UCP agent profile discovery.",
                                "properties": {
                                  "ucp-agent": {
                                    "type": "object",
                                    "properties": {
                                      "profile": {
                                        "type": "string",
                                        "format": "uri",
                                        "description": "Agent profile URI for UCP discovery."
                                      }
                                    },
                                    "required": [
                                      "profile"
                                    ]
                                  }
                                },
                                "required": [
                                  "ucp-agent"
                                ]
                              },
                              "catalog": {
                                "type": "object",
                                "description": "Catalog lookup parameters.",
                                "required": [
                                  "ids"
                                ],
                                "properties": {
                                  "ids": {
                                    "type": "array",
                                    "description": "Product IDs to look up.",
                                    "items": {
                                      "type": "string"
                                    },
                                    "minItems": 1,
                                    "maxItems": 10
                                  },
                                  "context": {
                                    "type": "object",
                                    "description": "Buyer signals for localization and personalization.",
                                    "additionalProperties": true,
                                    "properties": {
                                      "address_country": {
                                        "type": "string",
                                        "description": "Country code in ISO 3166-1 alpha-2 format."
                                      },
                                      "address_region": {
                                        "type": "string",
                                        "description": "Region or state."
                                      },
                                      "postal_code": {
                                        "type": "string",
                                        "description": "Postal code."
                                      },
                                      "language": {
                                        "type": "string",
                                        "description": "Language tag in IETF BCP 47 format."
                                      },
                                      "currency": {
                                        "type": "string",
                                        "description": "Currency code in ISO 4217 format."
                                      },
                                      "intent": {
                                        "type": "string",
                                        "description": "Buyer intent."
                                      }
                                    }
                                  },
                                  "signals": {
                                    "type": "object",
                                    "description": "Platform environment data.",
                                    "additionalProperties": true,
                                    "properties": {
                                      "dev.ucp.buyer_ip": {
                                        "type": "string",
                                        "description": "Buyer IP address."
                                      },
                                      "dev.ucp.user_agent": {
                                        "type": "string",
                                        "description": "Buyer user agent."
                                      }
                                    }
                                  },
                                  "filters": {
                                    "type": "object",
                                    "description": "Narrowing criteria for catalog results.",
                                    "additionalProperties": true,
                                    "properties": {
                                      "categories": {
                                        "type": "array",
                                        "description": "Category filters combined with OR logic.",
                                        "items": {
                                          "type": "string"
                                        }
                                      },
                                      "price": {
                                        "type": "object",
                                        "description": "Price range filter.",
                                        "properties": {
                                          "min": {
                                            "type": "integer",
                                            "description": "Minimum price in minor currency units."
                                          },
                                          "max": {
                                            "type": "integer",
                                            "description": "Maximum price in minor currency units."
                                          }
                                        }
                                      },
                                      "available": {
                                        "type": "boolean",
                                        "description": "Filter by availability. Default true (only sale-ready items).",
                                        "default": true
                                      }
                                    }
                                  }
                                }
                              }
                            },
                            "required": [
                              "meta",
                              "catalog"
                            ]
                          }
                        }
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "jsonrpc",
                      "id",
                      "method",
                      "params"
                    ],
                    "properties": {
                      "jsonrpc": {
                        "const": "2.0"
                      },
                      "id": {
                        "type": [
                          "string",
                          "integer"
                        ]
                      },
                      "method": {
                        "const": "tools/call"
                      },
                      "params": {
                        "type": "object",
                        "required": [
                          "name",
                          "arguments"
                        ],
                        "properties": {
                          "name": {
                            "const": "get_product"
                          },
                          "arguments": {
                            "$schema": "https://json-schema.org/draft/2020-12/schema",
                            "type": "object",
                            "properties": {
                              "meta": {
                                "type": "object",
                                "description": "Metadata for UCP agent profile discovery.",
                                "properties": {
                                  "ucp-agent": {
                                    "type": "object",
                                    "properties": {
                                      "profile": {
                                        "type": "string",
                                        "format": "uri",
                                        "description": "Agent profile URI for UCP discovery."
                                      }
                                    },
                                    "required": [
                                      "profile"
                                    ]
                                  }
                                },
                                "required": [
                                  "ucp-agent"
                                ]
                              },
                              "catalog": {
                                "type": "object",
                                "description": "Product detail parameters.",
                                "required": [
                                  "id"
                                ],
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "description": "Product ID."
                                  },
                                  "selected": {
                                    "type": "array",
                                    "description": "Selected variant options.",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "name": {
                                          "type": "string"
                                        },
                                        "label": {
                                          "type": "string"
                                        }
                                      }
                                    }
                                  },
                                  "preferences": {
                                    "type": "array",
                                    "description": "Buyer preferences.",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "context": {
                                    "type": "object",
                                    "description": "Buyer signals for localization and personalization.",
                                    "additionalProperties": true,
                                    "properties": {
                                      "address_country": {
                                        "type": "string",
                                        "description": "Country code in ISO 3166-1 alpha-2 format."
                                      },
                                      "address_region": {
                                        "type": "string",
                                        "description": "Region or state."
                                      },
                                      "postal_code": {
                                        "type": "string",
                                        "description": "Postal code."
                                      },
                                      "language": {
                                        "type": "string",
                                        "description": "Language tag in IETF BCP 47 format."
                                      },
                                      "currency": {
                                        "type": "string",
                                        "description": "Currency code in ISO 4217 format."
                                      },
                                      "intent": {
                                        "type": "string",
                                        "description": "Buyer intent."
                                      }
                                    }
                                  },
                                  "signals": {
                                    "type": "object",
                                    "description": "Platform environment data.",
                                    "additionalProperties": true,
                                    "properties": {
                                      "dev.ucp.buyer_ip": {
                                        "type": "string",
                                        "description": "Buyer IP address."
                                      },
                                      "dev.ucp.user_agent": {
                                        "type": "string",
                                        "description": "Buyer user agent."
                                      }
                                    }
                                  },
                                  "filters": {
                                    "type": "object",
                                    "description": "Narrowing criteria for catalog results.",
                                    "additionalProperties": true,
                                    "properties": {
                                      "categories": {
                                        "type": "array",
                                        "description": "Category filters combined with OR logic.",
                                        "items": {
                                          "type": "string"
                                        }
                                      },
                                      "price": {
                                        "type": "object",
                                        "description": "Price range filter.",
                                        "properties": {
                                          "min": {
                                            "type": "integer",
                                            "description": "Minimum price in minor currency units."
                                          },
                                          "max": {
                                            "type": "integer",
                                            "description": "Maximum price in minor currency units."
                                          }
                                        }
                                      },
                                      "available": {
                                        "type": "boolean",
                                        "description": "Filter by availability. Default true (only sale-ready items).",
                                        "default": true
                                      }
                                    }
                                  }
                                }
                              }
                            },
                            "required": [
                              "meta",
                              "catalog"
                            ]
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result or error; inspect the body even when HTTP status is 200",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "jsonrpc",
                    "id"
                  ],
                  "properties": {
                    "jsonrpc": {
                      "const": "2.0",
                      "type": "string"
                    },
                    "id": {
                      "type": [
                        "string",
                        "integer",
                        "null"
                      ]
                    },
                    "result": {
                      "type": "object",
                      "description": "Tool-list or provider tool result; validate against the current tools/list schema.",
                      "additionalProperties": true
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "integer",
                          "description": "JSON-RPC error code. -32601: rediscover methods; -32001: inspect UCP profile configuration."
                        },
                        "message": {
                          "type": "string"
                        },
                        "data": {
                          "oneOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "object",
                              "properties": {
                                "code": {
                                  "type": "string"
                                },
                                "content": {
                                  "type": "string"
                                },
                                "continue_url": {
                                  "type": "string",
                                  "format": "uri"
                                }
                              },
                              "additionalProperties": true
                            }
                          ],
                          "description": "Observed provider details. invalid_profile_url requires a valid agent profile; continue_url is not permission to transact."
                        }
                      }
                    }
                  },
                  "oneOf": [
                    {
                      "required": [
                        "result"
                      ]
                    },
                    {
                      "required": [
                        "error"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required; follow WWW-Authenticate discovery"
          },
          "403": {
            "description": "Insufficient permission or unavailable capability"
          },
          "429": {
            "description": "Rate limited; back off before retrying"
          },
          "422": {
            "description": "Observed UCP profile configuration error. Fix the registered agent profile before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcError"
                },
                "example": {
                  "jsonrpc": "2.0",
                  "id": 2,
                  "error": {
                    "code": -32001,
                    "message": "UCP discovery failed",
                    "data": {
                      "code": "invalid_profile_url",
                      "content": "Unable to fetch agent profile: Missing profile uri"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/products/{handle}.js": {
      "get": {
        "operationId": "getPublicProduct",
        "summary": "Read a current public product without a key",
        "description": "Shopify Ajax product lookup, verified without authentication. Prices use minor units. This provider route is unversioned. A missing handle currently returns HTTP 404 with an empty body; do not assume a JSON error. Rediscover valid handles from /sitemap.xml.",
        "security": [],
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "description": "Exact URL handle from the catalog; encode it as one path segment.",
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "bayrakli-saten-toren-tokasi"
          }
        ],
        "responses": {
          "200": {
            "description": "JSON document served with Shopify Ajax media type",
            "content": {
              "text/javascript": {
                "schema": {
                  "$ref": "#/components/schemas/AjaxProduct"
                }
              }
            }
          },
          "404": {
            "description": "Unknown product; observed empty body. Find the current handle in the sitemap."
          },
          "429": {
            "description": "Provider throttling; honor Retry-After when present. No fixed quota is advertised."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ShopifyCatalogOAuth": {
        "type": "oauth2",
        "description": "Existing Shopify authorization server. Authorization code with PKCE; a registered client is required. Declaration is documentation of an existing scope, not a grant or a new permission.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://shopify.com/authentication/85011890405/oauth/authorize",
            "tokenUrl": "https://shopify.com/authentication/85011890405/oauth/token",
            "scopes": {
              "dev.ucp.shopping.catalog.search:read": "Read/search the product catalog"
            }
          }
        }
      }
    },
    "schemas": {
      "JsonRpcError": {
        "type": "object",
        "required": [
          "jsonrpc",
          "id",
          "error"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "integer",
              "null"
            ]
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "description": "JSON-RPC error code. -32601: rediscover methods; -32001: inspect UCP profile configuration."
              },
              "message": {
                "type": "string"
              },
              "data": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string"
                      },
                      "content": {
                        "type": "string"
                      },
                      "continue_url": {
                        "type": "string",
                        "format": "uri"
                      }
                    },
                    "additionalProperties": true
                  }
                ],
                "description": "Observed provider details. invalid_profile_url requires a valid agent profile; continue_url is not permission to transact."
              }
            }
          }
        }
      },
      "UcpProfile": {
        "type": "object",
        "required": [
          "ucp"
        ],
        "properties": {
          "ucp": {
            "type": "object",
            "required": [
              "version",
              "services",
              "capabilities"
            ],
            "properties": {
              "version": {
                "type": "string",
                "description": "Current provider UCP date version"
              },
              "supported_versions": {
                "type": "object",
                "additionalProperties": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "services": {
                "type": "object",
                "additionalProperties": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "version": {
                        "type": "string"
                      },
                      "transport": {
                        "type": "string"
                      },
                      "endpoint": {
                        "type": "string",
                        "format": "uri"
                      },
                      "schema": {
                        "type": "string",
                        "format": "uri"
                      },
                      "spec": {
                        "type": "string",
                        "format": "uri"
                      }
                    },
                    "additionalProperties": true
                  }
                }
              },
              "capabilities": {
                "type": "object",
                "additionalProperties": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "version": {
                        "type": "string"
                      },
                      "spec": {
                        "type": "string",
                        "format": "uri"
                      },
                      "schema": {
                        "type": "string",
                        "format": "uri"
                      },
                      "extends": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    },
                    "additionalProperties": true
                  }
                }
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "AjaxVariant": {
        "type": "object",
        "required": [
          "id",
          "title",
          "price",
          "available"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "price": {
            "type": "integer",
            "description": "Minor currency units, not a wholesale quote."
          },
          "available": {
            "type": "boolean"
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "AjaxProduct": {
        "type": "object",
        "required": [
          "id",
          "title",
          "handle",
          "price",
          "available",
          "variants"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "handle": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "price": {
            "type": "integer",
            "description": "Minor currency units; TRY 10000 means TRY 100.00."
          },
          "price_min": {
            "type": "integer"
          },
          "price_max": {
            "type": "integer"
          },
          "available": {
            "type": "boolean"
          },
          "url": {
            "type": "string"
          },
          "variants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AjaxVariant"
            }
          }
        },
        "additionalProperties": true
      }
    }
  }
}