---
title: "Create a template"
method: POST
path: "/config-template"
tags: ["Templates"]
---

# Create a template

`POST /config-template`

## Request

- Base URL: `https://api.qrcodly.de/api/v1`
- URL: `https://api.qrcodly.de/api/v1/config-template`
- Auth: HTTP bearer

Saves a QR code styling configuration as a reusable template with a name. Templates store colors, dot styles, corner styles, margins, and embedded images.

## Request body

- object
  - `name` string, required: Template name (max 50 characters)
  - `config` object, required: QR code styling configuration stored in this template
    - `width` number, required: QR code width in pixels
    - `height` number, required: QR code height in pixels
    - `margin` number, required: Quiet zone margin around the QR code in pixels
    - `image` string: Base64-encoded logo image to embed in the center of the QR code. Max size 1 MB.
    - `imageOptions` object, required: Options for the embedded logo image
      - `hideBackgroundDots` boolean, required: Whether to hide QR code dots behind the embedded logo image
    - `dotsOptions` object, required: Styling for the QR code data dots
      - `type` 'dots' | 'rounded' | 'classy' | 'classy-rounded' | 'square' | 'extra-rounded', required: Shape style of the QR code data dots: dots, rounded, classy, classy-rounded, square, or extra-rounded
      - `style` union, required: Color or gradient for the data dots
        - object
          - `type` 'hex', required
          - `value` string, required
        - object
          - `type` 'rgba', required
          - `value` string, required
        - object
          - `type` 'gradient', required
          - `gradientType` 'radial' | 'linear', required
          - `rotation` number, nullable, required
          - `colorStops` object[], required
            - `offset` number, required
            - `color` string, required
    - `cornersSquareOptions` object, required: Styling for the three corner squares (finder patterns)
      - `type` 'dot' | 'square' | 'extra-rounded', required: Shape style of the corner squares: dot, square, or extra-rounded
      - `style` union, required: Color or gradient for the corner squares
        - object
          - `type` 'hex', required
          - `value` string, required
        - object
          - `type` 'rgba', required
          - `value` string, required
        - object
          - `type` 'gradient', required
          - `gradientType` 'radial' | 'linear', required
          - `rotation` number, nullable, required
          - `colorStops` object[], required
            - `offset` number, required
            - `color` string, required
    - `cornersDotOptions` object, required: Styling for the dots inside the corner squares
      - `type` 'dot' | 'square', required: Shape style of the corner dots: dot or square
      - `style` union, required: Color or gradient for the corner dots
        - object
          - `type` 'hex', required
          - `value` string, required
        - object
          - `type` 'rgba', required
          - `value` string, required
        - object
          - `type` 'gradient', required
          - `gradientType` 'radial' | 'linear', required
          - `rotation` number, nullable, required
          - `colorStops` object[], required
            - `offset` number, required
            - `color` string, required
    - `backgroundOptions` object, required: QR code background styling
      - `style` union, required: Background color or gradient
        - object
          - `type` 'hex', required
          - `value` string, required
        - object
          - `type` 'rgba', required
          - `value` string, required
        - object
          - `type` 'gradient', required
          - `gradientType` 'radial' | 'linear', required
          - `rotation` number, nullable, required
          - `colorStops` object[], required
            - `offset` number, required
            - `color` string, required

## Response `200`

Default Response

- object
  - `id` string, uuid, required: Unique identifier (UUID v4)
  - `createdAt` string, date-time, required: Timestamp when the resource was created (ISO 8601)
  - `updatedAt` string, date-time, nullable, required: Timestamp when the resource was last updated (ISO 8601), or null if never updated
  - `config` object, required: QR code styling configuration stored in this template
    - `width` number, required: QR code width in pixels
    - `height` number, required: QR code height in pixels
    - `margin` number, required: Quiet zone margin around the QR code in pixels
    - `image` string: Base64-encoded logo image to embed in the center of the QR code. Max size 1 MB.
    - `imageOptions` object, required: Options for the embedded logo image
      - `hideBackgroundDots` boolean, required: Whether to hide QR code dots behind the embedded logo image
    - `dotsOptions` object, required: Styling for the QR code data dots
      - `type` 'dots' | 'rounded' | 'classy' | 'classy-rounded' | 'square' | 'extra-rounded', required: Shape style of the QR code data dots: dots, rounded, classy, classy-rounded, square, or extra-rounded
      - `style` union, required: Color or gradient for the data dots
        - object
          - `type` 'hex', required
          - `value` string, required
        - object
          - `type` 'rgba', required
          - `value` string, required
        - object
          - `type` 'gradient', required
          - `gradientType` 'radial' | 'linear', required
          - `rotation` number, nullable, required
          - `colorStops` object[], required
            - `offset` number, required
            - `color` string, required
    - `cornersSquareOptions` object, required: Styling for the three corner squares (finder patterns)
      - `type` 'dot' | 'square' | 'extra-rounded', required: Shape style of the corner squares: dot, square, or extra-rounded
      - `style` union, required: Color or gradient for the corner squares
        - object
          - `type` 'hex', required
          - `value` string, required
        - object
          - `type` 'rgba', required
          - `value` string, required
        - object
          - `type` 'gradient', required
          - `gradientType` 'radial' | 'linear', required
          - `rotation` number, nullable, required
          - `colorStops` object[], required
            - `offset` number, required
            - `color` string, required
    - `cornersDotOptions` object, required: Styling for the dots inside the corner squares
      - `type` 'dot' | 'square', required: Shape style of the corner dots: dot or square
      - `style` union, required: Color or gradient for the corner dots
        - object
          - `type` 'hex', required
          - `value` string, required
        - object
          - `type` 'rgba', required
          - `value` string, required
        - object
          - `type` 'gradient', required
          - `gradientType` 'radial' | 'linear', required
          - `rotation` number, nullable, required
          - `colorStops` object[], required
            - `offset` number, required
            - `color` string, required
    - `backgroundOptions` object, required: QR code background styling
      - `style` union, required: Background color or gradient
        - object
          - `type` 'hex', required
          - `value` string, required
        - object
          - `type` 'rgba', required
          - `value` string, required
        - object
          - `type` 'gradient', required
          - `gradientType` 'radial' | 'linear', required
          - `rotation` number, nullable, required
          - `colorStops` object[], required
            - `offset` number, required
            - `color` string, required
  - `createdBy` string, required: User ID of the template owner
  - `name` string, required: Template name (max 50 characters)
  - `previewImage` string, nullable, required: URL to a preview image showing the template styling

## Other responses

- `400`: Bad Request — invalid input or validation failure
- `401`: Unauthorized — missing or invalid Bearer token.
- `429`: Too Many Requests — rate limit exceeded. Retry after the rate limit window resets.

---

[API](https://skmtc.dev/qrcodly/apis/qrcodly-api.md) · [All operations](https://skmtc.dev/qrcodly/apis/qrcodly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/qrcodly/apis/qrcodly-api/revisions/b7e95eb68866?raw)