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

# Create link

> Requires the `links:write` scope. Internal and private addresses, and destinations flagged
as phishing or malware, return `400 blocked_destination`.




## OpenAPI

````yaml /openapi.yaml post /links
openapi: 3.1.0
info:
  title: URLdn API
  version: 1.0.0
  description: >
    Create and manage short links, tags and custom domains, read click
    analytics, generate

    QR codes and ask the AI analyst. Included on every plan, with limits by
    plan. Limits apply

    to your whole account, across all its keys.


    Keep API keys on your server: anything in front-end code can be read by
    anyone.
servers:
  - url: https://api.urldn.com/v1
security:
  - apiKey: []
tags:
  - name: Links
  - name: Tags
  - name: Domains
  - name: Analytics
  - name: QR codes
  - name: AI analyst
  - name: Account
paths:
  /links:
    post:
      tags:
        - Links
      summary: Create link
      description: >
        Requires the `links:write` scope. Internal and private addresses, and
        destinations flagged

        as phishing or malware, return `400 blocked_destination`.
      operationId: createLink
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLink'
      responses:
        '201':
          description: The new link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/QuotaExceeded'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: >-
            `slug_taken`, or `idempotency_in_progress` when a request with this
            key is still running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: '`idempotency_key_reused`: this key was used with a different body'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >
        Any unique value of up to 255 printable characters. Retrying with the
        same key and

        body within 24 hours returns the first response with
        `Idempotent-Replayed: true`

        and creates nothing. A failed attempt frees the key.
      schema:
        type: string
        maxLength: 255
  schemas:
    CreateLink:
      type: object
      additionalProperties: false
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          maxLength: 2048
          description: Must be https. Internal and private addresses are rejected.
        customSlug:
          type: string
          pattern: ^[A-Za-z0-9_-]{4,14}$
        domain:
          type: string
          description: One of your verified custom domains, by name or id
        title:
          type: string
          maxLength: 120
        tags:
          type: array
          maxItems: 20
          items:
            type: string
            maxLength: 40
    Link:
      type: object
      required:
        - id
        - shortUrl
        - shortCode
        - url
        - domain
        - title
        - tags
        - isActive
        - isQrCode
        - hasPassword
        - expiresAt
        - createdAt
      properties:
        id:
          type: string
        shortUrl:
          type: string
          format: uri
        shortCode:
          type: string
        url:
          type: string
          format: uri
          description: The destination
        domain:
          type:
            - string
            - 'null'
          description: Your custom domain, or null for the default
        title:
          type:
            - string
            - 'null'
        tags:
          type: array
          items:
            type: string
        isActive:
          type: boolean
        isQrCode:
          type: boolean
        hasPassword:
          type: boolean
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: A stable machine-readable code
          examples:
            - quota_exceeded
        message:
          type: string
        details:
          type: object
          additionalProperties: true
  responses:
    BadRequest:
      description: >-
        `invalid_request`, `invalid_json`, `invalid_cursor` or
        `blocked_destination`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: '`missing_api_key`, `invalid_api_key` or `revoked_api_key`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    QuotaExceeded:
      description: >-
        `quota_exceeded`: your plan's limit is used up. `details` has the limit
        and an upgrade link.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: '`plan_required`, `insufficient_scope` or `domain_not_allowed`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >-
        `rate_limited`, `monthly_quota_exceeded` or `too_many_auth_failures`.
        Wait for `Retry-After` seconds.
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Your API key: `Authorization: Bearer urldn_live_...`'

````

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