{
  "openapi": "3.1.0",
  "info": {
    "title": "Garde-Robe public API",
    "summary": "Anonymous, read-only endpoints of the Garde-Robe gateway.",
    "description": "The parts of the Garde-Robe gateway that anyone can read without signing in: a health check, the day's reference exchange rates, and the brand pages' catalogue. Nothing here identifies a member. Every other part of the gateway is private to signed-in members and is not described here.",
    "version": "1.0.0",
    "contact": {
      "name": "Garde-Robe",
      "url": "https://www.garde-robe.com/contact",
      "email": "hi@garde-robe.com"
    }
  },
  "externalDocs": {
    "description": "Human-readable documentation for this API.",
    "url": "https://www.garde-robe.com/developers"
  },
  "servers": [
    {
      "url": "https://services.garde-robe.com",
      "description": "Production"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Status",
      "description": "Whether the gateway is up."
    },
    {
      "name": "Exchange rates",
      "description": "Reference currency conversion."
    },
    {
      "name": "Brands",
      "description": "The brand pages' catalogue."
    }
  ],
  "paths": {
    "/v1/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Status"
        ],
        "summary": "Check gateway health",
        "description": "Answers 200 with `status: ok` while the gateway is running. The response is never cached.",
        "responses": {
          "200": {
            "description": "The gateway is up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                },
                "example": {
                  "status": "ok",
                  "version": "v1",
                  "environment": "production"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "How long a response may be reused.",
                "schema": {
                  "type": "string"
                },
                "example": "no-store"
              }
            }
          }
        }
      }
    },
    "/v1/fx-rates": {
      "get": {
        "operationId": "getFxRates",
        "tags": [
          "Exchange rates"
        ],
        "summary": "Get the day's reference exchange rates",
        "description": "Units of each currency per one US dollar, from the European Central Bank's reference rates (via Frankfurter), refreshed once each working day. Use it to show a price approximately in the reader's own currency; never for payment. To convert an amount in currency A to currency B, divide by `rates[A]` and multiply by `rates[B]`. A currency missing from `rates` has no conversion.",
        "responses": {
          "200": {
            "description": "The latest stored table of rates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FxRates"
                },
                "example": {
                  "base": "USD",
                  "date": "2026-11-18",
                  "source": "ecb-frankfurter",
                  "rates": {
                    "USD": 1,
                    "CAD": 1.4305,
                    "EUR": 0.91174,
                    "GBP": 0.75939,
                    "JPY": 159.42
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "How long a response may be reused.",
                "schema": {
                  "type": "string"
                },
                "example": "public, max-age=3600"
              }
            }
          },
          "503": {
            "description": "No table is stored and the source could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "fx_rates_unavailable",
                    "message": "Exchange rates are unavailable"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/brands": {
      "get": {
        "operationId": "listPublicBrands",
        "tags": [
          "Brands"
        ],
        "summary": "List every brand that has a public brand page",
        "description": "Brands with enough products that members have saved publicly, largest first. A saved product counts only when it was saved publicly: saves restricted to a private wishlist never count. The answer is the same for every caller and the list is long, so read it once and keep it.",
        "responses": {
          "200": {
            "description": "Brands with a public page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicBrandListResponse"
                },
                "example": {
                  "brands": [
                    {
                      "slug": "zara",
                      "displayName": "Zara",
                      "productCount": 1019,
                      "shopProductCount": 0,
                      "lastSavedAt": "2026-11-16T20:32:01.210289+00:00",
                      "affiliate": false
                    },
                    {
                      "slug": "free-people",
                      "displayName": "Free People",
                      "productCount": 574,
                      "shopProductCount": 6047,
                      "lastSavedAt": "2026-11-17T16:10:53.377206+00:00",
                      "affiliate": true
                    }
                  ]
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "How long a response may be reused.",
                "schema": {
                  "type": "string"
                },
                "example": "public, max-age=60"
              }
            }
          },
          "503": {
            "description": "The catalogue could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "public_brand_unavailable",
                    "message": "Brands are temporarily unavailable"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/brands/{slug}": {
      "get": {
        "operationId": "getPublicBrandPage",
        "tags": [
          "Brands"
        ],
        "summary": "Read one brand's products",
        "description": "One page of the products members have saved publicly for this brand, newest save first, and one page of the brand's in-stock shop products. Each product appears once however many members saved it, and carries product facts only: nothing identifies, or was written by, the members who saved it. Any hyphenation of the same letters reaches the same brand; when the requested slug differs from `brand.slug`, use the canonical slug the response carries.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The brand slug, as listed by `/v1/public/brands`.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
              "maxLength": 120
            },
            "example": "free-people"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number of member products and of shop products.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": false,
            "description": "Member products per page. A page can hold slightly fewer, because repeated titles are shown once.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 48
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "A page of the brand's products.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicBrandPageResponse"
                },
                "example": {
                  "brand": {
                    "slug": "free-people",
                    "displayName": "Free People",
                    "productCount": 574,
                    "shopProductCount": 5876,
                    "lastSavedAt": "2026-11-17T16:10:53.377206+00:00",
                    "affiliate": true
                  },
                  "indexable": true,
                  "products": [
                    {
                      "productId": "407d362c-5063-4081-92d1-9b4802b05930",
                      "title": "Breezy Plaid Midi Skirt Set",
                      "priceCents": 22800,
                      "currency": "USD",
                      "availability": "in_stock",
                      "productUrl": "https://www.freepeople.com/shop/breezy-plaid-midi-skirt-set",
                      "saveCount": 1,
                      "lastSavedAt": "2026-11-17T16:10:53.377206+00:00",
                      "clickUrl": "https://services.garde-robe.com/v1/public/brand-products/407d362c-5063-4081-92d1-9b4802b05930/click",
                      "image": {
                        "url": "https://services.garde-robe.com/v1/public/brand-images/a1dd796f-e1ed-4056-baf1-e5fc4457b1a2",
                        "width": 640,
                        "height": 960
                      }
                    }
                  ],
                  "page": 1,
                  "pageSize": 1,
                  "hasMore": true,
                  "shopProducts": [
                    {
                      "id": "1326d3c1-18f6-4557-a1ae-833856f46b73",
                      "title": "Boxing Day Lace Up Boots",
                      "destinationUrl": "https://www.freepeople.com/shop/boxing-day-lace-up-boots/?color=023&size=US+10&type=STANDARD",
                      "brand": "Free People",
                      "priceCents": 17800,
                      "category": "Apparel & Accessories",
                      "imageUrl": "https://images.urbndata.com/is/image/FreePeople/87038972_023_a?$feed-main$",
                      "clickUrl": "https://services.garde-robe.com/v1/public/brand-products/1326d3c1-18f6-4557-a1ae-833856f46b73/click"
                    }
                  ],
                  "shopHasMore": true
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "description": "How long a response may be reused.",
                "schema": {
                  "type": "string"
                },
                "example": "public, max-age=60"
              }
            }
          },
          "400": {
            "description": "The slug, `page` or `pageSize` is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "public_brand_invalid_input",
                    "message": "pageSize must be an integer from 1 to 100"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No brand has this slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "public_brand_not_found",
                    "message": "Brand not found"
                  }
                }
              }
            }
          },
          "503": {
            "description": "The catalogue could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "public_brand_unavailable",
                    "message": "Brands are temporarily unavailable"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/public/brand-images/{assetId}": {
      "get": {
        "operationId": "getPublicBrandImage",
        "tags": [
          "Brands"
        ],
        "summary": "Fetch a product image shown on a brand page",
        "description": "The stable, unsigned address of a product image: every `image.url` in a brand page response points here. It answers with a redirect to the image CDN, or with the image itself. An image is served only while it belongs to at least one product shown on a public brand page; otherwise the answer is 404.",
        "parameters": [
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "description": "The image id, the last segment of an `image.url`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "a1dd796f-e1ed-4056-baf1-e5fc4457b1a2"
          }
        ],
        "responses": {
          "200": {
            "description": "The image.",
            "content": {
              "image/*": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "image/*",
                  "contentEncoding": "base64"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to the image CDN.",
            "headers": {
              "Location": {
                "description": "Where the image is.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "Cache-Control": {
                "description": "How long the redirect may be reused.",
                "schema": {
                  "type": "string"
                },
                "example": "public, max-age=14400"
              }
            }
          },
          "400": {
            "description": "The image id is not a valid id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "public_brand_invalid_input",
                    "message": "Asset id is invalid"
                  }
                }
              }
            }
          },
          "404": {
            "description": "The image is not on a public brand page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "public_brand_not_found",
                    "message": "Image not found"
                  }
                }
              }
            }
          },
          "503": {
            "description": "The catalogue could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "public_brand_unavailable",
                    "message": "Brands are temporarily unavailable"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Health": {
        "type": "object",
        "required": [
          "status",
          "version",
          "environment"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "ok",
            "description": "Always `ok` when the gateway answers."
          },
          "version": {
            "type": "string",
            "description": "The API version in the path, for example `v1`."
          },
          "environment": {
            "type": "string",
            "description": "The deployment that answered, for example `production`."
          },
          "deployTag": {
            "type": "string",
            "description": "The release tag running now, when known."
          },
          "deploySha": {
            "type": "string",
            "description": "The commit running now, when known."
          }
        }
      },
      "FxRates": {
        "type": "object",
        "description": "One day's reference exchange rates against the US dollar.",
        "required": [
          "base",
          "date",
          "source",
          "rates"
        ],
        "properties": {
          "base": {
            "type": "string",
            "const": "USD",
            "description": "The currency every rate is quoted against."
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "The publication date of the newest stored rate."
          },
          "source": {
            "type": "string",
            "description": "Where the rates came from, for example `ecb-frankfurter`."
          },
          "rates": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "Units of each ISO 4217 currency per one US dollar; `USD` is 1."
          }
        }
      },
      "PublicBrandSummary": {
        "type": "object",
        "required": [
          "slug",
          "displayName",
          "productCount",
          "lastSavedAt",
          "affiliate"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "description": "The canonical brand slug, used in the brand page's address."
          },
          "displayName": {
            "type": "string",
            "description": "The brand name as most members spell it."
          },
          "productCount": {
            "type": "integer",
            "description": "Number of distinct products with a qualifying public save."
          },
          "shopProductCount": {
            "type": "integer",
            "description": "Number of the brand's in-stock products in Garde-Robe's shop catalogue."
          },
          "logoUrl": {
            "type": "string",
            "format": "uri",
            "description": "The brand's own logo, hosted by Garde-Robe. Absent when no logo of the brand's own site has been found."
          },
          "lastSavedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When a product of this brand was most recently saved publicly or, for a brand with only shop products, listed."
          },
          "affiliate": {
            "type": "boolean",
            "description": "True when the brand's own website is a store Garde-Robe has a direct affiliate programme with."
          }
        }
      },
      "PublicBrandListResponse": {
        "type": "object",
        "required": [
          "brands"
        ],
        "properties": {
          "brands": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicBrandSummary"
            }
          }
        }
      },
      "PublicBrandProduct": {
        "type": "object",
        "description": "A product on a brand page. Product facts only.",
        "required": [
          "productId",
          "title",
          "productUrl",
          "saveCount",
          "lastSavedAt"
        ],
        "properties": {
          "productId": {
            "type": "string",
            "format": "uuid",
            "description": "The catalogue product id."
          },
          "title": {
            "type": "string",
            "description": "The product name from the retailer."
          },
          "priceCents": {
            "type": "integer",
            "description": "The retailer's current price in minor units, when known."
          },
          "currency": {
            "type": "string",
            "description": "The currency of `priceCents`, as stored from the retailer (usually an ISO 4217 code)."
          },
          "availability": {
            "type": "string",
            "description": "The retailer's stock status, when known."
          },
          "productUrl": {
            "type": "string",
            "format": "uri",
            "description": "The product page on the retailer's site."
          },
          "clickUrl": {
            "type": "string",
            "format": "uri",
            "description": "Garde-Robe's outbound link to the product, for a person who wants to shop it. It is a redirect, and following it counts as a visit, so automated clients should use `productUrl` instead."
          },
          "image": {
            "type": "object",
            "description": "The product image, at a stable public address.",
            "required": [
              "url"
            ],
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "width": {
                "type": "integer"
              },
              "height": {
                "type": "integer"
              }
            }
          },
          "saveCount": {
            "type": "integer",
            "description": "How many public posts saved this product. A count only."
          },
          "lastSavedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When this product was most recently saved publicly."
          }
        }
      },
      "PublicBrandShopProduct": {
        "type": "object",
        "description": "An in-stock product of the brand from Garde-Robe's shop catalogue.",
        "required": [
          "id",
          "title",
          "destinationUrl",
          "clickUrl"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "A stable identifier for this product."
          },
          "title": {
            "type": "string",
            "description": "The product name."
          },
          "brand": {
            "type": "string",
            "description": "The brand as the retailer's product feed reports it."
          },
          "imageUrl": {
            "type": "string",
            "format": "uri",
            "description": "The product image."
          },
          "destinationUrl": {
            "type": "string",
            "format": "uri",
            "description": "The merchant's own product page."
          },
          "priceCents": {
            "type": "integer",
            "description": "The regular price in minor units."
          },
          "salePriceCents": {
            "type": "integer",
            "description": "The reduced price in minor units, present only when it is below the regular price."
          },
          "currency": {
            "type": "string",
            "description": "The ISO 4217 currency of both prices."
          },
          "category": {
            "type": "string",
            "description": "The last part of the feed's category path, for example `Dresses`."
          },
          "clickUrl": {
            "type": "string",
            "format": "uri",
            "description": "Garde-Robe's outbound link to the product, for a person who wants to shop it. It is a redirect, and following it counts as a visit, so automated clients should use `destinationUrl` instead."
          }
        }
      },
      "PublicBrandPageResponse": {
        "type": "object",
        "required": [
          "brand",
          "indexable",
          "products",
          "page",
          "pageSize",
          "hasMore"
        ],
        "properties": {
          "brand": {
            "$ref": "#/components/schemas/PublicBrandSummary"
          },
          "indexable": {
            "type": "boolean",
            "description": "Whether this page shows enough products for a search engine to index it."
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicBrandProduct"
            }
          },
          "page": {
            "type": "integer"
          },
          "pageSize": {
            "type": "integer"
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether another page of member products follows."
          },
          "shopProducts": {
            "type": "array",
            "description": "In-stock products of this brand from Garde-Robe's shop catalogue, 24 per page, leaving out any product already in `products`. Empty when the brand has none.",
            "items": {
              "$ref": "#/components/schemas/PublicBrandShopProduct"
            }
          },
          "shopHasMore": {
            "type": "boolean",
            "description": "Whether another page of shop products follows."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "A stable, machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "A short explanation for a person."
              }
            }
          }
        }
      }
    }
  }
}
