> ## 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 a Shortlink

> API to create a shortlink for the current principal (either logged-in user or API key) while checking feature limits. Supports uploading a preview image and attaching it to the Shortlink document. All parameters are expected in FormData.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/shortlinks/create_shortlink
openapi: 3.1.0
info:
  title: Dashlink API
  version: 1.0.0
  description: >
    The Dashlink API lets you do programmatically what your team does in the
    Dashlink

    dashboard: create and manage Shortlinks, generate QR codes, organise work
    into

    campaigns, connect your own domains, and read click analytics.


    **Base URL:** `https://api.dashlink.ai`


    **Authentication:** every request needs an API key in the `X-API-Key`
    header.

    Create one in the dashboard under Settings → API Keys.


    ```bash

    curl https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks \
      -H "X-API-Key: dlk_live_..."
    ```


    **Responses** are always wrapped. Success returns `{"data": ...}` and
    failure

    returns `{"error": {"message": ..., "status_code": ..., "code": ...}}`, so
    one

    code path handles every endpoint.


    **Rate limits** depend on your plan, from 500 requests per minute on Free to

    uncapped on Enterprise. Every response carries `X-RateLimit-Remaining`.
  contact:
    name: Dashlink Support
    email: support@dashlink.ai
  license:
    name: Proprietary
    url: https://dashlink.ai/terms
servers:
  - url: https://api.dashlink.ai
    description: Production
security:
  - apiKey: []
tags:
  - name: Links
    description: >-
      Create, read, update and delete Shortlinks. Deletion is bulk-only: to
      delete a single link, pass a one-element array.
  - name: App Dynamic Links
    description: >-
      Links that route to an iOS or Android app when it is installed and fall
      back to the web when it is not. App dynamic links are Shortlink records,
      so an API key granted the `shortlinks` module covers them.
  - name: QR Codes
    description: >-
      Generate and style QR codes. Every QR code is backed by a Shortlink, so
      scans are tracked the same way clicks are.
  - name: Campaigns
    description: >-
      Group links into campaigns and channels so their performance can be
      compared as a unit.
  - name: Analytics
    description: >-
      Click and scan analytics at three scopes: the whole organization, a single
      link, or a campaign. All analytics endpoints are read-only and are subject
      to your plan's retention window.
  - name: Branded Links
    description: >-
      Connect your own domain so Shortlinks carry your brand instead of the
      default Dashlink domain. Covers custom domains you own and platform
      subdomains Dashlink hosts for you.
  - name: Tags
    description: Organise links and QR codes with tags, and filter lists by them.
  - name: UTM Templates
    description: >-
      Reusable sets of UTM parameters, so campaign tagging stays consistent
      across everyone creating links.
  - name: Dynamic Link Templates
    description: >-
      Reusable app setup for Dynamic Links: domain, desktop fallback, and iOS
      and Android behaviour. Applying a template fills the create form. It does
      not change links already created.
  - name: Users & Organization
    description: Read your organization's profile and its members.
  - name: Account Limits
    description: >-
      What your plan allows and how much of it you have used. Check these before
      a bulk create so you fail early rather than halfway through.
