openapi: 3.0.0
info:
  title: 'URLR API Reference'
  description: "API powering the features of URLR.<br><br>Note that in order to facilitate integration, we provide SDKs for various languages at https://github.com/URLR.<br><br>Key API principles:<br>\n        <ul>\n        <li>All dates follow **ISO-8601** format</li>\n        <li>Most errors follow **RFC 9457** standard</li>\n        <li>All responses are delivered in English</li>\n    </ul>\n    All requests must include an API key generated in your workspace.\n    The key should be provided in the X-API-KEY HTTP header."
  termsOfService: 'https://urlr.me/en/terms-of-use'
  contact:
    name: URLR
    url: 'https://urlr.me/en'
  license:
    name: 'All rights reserved'
    url: 'https://urlr.me/en/legal-notice'
  version: 2.0.0
servers:
  -
    url: 'https://urlr.me/api/v2'
    description: 'Main API entry point'
paths:
  '/domains/{domain_id}':
    get:
      tags:
        - Domains
      summary: 'Get a domain'
      operationId: domainGet
      parameters:
        -
          name: domain_id
          in: path
          description: 'Domain API ID'
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
  /domains:
    get:
      tags:
        - Domains
      summary: 'List domains'
      operationId: domainList
      responses:
        '200':
          description: 'Domains of user'
          content:
            application/json:
              schema:
                properties:
                  domains: { type: array, items: { $ref: '#/components/schemas/Domain' } }
                type: object
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
    post:
      tags:
        - Domains
      summary: 'Create a domain'
      operationId: domainCreate
      requestBody:
        description: 'You can use this endpoint to add a custom domain to URLR.'
        content:
          application/json:
            schema:
              required:
                - domain
              properties:
                domain:
                  description: Domain
                  type: string
                  format: hostname
                  example: mybrand.com
                  maxLength: 255
                root_url:
                  description: 'Redirect URL for the root of the domain'
                  type: string
                  format: url
              type: object
      responses:
        '201':
          description: Domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '429':
          description: 'Limits Exceeded'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 429 }
                  detail: { type: string }
                type: object
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 409 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
  '/folders/{folder_id}':
    get:
      tags:
        - Folders
      summary: 'Get a folder'
      operationId: folderGet
      parameters:
        -
          name: folder_id
          in: path
          description: 'Folder API ID'
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Folder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
  /folders:
    get:
      tags:
        - Folders
      summary: 'List folders'
      operationId: folderList
      parameters:
        -
          name: workspace_id
          in: query
          description: 'Workspace API ID'
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 'Folders of workspace'
          content:
            application/json:
              schema:
                properties:
                  folders: { type: array, items: { $ref: '#/components/schemas/Folder' } }
                type: object
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
    post:
      tags:
        - Folders
      summary: 'Create a folder'
      operationId: folderCreate
      requestBody:
        description: 'You can use this endpoint to add a folder to URLR.'
        content:
          application/json:
            schema:
              required:
                - workspace_id
                - name
              properties:
                workspace_id:
                  description: 'Workspace API ID'
                  type: string
                  format: uuid
                name:
                  description: Name
                  type: string
                  maxLength: 255
                parent_id:
                  description: 'Folder API ID'
                  type: string
                  format: uuid
                color:
                  description: 'Color of folder'
                  type: string
                  enum: [blue, green, orange, purple, red, rose, yellow, black]
              type: object
      responses:
        '201':
          description: Folder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '429':
          description: 'Limits Exceeded'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 429 }
                  detail: { type: string }
                type: object
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 409 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
  '/links/{link_id}':
    get:
      tags:
        - Links
      summary: 'Get a link'
      operationId: linkGet
      parameters:
        -
          name: link_id
          in: path
          description: 'Link API ID'
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
    delete:
      tags:
        - Links
      summary: 'Delete a link'
      operationId: linkDelete
      parameters:
        -
          name: link_id
          in: path
          description: 'Link API ID'
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
        '500':
          description: 'Internal Error'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 500 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
    patch:
      tags:
        - Links
      summary: 'Edit a link'
      operationId: linkEdit
      parameters:
        -
          name: link_id
          in: path
          description: 'Link API ID'
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: 'Info of the link to edit'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkEditRequest'
      responses:
        '200':
          description: Link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
        '500':
          description: 'Internal Error'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 500 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
  /links:
    get:
      tags:
        - Links
      summary: 'List links'
      operationId: linkList
      parameters:
        -
          name: workspace_id
          in: query
          description: 'Filter by Workspace API ID'
          schema:
            type: string
            format: uuid
        -
          name: folder_id
          in: query
          description: 'Filter by Folder API ID'
          schema:
            type: string
            format: uuid
        -
          name: tag_id
          in: query
          description: 'Filter by Tag API ID'
          schema:
            type: string
            format: uuid
        -
          name: limit
          in: query
          description: 'Number of items per page'
          schema:
            type: integer
            default: 10
            maximum: 50
            minimum: 1
        -
          name: page
          in: query
          description: 'Page number'
          schema:
            type: integer
            default: 1
            minimum: 1
      responses:
        '200':
          description: 'List of links'
          content:
            application/json:
              schema:
                properties:
                  links: { description: 'List of links', type: array, items: { $ref: '#/components/schemas/Link' } }
                  total: { description: 'Total number of links', type: integer }
                  limit: { description: 'Number of items per page', type: integer }
                  pages: { description: 'Total number of pages', type: integer }
                  page: { description: 'Current page number', type: integer }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
    post:
      tags:
        - Links
      summary: 'Create a link'
      operationId: linkCreate
      requestBody:
        description: 'Info of the link to create'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkCreateRequest'
      responses:
        '201':
          description: Link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
        '429':
          description: 'Limits Exceeded'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 429 }
                  detail: { type: string }
                type: object
        '500':
          description: 'Internal Error'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 500 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
  /qrcodes:
    post:
      tags:
        - 'QR Codes'
      summary: 'Create a QR Code'
      operationId: qrcodeCreate
      requestBody:
        description: 'Info of the QR Code to create'
        content:
          application/json:
            schema:
              properties:
                size:
                  description: 'The size of the QR code (px)'
                  type: integer
                  default: 600
                  maximum: 1000
                  minimum: 100
                format:
                  description: 'The format of the QR code'
                  type: string
                  default: png
                  enum: [png, webp, svg]
                margin:
                  description: 'The margin around the QR code (px)'
                  type: integer
                  default: 0
                background_color:
                  description: 'The background color of the QR code (hexadecimal)'
                  type: string
                  default: '#ffffff'
                foreground_color:
                  description: 'The foreground color of the QR code (hexadecimal)'
                  type: string
                  default: '#000000'
              type: object
              oneOf:
                -
                  required: [url, workspace_id]
                  properties: { url: { description: 'URL of the QR Code', type: string, format: url }, workspace_id: { description: 'Workspace API ID', type: string, format: uuid } }
                  type: object
                -
                  required: [link_id]
                  properties: { link_id: { description: 'Link API ID of the QR Code', type: string, format: uuid } }
                  type: object
      responses:
        '201':
          description: 'QR Code'
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
        '429':
          description: 'Limits Exceeded'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 429 }
                  detail: { type: string }
                type: object
        '500':
          description: 'Internal Error'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 500 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
  /statistics:
    get:
      tags:
        - Statistics
      summary: 'Get statistics'
      operationId: statisticGet
      parameters:
        -
          name: link_id
          in: query
          description: 'Link API ID'
          required: true
          schema:
            type: string
            format: uuid
        -
          name: from
          in: query
          description: 'Get statistics from this date'
          required: false
          schema:
            type: string
            format: date-time
        -
          name: to
          in: query
          description: 'Get statistics until this date'
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Statistics
          content:
            application/json:
              schema:
                properties:
                  link_id: { description: 'Link API ID', type: string, format: uuid }
                  visits: { description: 'Total number of visits, combining clicks and scans', type: integer, example: 51 }
                  unique_visits: { description: 'Number of unique visitors, combining clicks and scans', type: integer, example: 32 }
                  clicks: { description: 'Number of clicks', type: integer, example: 42 }
                  scans: { description: 'Number of scans', type: integer, example: 9 }
                type: object
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
  '/workspaces/{workspace_id}':
    get:
      tags:
        - Workspaces
      summary: 'Get a workspace'
      operationId: workspaceGet
      parameters:
        -
          name: workspace_id
          in: path
          description: 'Workspace API ID'
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '404':
          description: 'Not Found'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 404 }
                  detail: { type: string }
                type: object
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
        '422':
          description: 'Validation Failed'
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 422 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
  /workspaces:
    get:
      tags:
        - Workspaces
      summary: 'List workspaces of user'
      operationId: workspaceList
      responses:
        '200':
          description: 'Workspaces of user'
          content:
            application/json:
              schema:
                properties:
                  workspaces: { type: array, items: { $ref: '#/components/schemas/Workspace' } }
                type: object
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                properties:
                  type: { type: string }
                  title: { type: string }
                  status: { type: integer, example: 401 }
                  detail: { type: string }
                type: object
      security:
        -
          ApiKeyAuth: []
