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

# Create shortlink

> Create a shortlink via the Dashlink Links API



## OpenAPI

````yaml POST /api/v1/shortlinks/create_shortlink
openapi: 3.1.0
info:
  title: Dashlink API
  description: Dashlink Links API for creating and managing shortlinks.
  version: 1.0.0
servers:
  - url: https://dashlink.ai
security:
  - ApiKeyAuth: []
paths:
  /api/v1/shortlinks/create_shortlink:
    post:
      tags:
        - Shortlinks
      summary: Create a shortlink
      description: >-
        Create a shortlink for the authenticated workspace with optional UTM
        parameters, custom preview image, and QR code generation.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                destination_url:
                  type: string
                  format: uri
                  description: Target URL the shortlink will redirect to.
                domain:
                  type: string
                  description: >-
                    Dashlink Domain document name (ID). The effective hostname
                    is taken from the Dashlink Domain.domain_name field.
                title:
                  type: string
                  description: Human-readable title for the shortlink.
                back_half:
                  type: string
                  description: >-
                    Custom back-half path segment, e.g. `summer-sale`. If
                    omitted, the system auto-generates a unique code per domain.
                utm_analytics_enabled:
                  type: string
                  description: Whether UTM analytics are enabled (`true`/`false`).
                  default: 'false'
                utm_campaign:
                  type: string
                utm_term:
                  type: string
                utm_medium:
                  type: string
                utm_content:
                  type: string
                utm_source:
                  type: string
                utm_id:
                  type: string
                is_custom_preview:
                  type: string
                  description: >-
                    Whether custom preview metadata/image are used
                    (`true`/`false`).
                  default: 'false'
                preview_title:
                  type: string
                preview_description:
                  type: string
                preview_image:
                  type: string
                  format: binary
                  description: >-
                    Custom preview image file. Allowed extensions: jpeg, jpg,
                    png, svg. Max size: 500KB.
                qr_code_enabled:
                  type: string
                  description: Whether to generate a QR code (`true`/`false`).
                  default: 'false'
                qr_code_color:
                  type: string
                  description: HEX color value used for the QR code (e.g. `#FF7908`).
              required:
                - destination_url
                - domain
      responses:
        '200':
          description: Shortlink created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortlinkResponse'
        '400':
          description: Bad request - validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required or failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Permission denied or feature limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict - duplicate destination URL or back-half conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ShortlinkResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            status:
              type: string
              example: success
              description: Status of the operation.
            message:
              type: string
              example: Shortlink created successfully.
              description: Human-readable message describing the result.
            shortlink:
              $ref: '#/components/schemas/Shortlink'
          required:
            - status
            - message
            - shortlink
      required:
        - data
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            status_code:
              type: integer
            code:
              type: string
            details:
              type: object
              additionalProperties: true
          required:
            - message
            - status_code
            - code
    Shortlink:
      type: object
      properties:
        name:
          type: string
          description: Internal ID of the Shortlink document.
        title:
          type: string
          description: Human-readable title for the shortlink.
        destination_url:
          type: string
          format: uri
          description: Target URL the shortlink redirects to.
        shortlink_url:
          type: string
          format: uri
          description: Fully-qualified short URL.
        is_custom_preview:
          type: boolean
          description: Whether custom preview metadata/image are enabled.
        preview_title:
          type: string
          description: Custom preview title for link unfurls.
        preview_description:
          type: string
          description: Custom preview description for link unfurls.
        preview_image:
          type: string
          format: uri
          description: URL to the preview image file.
        qr_code_enabled:
          type: boolean
          description: Whether QR code generation is enabled for this shortlink.
      required:
        - name
        - destination_url
        - shortlink_url
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````