paths:
  /api/v1/shortlinks/create_shortlink:
    post:
      tags:
        - Links
      summary: Create a Shortlink
      description: >-
        API to create a shortlink for the current principal (either logged-in
        user or API key) while checking feature limits. Supports uploading a
        preview image and attaching it to the Shortlink document. All parameters
        are expected in FormData.
      operationId: shortlinks_create_shortlink
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                back_half:
                  type: string
                  description: The path after the domain. Generated at random when omitted.
                destination_payload:
                  type: string
                  description: >-
                    JSON object holding the type-specific fields the destination
                    is built from (for example a `url` key, or the
                    wifi/sms/call/email/vcard fields). Required for non-`url`
                    destination types.
                destination_type:
                  type: string
                  description: >-
                    The kind of destination to build: `url`, `wifi`, `sms`,
                    `call`, `email` or `vcard`. Defaults to `url`.
                destination_url:
                  type: string
                  description: The URL the link sends visitors to.
                domain:
                  type: string
                  description: >-
                    The domain to build the link on. Uses your default domain
                    when omitted.
                dynamic_routing_enabled:
                  type: string
                  description: >-
                    Whether `routing_rules` are evaluated for this link. When
                    off, the base destination is always served. Defaults to
                    false.
                expiration_url:
                  type: string
                  description: >-
                    URL to redirect visitors to once the link has expired.
                    Optional.
                expires_at:
                  type: string
                  description: >-
                    ISO-8601 timestamp after which the link expires. Must
                    include a timezone (`Z` or an offset).
                is_custom_preview:
                  type: string
                  description: >-
                    Whether the link uses custom link-preview metadata
                    (`preview_title`, `preview_description`, `preview_image`)
                    instead of an auto-generated preview. Defaults to false.
                link_expiration_enabled:
                  type: string
                  description: >-
                    Whether the link stops resolving after `expires_at`.
                    Defaults to false.
                password:
                  type: string
                  description: Password required to open the link.
                password_protected:
                  type: string
                  description: Whether the link requires a password.
                preview_description:
                  type: string
                  description: >-
                    Custom link-preview description shown when the link is
                    shared.
                preview_title:
                  type: string
                  description: >-
                    Custom link-preview (Open Graph) title shown when the link
                    is shared.
                qr_code_color:
                  type: string
                  description: >-
                    Convenience hex color applied to both the QR pattern and the
                    corner eyes when a link's QR code is generated. Defaults to
                    `#000000`.
                qr_code_enabled:
                  type: string
                  description: >-
                    Whether to generate a QR code for this link. Defaults to
                    false.
                routing_rules:
                  type: string
                  description: >-
                    Ordered JSON array (max 10) of conditional destination
                    overrides; the first rule whose `condition` matches wins.
                    Each rule carries a `destination_type`/`destination_payload`
                    and a `condition` tree over properties such as
                    `req.country`, `agent.os` or `calendar.weekday`.
                title:
                  type: string
                  description: Human-readable name shown in the dashboard.
                utm_analytics_enabled:
                  type: string
                  description: >-
                    Whether UTM parameters are appended to the destination and
                    tracked. Defaults to false.
                utm_campaign:
                  type: string
                  description: '`utm_campaign` value appended to the destination URL.'
                utm_content:
                  type: string
                  description: '`utm_content` value appended to the destination URL.'
                utm_id:
                  type: string
                  description: '`utm_id` value appended to the destination URL.'
                utm_medium:
                  type: string
                  description: '`utm_medium` value appended to the destination URL.'
                utm_source:
                  type: string
                  description: '`utm_source` value appended to the destination URL.'
                utm_term:
                  type: string
                  description: '`utm_term` value appended to the destination URL.'
                preview_image:
                  type: string
                  format: binary
                  description: >-
                    Custom link-preview image. Sent as an uploaded file;
                    returned as a URL.
              required:
                - destination_url
      responses:
        '200':
          description: Success.
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Requests allowed per minute on your plan. `-1` means uncapped.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Requests left in the current window.
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the window resets.
            X-RateLimit-Plan:
              schema:
                type: string
              description: The plan the limit was derived from.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: The endpoint's payload.
                    additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    BadRequest:
      description: A parameter is missing, malformed, or outside its allowed range.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: >-
                Invalid sort_by option. Choose from name, most_recent,
                last_modified
              status_code: 400
              code: INVALID_PARAMETER
              details:
                parameter: sort_by
                value: most_clicked
                valid_options:
                  - name
                  - most_recent
                  - last_modified
    Unauthorized:
      description: The API key is missing, malformed, expired, or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Authentication required. Please provide valid credentials.
              status_code: 401
              code: AUTHENTICATION_REQUIRED
    Forbidden:
      description: >-
        The key is valid but is not permitted to do this. Usually a restricted
        key without the right module grant, or a read-only key attempting a
        write.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: You do not have permission to perform this action.
              status_code: 403
              code: PERMISSION_DENIED
    NotFound:
      description: >-
        No such resource. Also returned for a resource that belongs to another
        organization, so the response cannot be used to discover which ids
        exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Shortlink not found.
              status_code: 404
              code: NOT_FOUND
    Conflict:
      description: >-
        The resource already exists. Most often a back-half already taken on
        that domain.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: This back-half is already in use on that domain.
              status_code: 409
              code: DUPLICATE_ENTRY
    RateLimited:
      description: >-
        Too many requests this minute. `Retry-After` says how many seconds to
        wait; `X-RateLimit-Reset` says when the window rolls over.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Rate limit exceeded. Please retry in 43 seconds.
              status_code: 429
              code: RATE_LIMIT_EXCEEDED
    ServerError:
      description: Something failed on our side. Safe to retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: An unexpected error occurred. Please try again.
              status_code: 500
              code: INTERNAL_SERVER_ERROR
  schemas:
    Error:
      type: object
      description: The single error shape returned by every endpoint.
      properties:
        error:
          type: object
          required:
            - message
            - status_code
          properties:
            message:
              type: string
              description: A human-readable description of what went wrong.
            status_code:
              type: integer
              description: Matches the HTTP status code of the response.
            code:
              type: string
              description: >-
                A stable machine-readable code such as `NOT_FOUND` or
                `RATE_LIMIT_EXCEEDED`. Branch on this rather than on the message
                text.
            details:
              type: object
              description: >-
                Which parameter was at fault, when the error is about a
                parameter.
              additionalProperties: true
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your API key, for example `dlk_live_...`. Create one in the dashboard
        under Settings → API Keys. Keys are shown once at creation and stored
        only as a hash, so they cannot be recovered.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.