{
  "openapi": "3.1.0",
  "info": {
    "title": "AllMySizes.AI Family Size API",
    "version": "1.0.0-preview",
    "description": "Private household sizing, international reference conversions, selective sharing, photo uploads and optional adult virtual try-on. Browser API uses authenticated Site identity and same-origin access. This specification describes the current private preview, not an OAuth partner API."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "tags": [
    {
      "name": "Household"
    },
    {
      "name": "People"
    },
    {
      "name": "Size & fit"
    },
    {
      "name": "Preferences"
    },
    {
      "name": "Sharing"
    },
    {
      "name": "Invitations"
    },
    {
      "name": "Photos"
    },
    {
      "name": "Phone scan"
    },
    {
      "name": "Virtual try-on"
    },
    {
      "name": "Merchant"
    },
    {
      "name": "Agent"
    }
  ],
  "paths": {
    "/api/v1/household": {
      "get": {
        "tags": [
          "Household"
        ],
        "summary": "Get the current owner's full household snapshot",
        "responses": {
          "200": {
            "description": "Household and associated records"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "patch": {
        "tags": [
          "Household"
        ],
        "summary": "Rename household",
        "requestBody": {
          "$ref": "#/components/requestBodies/HouseholdName"
        },
        "responses": {
          "200": {
            "description": "Renamed household"
          }
        }
      }
    },
    "/api/v1/account-export": {
      "get": {
        "tags": [
          "Household"
        ],
        "summary": "Download the signed-in owner's structured family data export without binary photos or tokens",
        "responses": {
          "200": {
            "description": "JSON attachment"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/invitations": {
      "get": {
        "tags": [
          "Invitations"
        ],
        "summary": "List an owner's sent invitations and accepted viewer grants",
        "responses": {
          "200": {
            "description": "Invitation metadata only, never raw tokens"
          }
        }
      },
      "post": {
        "tags": [
          "Invitations"
        ],
        "summary": "Create a single-use account invitation scoped to one owned person and sizes or preferences",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "personId",
                  "scopes"
                ],
                "properties": {
                  "personId": {
                    "type": "string"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "sizes",
                        "preferences"
                      ]
                    }
                  },
                  "days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 30
                  },
                  "label": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "One-time invite URL, never stored in plaintext"
          }
        }
      }
    },
    "/api/v1/invitations/{id}": {
      "delete": {
        "tags": [
          "Invitations"
        ],
        "summary": "Revoke an owned invitation",
        "responses": {
          "200": {
            "description": "Revoked"
          }
        }
      }
    },
    "/api/v1/invitations/accept": {
      "post": {
        "tags": [
          "Invitations"
        ],
        "summary": "Bind an unexpired one-use invitation to the authenticated user as a read-only viewer",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted and bound to the current identity"
          },
          "410": {
            "description": "Expired or used"
          }
        }
      }
    },
    "/api/v1/circle": {
      "get": {
        "tags": [
          "Invitations"
        ],
        "summary": "Only the invited person's permitted size and preference fields",
        "responses": {
          "200": {
            "description": "Scoped read-only size cards"
          }
        }
      }
    },
    "/api/v1/circle/{id}": {
      "delete": {
        "tags": [
          "Invitations"
        ],
        "summary": "Leave a viewed size circle",
        "responses": {
          "200": {
            "description": "Membership revoked"
          }
        }
      }
    },
    "/api/v1/members/{id}": {
      "delete": {
        "tags": [
          "Invitations"
        ],
        "summary": "Owner revokes an accepted viewer grant",
        "responses": {
          "200": {
            "description": "Membership revoked"
          }
        }
      }
    },
    "/api/v1/people": {
      "post": {
        "tags": [
          "People"
        ],
        "summary": "Create a new household profile",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "relationship": {
                    "type": "string"
                  },
                  "lifeStage": {
                    "type": "string",
                    "enum": [
                      "adult",
                      "child"
                    ]
                  },
                  "birthYear": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "genderPresentation": {
                    "type": "string",
                    "enum": [
                      "neutral",
                      "woman",
                      "man"
                    ],
                    "description": "Controls an illustrative silhouette only, never garment size"
                  },
                  "notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created person"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/people/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "patch": {
        "tags": [
          "People"
        ],
        "summary": "Update an owned person",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "relationship": {
                    "type": "string"
                  },
                  "lifeStage": {
                    "type": "string",
                    "enum": [
                      "adult",
                      "child"
                    ]
                  },
                  "birthYear": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "genderPresentation": {
                    "type": "string",
                    "enum": [
                      "neutral",
                      "woman",
                      "man"
                    ]
                  },
                  "notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Person updated"
          }
        }
      },
      "delete": {
        "tags": [
          "People"
        ],
        "summary": "Delete person and their records",
        "responses": {
          "200": {
            "description": "Person deleted"
          }
        }
      }
    },
    "/api/v1/people/{id}/photo": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "get": {
        "tags": [
          "Photos"
        ],
        "summary": "Read private profile photo",
        "responses": {
          "200": {
            "description": "Private image bytes",
            "content": {
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "contentEncoding": "binary"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Photos"
        ],
        "summary": "Upload owner-authorized photo",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "photo",
                  "consent"
                ],
                "properties": {
                  "photo": {
                    "type": "string",
                    "format": "binary"
                  },
                  "consent": {
                    "type": "string",
                    "const": "true"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Photo saved"
          }
        }
      },
      "delete": {
        "tags": [
          "Photos"
        ],
        "summary": "Delete profile photo",
        "responses": {
          "200": {
            "description": "Photo deleted"
          }
        }
      }
    },
    "/api/v1/sizes": {
      "post": {
        "tags": [
          "Size & fit"
        ],
        "summary": "Add a garment-specific size and optionally make it preferred",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "personId",
                  "category",
                  "label"
                ],
                "properties": {
                  "personId": {
                    "type": "string"
                  },
                  "category": {
                    "type": "string",
                    "examples": [
                      "T-shirt",
                      "Tank top",
                      "Gloves",
                      "Cap",
                      "Shoes",
                      "Socks",
                      "Shorts"
                    ]
                  },
                  "label": {
                    "type": "string"
                  },
                  "region": {
                    "type": "string",
                    "examples": [
                      "EU",
                      "UK",
                      "US",
                      "JP",
                      "KR",
                      "CN",
                      "INT"
                    ]
                  },
                  "brand": {
                    "type": "string"
                  },
                  "fit": {
                    "type": "string"
                  },
                  "preferred": {
                    "type": "boolean",
                    "description": "Make this the preferred size for the named garment type for this person. First size in a category becomes preferred automatically."
                  },
                  "note": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Size saved"
          }
        }
      }
    },
    "/api/v1/sizes/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "delete": {
        "tags": [
          "Size & fit"
        ],
        "summary": "Delete a size record",
        "responses": {
          "200": {
            "description": "Deleted"
          }
        }
      }
    },
    "/api/v1/sizes/{id}/preferred": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "patch": {
        "tags": [
          "Size & fit"
        ],
        "summary": "Make this the preferred size for its person and garment category",
        "responses": {
          "200": {
            "description": "The preferred garment size was updated"
          },
          "404": {
            "description": "Size does not belong to the signed-in household"
          }
        }
      }
    },
    "/api/v1/measurements": {
      "post": {
        "tags": [
          "Size & fit"
        ],
        "summary": "Record a dated tape measurement or separately labeled screen estimate in cm",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "personId",
                  "key",
                  "valueCm"
                ],
                "properties": {
                  "personId": {
                    "type": "string"
                  },
                  "key": {
                    "type": "string",
                    "examples": [
                      "height",
                      "chest",
                      "hips",
                      "inseam",
                      "foot"
                    ]
                  },
                  "valueCm": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "tape",
                      "screen_estimate"
                    ],
                    "description": "Only tape measurements are used for brand chart fitting."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Measurement recorded as millimetres with source provenance"
          }
        }
      }
    },
    "/api/v1/measurements/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "delete": {
        "tags": [
          "Size & fit"
        ],
        "summary": "Delete measurement entry",
        "responses": {
          "200": {
            "description": "Deleted"
          }
        }
      }
    },
    "/api/v1/preferences": {
      "post": {
        "tags": [
          "Preferences"
        ],
        "summary": "Save a favorite or dislike",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "personId",
                  "kind",
                  "sentiment",
                  "value"
                ],
                "properties": {
                  "personId": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "color",
                      "material",
                      "style",
                      "brand",
                      "pattern",
                      "fit",
                      "other"
                    ]
                  },
                  "sentiment": {
                    "type": "string",
                    "enum": [
                      "like",
                      "dislike"
                    ]
                  },
                  "value": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Preference saved"
          }
        }
      }
    },
    "/api/v1/preferences/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "delete": {
        "tags": [
          "Preferences"
        ],
        "summary": "Delete preference",
        "responses": {
          "200": {
            "description": "Deleted"
          }
        }
      }
    },
    "/api/v1/wishlist": {
      "post": {
        "tags": [
          "Preferences"
        ],
        "summary": "Add a gift wish",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "personId",
                  "item"
                ],
                "properties": {
                  "personId": {
                    "type": "string"
                  },
                  "item": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Wishlist item saved"
          }
        }
      }
    },
    "/api/v1/wishlist/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "delete": {
        "tags": [
          "Preferences"
        ],
        "summary": "Delete wishlist item",
        "responses": {
          "200": {
            "description": "Deleted"
          }
        }
      }
    },
    "/api/v1/convert": {
      "get": {
        "tags": [
          "Size & fit"
        ],
        "summary": "Approximate size reference conversion",
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "shoes",
                "women",
                "men",
                "kids"
              ]
            }
          },
          {
            "name": "region",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "value",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Conversion reference or null, always with approximate warning"
          }
        }
      }
    },
    "/api/v1/fit": {
      "post": {
        "tags": [
          "Size & fit"
        ],
        "summary": "Compare personal measurements against supplied garment chart",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "personId",
                  "chart"
                ],
                "properties": {
                  "personId": {
                    "type": "string"
                  },
                  "chart": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "label"
                      ],
                      "properties": {
                        "label": {
                          "type": "string"
                        },
                        "min": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "number"
                          }
                        },
                        "max": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Size ranking and measurement coverage"
          }
        }
      }
    },
    "/api/v1/shares": {
      "post": {
        "tags": [
          "Sharing"
        ],
        "summary": "Create a capability link for selected person data",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "personId",
                  "scopes"
                ],
                "properties": {
                  "personId": {
                    "type": "string"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "sizes",
                        "preferences",
                        "measurements",
                        "photo"
                      ]
                    }
                  },
                  "days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 90
                  },
                  "label": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "One-time share URL, expiry, and share ID"
          }
        },
        "description": "Gift fields: occasion (theme key), note (max 280), allowForward, sizeId (shares exactly one size), campaign (slug for anonymous counts)."
      }
    },
    "/api/v1/shares/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "delete": {
        "tags": [
          "Sharing"
        ],
        "summary": "Revoke a capability link",
        "responses": {
          "200": {
            "description": "Link revoked"
          }
        }
      }
    },
    "/api/v1/shared/{token}": {
      "get": {
        "tags": [
          "Sharing"
        ],
        "summary": "Read the data allowed by an active share token",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scoped fields only"
          },
          "404": {
            "description": "Expired or revoked link"
          }
        }
      }
    },
    "/api/v1/shared/{token}/photo": {
      "get": {
        "tags": [
          "Sharing"
        ],
        "summary": "Read only if the token includes photo permission",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Image bytes"
          },
          "403": {
            "description": "Photo permission missing"
          }
        }
      }
    },
    "/api/v1/scan-settings": {
      "patch": {
        "tags": [
          "Phone scan"
        ],
        "summary": "Owner toggles temporary phone scan capability; disabling revokes every active QR link",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "enabled"
                ],
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated setting"
          }
        }
      }
    },
    "/api/v1/scan-sessions": {
      "post": {
        "tags": [
          "Phone scan"
        ],
        "summary": "Owner generates a short-lived write-only QR capability for a selected family member",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "personId"
                ],
                "properties": {
                  "personId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Single-view phone URL and expiry"
          }
        }
      },
      "get": {
        "tags": [
          "Phone scan"
        ],
        "summary": "Owner reads active session and pending size submissions, never exposed to phone bearer",
        "responses": {
          "200": {
            "description": "Private approval queue"
          }
        }
      }
    },
    "/api/v1/scan-sessions/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "delete": {
        "tags": [
          "Phone scan"
        ],
        "summary": "Owner immediately revokes the temporary QR capability",
        "responses": {
          "200": {
            "description": "Revoked"
          }
        }
      }
    },
    "/api/v1/scan-submissions/{id}/approve": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "post": {
        "tags": [
          "Phone scan"
        ],
        "summary": "Owner approves exactly one queued size and saves it as nonpreferred",
        "responses": {
          "200": {
            "description": "Approved"
          },
          "409": {
            "description": "Already reviewed"
          }
        }
      }
    },
    "/api/v1/scan-submissions/{id}/reject": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "post": {
        "tags": [
          "Phone scan"
        ],
        "summary": "Owner rejects one queued size without writing a size record",
        "responses": {
          "200": {
            "description": "Rejected"
          }
        }
      }
    },
    "/api/v1/scan-portal/{token}": {
      "parameters": [
        {
          "name": "token",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "minLength": 64,
            "maxLength": 64
          }
        }
      ],
      "get": {
        "tags": [
          "Phone scan"
        ],
        "summary": "Bare session-active response, no household data",
        "responses": {
          "200": {
            "description": "Active flag and expiry"
          },
          "410": {
            "description": "Expired"
          }
        }
      },
      "post": {
        "tags": [
          "Phone scan"
        ],
        "summary": "Token bearer may submit one unapproved size, never read existing records",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "category",
                  "label",
                  "region"
                ],
                "properties": {
                  "category": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  },
                  "region": {
                    "type": "string"
                  },
                  "brand": {
                    "type": "string"
                  },
                  "fit": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued for desktop approval"
          },
          "429": {
            "description": "Rate or session limit"
          }
        }
      }
    },
    "/api/v1/tryons": {
      "post": {
        "tags": [
          "Virtual try-on"
        ],
        "summary": "Consume one prepaid credit to generate an adult virtual look",
        "description": "Requires explicit photo consent, a prepaid credit and a configured FASHN or fal provider. Child profiles are ineligible.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "personId",
                  "garment",
                  "consentExternal"
                ],
                "properties": {
                  "personId": {
                    "type": "string"
                  },
                  "garment": {
                    "type": "string",
                    "format": "binary"
                  },
                  "consentExternal": {
                    "type": "string",
                    "const": "true"
                  },
                  "provider": {
                    "type": "string",
                    "description": "quality, economy, speed, or an explicit provider ID"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted and charged one prepaid credit"
          },
          "402": {
            "description": "Paid credit required"
          },
          "503": {
            "description": "Provider key missing"
          }
        }
      }
    },
    "/api/tryon-billing": {
      "get": {
        "tags": [
          "Virtual try-on"
        ],
        "summary": "Read authenticated household prepaid look credits",
        "responses": {
          "200": {
            "description": "Credit balance and checkout availability"
          }
        }
      },
      "post": {
        "tags": [
          "Virtual try-on"
        ],
        "summary": "Create authenticated Stripe checkout for ten prepaid look credits",
        "responses": {
          "200": {
            "description": "Hosted checkout URL"
          },
          "503": {
            "description": "Billing not configured"
          }
        }
      }
    },
    "/api/tryon-webhook": {
      "post": {
        "tags": [
          "Virtual try-on"
        ],
        "summary": "Receive and verify Stripe checkout session events",
        "description": "Stripe signature is required. Paid sessions grant credits idempotently.",
        "responses": {
          "200": {
            "description": "Event acknowledged"
          },
          "400": {
            "description": "Invalid signature"
          }
        }
      }
    },
    "/api/v1/tryons/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "get": {
        "tags": [
          "Virtual try-on"
        ],
        "summary": "Poll and retrieve own try-on job",
        "responses": {
          "200": {
            "description": "Job state and result reference"
          }
        }
      }
    },
    "/api/v1/tryons/{id}/image": {
      "parameters": [
        {
          "$ref": "#/components/parameters/id"
        }
      ],
      "get": {
        "tags": [
          "Virtual try-on"
        ],
        "summary": "Retrieve private generated image when ready",
        "responses": {
          "200": {
            "description": "Generated image"
          },
          "404": {
            "description": "Not ready"
          }
        }
      }
    },
    "/api/v1/preferences/quiz": {
      "post": {
        "tags": [
          "Preferences"
        ],
        "summary": "Save six confirmed fit personality preferences for an owned person",
        "responses": {
          "201": {
            "description": "Preferences saved"
          },
          "401": {
            "description": "Account required"
          }
        }
      }
    },
    "/api/merchant": {
      "get": {
        "tags": [
          "Merchant"
        ],
        "summary": "List merchant draft workspaces owned by the authenticated account",
        "responses": {
          "200": {
            "description": "Owned stores"
          },
          "401": {
            "description": "Account required"
          }
        }
      },
      "post": {
        "tags": [
          "Merchant"
        ],
        "summary": "Create a free merchant workspace for a supported platform, without connecting store credentials",
        "responses": {
          "201": {
            "description": "Draft workspace created, setup still required"
          },
          "401": {
            "description": "Account required"
          }
        }
      }
    },
    "/api/merchant/chart": {
      "post": {
        "tags": [
          "Merchant"
        ],
        "summary": "Validate and normalize a merchant supplied size chart without accessing shopper information or installing a platform app",
        "description": "Read only calculation. Accepts centimetres or inches, up to 100 size rows. A successful response does not establish store ownership, synchronize a product, or guarantee fit.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "platform",
                  "productId",
                  "brand",
                  "region",
                  "sourceUrl",
                  "unit",
                  "ranges"
                ],
                "properties": {
                  "platform": {
                    "type": "string",
                    "enum": [
                      "shopify",
                      "woocommerce",
                      "bigcommerce",
                      "adobe",
                      "wix",
                      "squarespace",
                      "salesforce",
                      "commercetools",
                      "shopware",
                      "prestashop"
                    ]
                  },
                  "productId": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "brand": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "region": {
                    "type": "string",
                    "maxLength": 16
                  },
                  "sourceUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "unit": {
                    "type": "string",
                    "enum": [
                      "cm",
                      "in"
                    ]
                  },
                  "ranges": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": [
                        "label",
                        "min",
                        "max"
                      ],
                      "properties": {
                        "label": {
                          "type": "string"
                        },
                        "min": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "number"
                          }
                        },
                        "max": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Normalized chart in centimetres with explicit unverified provenance"
          },
          "401": {
            "description": "Account required"
          },
          "422": {
            "description": "Invalid merchant chart"
          }
        }
      }
    },
    "/api/agent-capabilities": {
      "get": {
        "tags": [
          "Agent"
        ],
        "summary": "Discover current agent and optional x402 integration capabilities",
        "responses": {
          "200": {
            "description": "Capability status including inactive payment layer"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": [
          "Agent"
        ],
        "summary": "Authenticated MCP JSON-RPC tool endpoint using 2026-07-28 server/discover, tools/list, tools/call",
        "responses": {
          "200": {
            "description": "JSON-RPC tool result"
          },
          "401": {
            "description": "Account required"
          }
        }
      }
    },
    "/api/v1/account": {
      "delete": {
        "tags": [
          "Household"
        ],
        "summary": "Permanently delete the signed in account and all its data",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "confirm"
                ],
                "properties": {
                  "confirm": {
                    "type": "string",
                    "enum": [
                      "DELETE MY ACCOUNT"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account, household, photos and sign in removed"
          },
          "400": {
            "description": "Missing confirmation phrase"
          },
          "401": {
            "description": "Not signed in"
          }
        }
      }
    },
    "/api/v1/shared/{token}/size-requests": {
      "post": {
        "tags": [
          "Gift cards"
        ],
        "summary": "Request missing sizes from a card (categories[]), ask for an email update (category, email) or confirm it (category, code). Each requested category gets its own status.",
        "responses": {
          "200": {
            "description": "All requests handled"
          },
          "207": {
            "description": "Some requests failed, see results"
          },
          "422": {
            "description": "No request could be saved"
          },
          "429": {
            "description": "Limit reached"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "categories": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "category": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/api/v1/shared/{token}/fit-product": {
      "post": {
        "tags": [
          "Will this fit"
        ],
        "summary": "Look up a public product page within the card's scope (approved stores only)",
        "responses": {
          "200": {
            "description": "status found, manual or invalid, with name, brand, charts, variants and availability"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/api/v1/fit-product": {
      "post": {
        "tags": [
          "Will this fit"
        ],
        "summary": "Look up a public product page for the owner",
        "responses": {
          "200": {
            "description": "Product lookup result"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/fit-purchases": {
      "get": {
        "tags": [
          "Will this fit"
        ],
        "summary": "List saved purchases for a person (?personId=)",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "post": {
        "tags": [
          "Will this fit"
        ],
        "summary": "Save a purchase",
        "responses": {
          "201": {
            "description": "Saved"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "personId": {
                    "type": "string"
                  },
                  "product": {
                    "type": "string"
                  },
                  "brand": {
                    "type": "string"
                  },
                  "retailer": {
                    "type": "string"
                  },
                  "category": {
                    "type": "string"
                  },
                  "sizeLabel": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/fit-purchases/{id}": {
      "patch": {
        "tags": [
          "Will this fit"
        ],
        "summary": "Record fit feedback",
        "responses": {
          "200": {
            "description": "Saved"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "outcome": {
                    "enum": [
                      "too_small",
                      "fit_well",
                      "too_large",
                      null
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Will this fit"
        ],
        "summary": "Delete a saved purchase",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/v1/gift-size-requests": {
      "get": {
        "tags": [
          "Gift cards"
        ],
        "summary": "Open size requests for the household, without requester identity",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/v1/gift-size-requests/{id}": {
      "delete": {
        "tags": [
          "Gift cards"
        ],
        "summary": "Dismiss a size request",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/v1/funnel": {
      "post": {
        "tags": [
          "Analytics"
        ],
        "summary": "Count an anonymous client step (allowlisted events only)",
        "responses": {
          "202": {
            "description": "Counted"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {
                    "type": "string"
                  },
                  "campaign": {
                    "type": "string"
                  },
                  "detail": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "security": []
      },
      "get": {
        "tags": [
          "Analytics"
        ],
        "summary": "Funnel summary for administrators (?days=)",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "id": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "requestBodies": {
      "HouseholdName": {
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "name"
              ],
              "properties": {
                "name": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Signed-in owner required"
      }
    }
  },
  "x-privacy-boundary": "Private Site identity is not interchangeable with external partner OAuth. Sharing links are capabilities but still subject to private Site access."
}