{
  "openapi": "3.1.0",
  "info": {
    "title": "GameBreaker Partner API",
    "version": "1.0.0",
    "description": "Read-only product, inventory and status feeds for retail partners.\n\nAuthenticate every request with your API key, either as an `x-api-key` header or as `Authorization: Bearer <key>`.\n\nKeys come in two flavours: **test** keys (`gb_test_…`) read a frozen snapshot of the feed so you can build against stable data, and **live** keys (`gb_live_…`) read current data.\n\nUse `updated_since` with the `ChangedAt` value from your last pull to fetch only what actually changed.",
    "contact": {
      "name": "GameBreaker"
    }
  },
  "servers": [
    {
      "url": "https://api.gamebreaker.com",
      "description": "Production"
    },
    {
      "url": "/",
      "description": "This site (whatever host you are viewing the docs on)"
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "BearerKey": []
    }
  ],
  "tags": [
    {
      "name": "Products",
      "description": "Full catalog feed."
    },
    {
      "name": "Inventory",
      "description": "Lightweight stock-only feed."
    },
    {
      "name": "Status",
      "description": "Freshness and availability."
    }
  ],
  "paths": {
    "/v1/products": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "List products",
        "description": "Paginated catalog feed with all partner fields. Supports incremental pulls via updated_since.",
        "operationId": "listProducts",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Records per page. Maximum 250.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 250,
              "default": 100
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "description": "ISO 8601 timestamp. Only returns records whose ChangedAt is at or after this moment. Invalid values return 400.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-09-01T00:00:00Z"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of product records.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "environment": {
                      "type": "string",
                      "enum": [
                        "sandbox",
                        "prod"
                      ]
                    },
                    "page": {
                      "type": "integer",
                      "example": 1
                    },
                    "limit": {
                      "type": "integer",
                      "example": 100
                    },
                    "total": {
                      "type": "integer",
                      "example": 240
                    },
                    "total_pages": {
                      "type": "integer",
                      "example": 3
                    },
                    "has_more": {
                      "type": "boolean",
                      "example": true
                    },
                    "updated_since": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "generated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/inventory": {
      "get": {
        "tags": [
          "Inventory"
        ],
        "summary": "List stock levels",
        "description": "Same paging and change filtering as products, but only the fields needed to refresh stock.",
        "operationId": "listInventory",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Records per page. Maximum 250.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 250,
              "default": 100
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "required": false,
            "description": "ISO 8601 timestamp. Only returns records whose ChangedAt is at or after this moment. Invalid values return 400.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-09-01T00:00:00Z"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of stock records.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "environment": {
                      "type": "string",
                      "enum": [
                        "sandbox",
                        "prod"
                      ]
                    },
                    "page": {
                      "type": "integer",
                      "example": 1
                    },
                    "limit": {
                      "type": "integer",
                      "example": 100
                    },
                    "total": {
                      "type": "integer",
                      "example": 240
                    },
                    "total_pages": {
                      "type": "integer",
                      "example": 3
                    },
                    "has_more": {
                      "type": "boolean",
                      "example": true
                    },
                    "updated_since": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "generated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InventoryItem"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/health": {
      "get": {
        "tags": [
          "Status"
        ],
        "summary": "Service health and data freshness",
        "description": "Reports when inventory, the store push and product content last updated successfully.",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Current status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "401": {
            "description": "Request refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request refused.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "BearerKey": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Product": {
        "type": "object",
        "required": [
          "SKU",
          "ChangedAt"
        ],
        "properties": {
          "StyleNumber": {
            "type": [
              "string",
              "null"
            ],
            "example": "GB",
            "description": "Style / product grouping code."
          },
          "ProductName": {
            "type": [
              "string",
              "null"
            ],
            "example": "GameBreaker Multi-Sport Protective Headgear"
          },
          "Color": {
            "type": [
              "string",
              "null"
            ],
            "example": "Black"
          },
          "ColorCode": {
            "type": [
              "string",
              "null"
            ],
            "example": "10"
          },
          "Size": {
            "type": [
              "string",
              "null"
            ],
            "example": "Medium"
          },
          "SKU": {
            "type": [
              "string"
            ],
            "example": "GB-10-02",
            "description": "Unique store SKU. Stable identifier for the row."
          },
          "MSRP": {
            "type": [
              "number",
              "null"
            ],
            "example": 69.99
          },
          "UPC": {
            "type": [
              "string",
              "null"
            ],
            "example": "689253451854",
            "description": "12-14 digit barcode when available."
          },
          "Inventory": {
            "type": [
              "integer",
              "null"
            ],
            "example": 42,
            "description": "Available units. Null when no stock source is mapped."
          },
          "Description": {
            "type": [
              "string",
              "null"
            ]
          },
          "Weight": {
            "type": [
              "number",
              "null"
            ],
            "example": 12.5,
            "description": "Weight in ounces."
          },
          "ProductImage1": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Typically the front image."
          },
          "ProductImage2": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Typically the back image."
          },
          "ProductImage3": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Typically a side image."
          },
          "ProductImage4": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "ChangedAt": {
            "type": [
              "string"
            ],
            "format": "date-time",
            "description": "Last time quantity, price, barcode, content, weight or images actually changed. Use with updated_since."
          }
        }
      },
      "InventoryItem": {
        "type": "object",
        "required": [
          "SKU",
          "ChangedAt"
        ],
        "properties": {
          "SKU": {
            "type": [
              "string"
            ],
            "example": "GB-10-02",
            "description": "Unique store SKU. Stable identifier for the row."
          },
          "StyleNumber": {
            "type": [
              "string",
              "null"
            ],
            "example": "GB",
            "description": "Style / product grouping code."
          },
          "Inventory": {
            "type": [
              "integer",
              "null"
            ],
            "example": 42,
            "description": "Available units. Null when no stock source is mapped."
          },
          "ChangedAt": {
            "type": [
              "string"
            ],
            "format": "date-time",
            "description": "Last time quantity, price, barcode, content, weight or images actually changed. Use with updated_since."
          }
        }
      },
      "Health": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "status": {
            "type": "string",
            "example": "operational"
          },
          "partner": {
            "type": "string",
            "example": "chipply"
          },
          "environment": {
            "type": "string",
            "enum": [
              "sandbox",
              "prod"
            ]
          },
          "last_inventory_sync": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "last_store_push": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "last_content_crawl": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "sandbox_snapshot_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "server_time": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}