{
  "openapi": "3.1.0",
  "info": {
    "title": "Stock Sorted API",
    "description": "Shopify inventory pool management API. Manage shared inventory pools, sync variant quantities, and track stock history.",
    "version": "1.0.0",
    "contact": {
      "name": "Stock Sorted Support",
      "email": "support@sorted.fast",
      "url": "https://stock.sorted.fast"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://stock.sorted.fast",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "summary": "MCP JSON-RPC endpoint",
        "description": "Model Context Protocol (MCP) Streamable HTTP endpoint. Send JSON-RPC 2.0 requests to interact with inventory tools.",
        "operationId": "mcpPost",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "examples": {
                "initialize": {
                  "summary": "Initialize MCP session",
                  "value": {
                    "jsonrpc": "2.0",
                    "method": "initialize",
                    "params": {
                      "protocolVersion": "2025-06-18",
                      "clientInfo": {"name": "my-agent", "version": "1.0"}
                    },
                    "id": 1
                  }
                },
                "listTools": {
                  "summary": "List available tools",
                  "value": {"jsonrpc": "2.0", "method": "tools/list", "id": 2}
                },
                "listPools": {
                  "summary": "List inventory pools",
                  "value": {
                    "jsonrpc": "2.0",
                    "method": "tools/call",
                    "params": {"name": "list_pools", "arguments": {}},
                    "id": 3
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/JsonRpcResponse"}
              },
              "text/event-stream": {
                "schema": {"type": "string", "description": "SSE stream of JSON-RPC messages"}
              }
            }
          },
          "401": {
            "description": "Missing or invalid Bearer token",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Error"}
              }
            }
          }
        },
        "security": [{"bearerAuth": []}]
      },
      "get": {
        "summary": "MCP SSE stream",
        "description": "Open a Server-Sent Events stream for server-initiated MCP messages.",
        "operationId": "mcpStream",
        "responses": {
          "200": {
            "description": "SSE stream",
            "content": {
              "text/event-stream": {
                "schema": {"type": "string"}
              }
            }
          },
          "401": {"description": "Unauthorized"}
        },
        "security": [{"bearerAuth": []}]
      }
    },
    "/storefront/availability": {
      "get": {
        "summary": "Get variant availability for storefront",
        "description": "Returns current effective available quantities for all pool-linked variants. Used by Shopify theme extensions. Requires valid Shopify app proxy HMAC signature.",
        "operationId": "storefrontAvailability",
        "parameters": [
          {
            "name": "shop",
            "in": "query",
            "required": true,
            "schema": {"type": "string"},
            "description": "Shop domain (e.g. mystore.myshopify.com)"
          }
        ],
        "responses": {
          "200": {
            "description": "Variant availability map",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "shared_inventory_id": {"type": "integer"},
                    "variants": {
                      "type": "object",
                      "additionalProperties": {"type": "integer"},
                      "description": "Map of variant GID to effective available quantity"
                    },
                    "stream_url": {
                      "type": "string",
                      "description": "URL for real-time SSE updates"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": {"type": "string", "enum": ["2.0"]},
          "method": {"type": "string"},
          "params": {"type": "object"},
          "id": {"oneOf": [{"type": "integer"}, {"type": "string"}, {"type": "null"}]}
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc", "id"],
        "properties": {
          "jsonrpc": {"type": "string", "enum": ["2.0"]},
          "id": {"oneOf": [{"type": "integer"}, {"type": "string"}, {"type": "null"}]},
          "result": {"type": "object"},
          "error": {
            "type": "object",
            "properties": {
              "code": {"type": "integer"},
              "message": {"type": "string"}
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {"type": "string"},
          "message": {"type": "string"}
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "MCP API Key",
        "description": "MCP API key from Stock Sorted dashboard. Get yours at: Shopify Admin → Stock Sorted → Settings → API Access"
      }
    }
  }
}