> ## 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.

# List links

> Requires the `links:read` scope. Returns your links, newest first. Pass `nextCursor` back
as `cursor` to get the next page, until `hasMore` is `false`.




## OpenAPI

````yaml GET /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:
    get:
      tags:
        - Links
      summary: List links
      description: >
        Requires the `links:read` scope. Returns your links, newest first. Pass
        `nextCursor` back

        as `cursor` to get the next page, until `hasMore` is `false`.
      operationId: listLinks
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: The `nextCursor` of the previous page
          schema:
            type: string
        - $ref: '#/components/parameters/FilterDomain'
        - $ref: '#/components/parameters/FilterTag'
        - $ref: '#/components/parameters/FilterSearch'
        - $ref: '#/components/parameters/FilterIsActive'
      responses:
        '200':
          description: One page of links
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - hasMore
                  - nextCursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Link'
                  hasMore:
                    type: boolean
                  nextCursor:
                    type:
                      - string
                      - 'null'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    FilterDomain:
      name: domain
      in: query
      description: >-
        Only links on this custom domain. `default` means links on the default
        domain.
      schema:
        type: string
    FilterTag:
      name: tag
      in: query
      description: Only links with this tag
      schema:
        type: string
        maxLength: 40
    FilterSearch:
      name: search
      in: query
      description: Text to find in the destination, alias or title. Case doesn't matter.
      schema:
        type: string
        maxLength: 100
    FilterIsActive:
      name: isActive
      in: query
      description: Only active or only inactive links
      schema:
        type: boolean
  schemas:
    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'
    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.