components:
  schemas:
    Domain:
      properties:
        id:
          description: 'Domain API ID'
          type: string
          format: uuid
        domain:
          description: Domain
          type: string
          format: hostname
          example: mybrand.com
        root_url:
          description: 'Redirect URL for the root of the domain'
          type: string
          format: url
        created_at:
          description: 'Creation date'
          type: string
          format: date-time
        updated_at:
          description: 'Modification date'
          type: string
          format: date-time
      type: object
    Folder:
      properties:
        id:
          description: 'Folder API ID'
          type: string
          format: uuid
        name:
          description: Name
          type: string
        workspace_id:
          description: 'Workspace API ID'
          type: string
          format: uuid
        parent_id:
          description: 'Parent Folder API ID'
          type: string
          format: uuid
        parent_name:
          description: 'Parent Folder name'
          type: string
        color:
          description: 'Color of folder'
          type: string
          enum:
            - blue
            - green
            - orange
            - purple
            - red
            - rose
            - yellow
            - black
        domain:
          description: Domain
          type: string
          format: hostname
        created_at:
          description: 'Creation date'
          type: string
          format: date-time
        updated_at:
          description: 'Modification date'
          type: string
          format: date-time
      type: object
    Link:
      properties:
        id:
          description: 'Link API ID'
          type: string
          format: uuid
        url:
          description: 'Original URL'
          type: string
        workspace_id:
          description: 'Workspace API ID'
          type: string
          format: uuid
        folder_id:
          description: 'Folder API ID'
          type: string
          format: uuid
        user:
          description: User
          type: string
        domain:
          description: Domain
          type: string
          format: hostname
          example: urlr.me
        code:
          description: 'Short code'
          type: string
          example: xxxxx
          maxLength: 50
          minLength: 2
        label:
          description: Label
          type: string
          maxLength: 255
        password:
          description: 'Password: "**********" means a password exists; null means no password.'
          type: string
          example: '**********'
          maxLength: 255
        created_at:
          description: 'Creation date'
          type: string
          format: date-time
        updated_at:
          description: 'Modification date'
          type: string
          format: date-time
        delete_at:
          description: 'Scheduled deletion date'
          type: string
          format: date-time
        expired_at:
          description: 'Scheduled expiration date'
          type: string
          format: date-time
        expired_url:
          description: 'The URL to which users will be redirected after the link has expired'
          type: string
          format: url
        expired_title:
          description: 'The title displayed on the expiration page'
          type: string
        expired_text:
          description: 'The text displayed on the expiration page'
          type: string
        delete_after_expiration:
          description: 'Whether the link should be deleted once it has expired'
          type: boolean
          default: false
        tags:
          description: Tags
          type: array
          items:
            properties:
              id:
                description: ID
                type: string
                format: uuid
              name:
                description: Name
                type: string
            type: object
          maxItems: 3
        qrcode:
          description: 'QR Code associated to the short link'
          properties:
            data:
              description: 'QR Code Data URL'
              type: string
          type: object
        utm:
          description: 'UTM parameters'
          properties:
            campaign:
              description: utm_campaign
              type: string
              maxLength: 255
            medium:
              description: utm_medium
              type: string
              maxLength: 255
            source:
              description: utm_source
              type: string
              maxLength: 255
            content:
              description: utm_content
              type: string
              maxLength: 255
          type: object
        metatag:
          description: 'Custom metadata for social previews'
          properties:
            title:
              description: 'Title of the link'
              type: string
              maxLength: 255
            description:
              description: 'Description of the link'
              type: string
              maxLength: 255
            image:
              description: 'Image URL of the link'
              type: string
              format: url
          type: object
        geolinks:
          description: 'Dynamic routing conditions'
          type: array
          items:
            properties:
              conditions:
                description: 'Conditions for dynamic routing'
                type: array
                items:
                  properties: { type: { description: 'Type of the condition ', type: string, enum: [country, language, system] }, value: { description: 'Value for the given type. Allowed values depend on "type": e.g., "US", "DE", "FR" for type "country"; "en", "fr", "de" for type "language"; "Android", "iOS" for type "system".', type: string }, operator: { description: 'Operator to apply for the condition', type: string, enum: [AND, OR] } }
                  type: object
              url:
                description: 'URL to redirect to when conditions match'
                type: string
                format: url
            type: object
      type: object
    LinkBaseRequest:
      properties:
        url:
          description: 'URL to shorten'
          type: string
          maxLength: 4096
        folder_id:
          description: 'Folder API ID'
          type: string
          format: uuid
        domain:
          description: Domain
          type: string
          format: hostname
          example: mybrand.com
        code:
          description: 'Custom short code'
          type: string
          pattern: '^[\p{L}0-9_\-/]{2,50}$'
          example: xxxxx
          maxLength: 50
          minLength: 2
        label:
          description: Label
          type: string
          maxLength: 255
        password:
          description: Password
          type: string
          maxLength: 255
        delete_at:
          description: 'Scheduled deletion date'
          type: string
          format: date-time
        expired_at:
          description: 'Scheduled expiration date'
          type: string
          format: date-time
        expired_url:
          description: 'The URL to which users will be redirected after the link has expired'
          type: string
          format: url
        expired_title:
          description: 'The title displayed on the expiration page'
          type: string
        expired_text:
          description: 'The text displayed on the expiration page'
          type: string
        delete_after_expiration:
          description: 'Whether the link should be deleted once it has expired'
          type: boolean
          default: false
        tags:
          description: Tags
          type: array
          items:
            type: string
            format: uuid
          maxItems: 3
        qrcode:
          description: 'QR Code'
          properties:
            size:
              description: 'The size of the QR code (px)'
              type: integer
              default: 600
              maximum: 1000
              minimum: 100
            format:
              description: 'The format of the QR code'
              type: string
              default: png
              enum:
                - png
                - webp
                - svg
            margin:
              description: 'The margin around the QR code (px)'
              type: integer
              default: 0
            background_color:
              description: 'The background color of the QR code (hexadecimal)'
              type: string
              default: '#ffffff'
            foreground_color:
              description: 'The foreground color of the QR code (hexadecimal)'
              type: string
              default: '#000000'
          type: object
        utm:
          description: 'UTM parameters'
          properties:
            campaign:
              description: utm_campaign
              type: string
              maxLength: 255
            medium:
              description: utm_medium
              type: string
              maxLength: 255
            source:
              description: utm_source
              type: string
              maxLength: 255
            content:
              description: utm_content
              type: string
              maxLength: 255
          type: object
        metatag:
          description: 'Custom metadata for social previews'
          properties:
            title:
              description: 'Title for the link'
              type: string
              maxLength: 255
            description:
              description: 'Description for the link'
              type: string
              maxLength: 255
            image:
              description: 'Image URL for the link. Recommended: 1200X630px<br>Maximum size: 3Mb - Formats: PNG, JPEG, WebP and GIF.'
              type: string
              format: url
          type: object
        geolinks:
          description: 'Dynamic routing conditions'
          type: array
          items:
            properties:
              conditions:
                description: 'Conditions for dynamic routing'
                type: array
                items:
                  properties: { type: { description: 'Type of the condition ', type: string, enum: [country, language, system] }, value: { description: 'Value for the given type. Allowed values depend on "type": e.g., "US", "DE", "FR" for type "country"; "en", "fr", "de" for type "language"; "Android", "iOS" for type "system".', type: string }, operator: { description: 'Operator to apply for the condition', type: string, enum: [AND, OR] } }
                  type: object
              url:
                description: 'URL to redirect to when conditions match'
                type: string
                format: url
            type: object
      type: object
    LinkCreateRequest:
      allOf:
        -
          required:
            - url
            - workspace_id
          properties:
            workspace_id:
              description: 'Workspace API ID'
              type: string
              format: uuid
          type: object
        -
          $ref: '#/components/schemas/LinkBaseRequest'
    LinkEditRequest:
      allOf:
        -
          $ref: '#/components/schemas/LinkBaseRequest'
    Workspace:
      properties:
        id:
          description: 'Workspace API ID'
          type: string
          format: uuid
        name:
          description: 'Workspace name'
          type: string
          example: 'the best team'
        created_at:
          description: 'Creation date'
          type: string
          format: date-time
        updated_at:
          description: 'Modification date'
          type: string
          format: date-time
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-KEY
      in: header
tags:
  -
    name: Links
  -
    name: 'QR Codes'
  -
    name: Statistics
  -
    name: Workspaces
  -
    name: Folders
  -
    name: Domains
