> ## Documentation Index
> Fetch the complete documentation index at: https://learn.biq.li/llms.txt
> Use this file to discover all available pages before exploring further.

# Style a QR code

> Configure QR shapes, flat colors, gradients, inheritance, and the default logo.

Use `qr_config` when creating or updating a static or dynamic QR code. The same design contract applies to both types. Create, Retrieve, Update, and List responses always return a complete normalized configuration with renderer defaults filled in.

## Shape fields

| Field           | Accepted values                                                   | Default  |
| --------------- | ----------------------------------------------------------------- | -------- |
| `matrixStyle`   | `square`, `dots`, `organic`, `vertical-pills`, `horizontal-pills` | `square` |
| `eyeFrameStyle` | `square`, `rounded-square`, `circle`                              | `square` |
| `eyeStyle`      | `square`, `rounded-square`, `circle`, `diamond`                   | `square` |

The eye frame does not support `diamond`.

## Flat colors

Each section has a color and a color mode:

| Section    | Mode                | Flat color      | Gradient           |
| ---------- | ------------------- | --------------- | ------------------ |
| Matrix     | `matrixColorMode`   | `matrixColor`   | `matrixGradient`   |
| Eye frame  | `eyeFrameColorMode` | `eyeFrameColor` | `eyeFrameGradient` |
| Eye center | `eyeColorMode`      | `eyeColor`      | `eyeGradient`      |

Set a mode to `flat` or `gradient`. Colors must use six-digit hexadecimal notation such as `#214687`; three-digit hex, alpha channels, CSS names, and RGB strings are rejected.

```json theme={null}
{
  "qr_config": {
    "matrixStyle": "organic",
    "matrixColorMode": "flat",
    "matrixColor": "#214687",
    "eyeFrameStyle": "rounded-square",
    "eyeFrameColorMode": "flat",
    "eyeFrameColor": "#44C8DE",
    "eyeStyle": "circle",
    "eyeColorMode": "flat",
    "eyeColor": "#111827",
    "showLogo": true
  }
}
```

## Gradient object

When a section uses `gradient`, provide its complete gradient object:

```json theme={null}
{
  "colorOne": "#214687",
  "colorTwo": "#44C8DE",
  "angle": "45deg",
  "midpoint": 50
}
```

`midpoint` is an integer from `5` through `95`. It controls where the blended midpoint color appears.

| Angle    | Direction  |
| -------- | ---------- |
| `0deg`   | Up         |
| `45deg`  | Up right   |
| `90deg`  | Right      |
| `135deg` | Down right |
| `180deg` | Down       |
| `225deg` | Down left  |
| `270deg` | Left       |
| `315deg` | Up left    |

## Gradient inheritance and precedence

`applyGradientToAll` and `applyEyeFrameGradientToEye` reproduce the dashboard's **Apply to all** controls.

1. When `matrixColorMode` is `gradient` and `applyGradientToAll` is `true`, `matrixGradient` renders the matrix, eye frames, and eye centers. Eye-frame and eye color/gradient fields remain stored but do not affect rendering.
2. Otherwise, when `eyeFrameColorMode` is `gradient` and `applyEyeFrameGradientToEye` is `true`, `eyeFrameGradient` renders the eye frames and eye centers. Eye color/gradient fields remain stored but do not affect rendering.
3. Otherwise, the matrix, eye frame, and eye center each use their own active flat color or gradient.

If both apply flags are `true`, the matrix gradient wins because it has the highest precedence. `applyGradientToAll: true` requires `matrixColorMode: "gradient"`. `applyEyeFrameGradientToEye: true` requires `eyeFrameColorMode: "gradient"`.

### Matrix gradient applied everywhere

```json theme={null}
{
  "qr_config": {
    "matrixColorMode": "gradient",
    "matrixGradient": {
      "colorOne": "#214687",
      "colorTwo": "#44C8DE",
      "angle": "135deg",
      "midpoint": 50
    },
    "applyGradientToAll": true,
    "applyEyeFrameGradientToEye": false
  }
}
```

### Eye-frame gradient applied to the eye

```json theme={null}
{
  "qr_config": {
    "matrixColorMode": "flat",
    "matrixColor": "#214687",
    "applyGradientToAll": false,
    "eyeFrameColorMode": "gradient",
    "eyeFrameGradient": {
      "colorOne": "#7C3AED",
      "colorTwo": "#EC4899",
      "angle": "90deg",
      "midpoint": 60
    },
    "applyEyeFrameGradientToEye": true
  }
}
```

## Logo visibility

`showLogo` defaults to `true` and uses the standard Biqli logo. Set it to `false` only when the workspace plan includes QR logo customization. Otherwise the API returns `403 upgrade_required` with the current and required plan.

The public API does not accept custom logos. `logoUrl`, `useCustomLogo`, upload data, and arbitrary extra `qr_config` fields return `422 validation_error`.

## Updating an existing design

`PATCH /v1/qr/{qr_id}` recursively merges `qr_config`, including individual gradient properties. Send `qr_config: null` to reset the saved public design. Unknown fields and incomplete active gradients return `422 validation_error`.