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

# Add a link visit



## OpenAPI

````yaml post /public/addlinkvisit
openapi: 3.1.0
info:
  title: Joylink API
  version: 1.0.0
  description: API for managing Joylink short links and tracking
servers:
  - url: https://api.joylink.io
    description: Production server
security: []
paths:
  /public/addlinkvisit:
    post:
      summary: Add a link visit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                link_key:
                  type: string
                  description: The link key to track
                os:
                  type: string
                  description: Operating system
                city:
                  type: string
                  description: City name
                device:
                  type: string
                  description: Device type
                region:
                  type: string
                  description: Region
                browser:
                  type: string
                  description: Browser name
                country:
                  type: string
                  description: Country name
                referrer:
                  type: string
                  description: Referrer
                referrerURL:
                  type: string
                  description: Referrer URL
                country_code:
                  type: string
                  description: Country code
                user_agent:
                  type: string
                  description: User agent string
                ip_address:
                  type: string
                  description: IP address
                link_not_found_behavior:
                  type: object
                  properties:
                    create_link:
                      type: boolean
                      description: Whether to create link if not found
                    create_link_input:
                      $ref: '#/components/schemas/CreateLinkInput'
              required:
                - link_key
      responses:
        '200':
          description: Successfully recorded link visit
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  link:
                    $ref: '#/components/schemas/Link'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Link not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateLinkInput:
      type: object
      properties:
        destination:
          type: string
          description: The URL to be shortened
        trackingid:
          type: string
          description: Optional tracking ID
      required:
        - destination
    Link:
      type: object
      properties:
        key:
          type: string
          description: Unique identifier for the link
        description:
          type: string
          description: Description of the link
        destination:
          type: string
          description: The target URL
        imageUrl:
          type: string
          description: URL of the product image
        productTitle:
          type: string
          description: Title of the product
        userId:
          type: string
          description: ID of the user who created the link
        linkPrefix:
          type: string
          description: Custom link prefix for the user
        createdAt:
          type: string
          description: Timestamp of when the link was created
    Error:
      type: object
      properties:
        error:
          type: string
        details:
          type: string
  responses:
    RateLimitExceeded:
      description: >-
        Rate limit exceeded. Public API keys are limited to 60 requests per
        minute and 1440 requests per day, shared across endpoints.
      headers:
        X-RateLimit-Limit-Minute:
          description: Maximum requests allowed per minute.
          schema:
            type: integer
            example: 60
        X-RateLimit-Remaining-Minute:
          description: Requests remaining in the current minute window.
          schema:
            type: integer
            example: 0
        X-RateLimit-Reset-Minute:
          description: Seconds until the minute window resets.
          schema:
            type: integer
            example: 45
        X-RateLimit-Limit-Day:
          description: Maximum requests allowed per day.
          schema:
            type: integer
            example: 1440
        X-RateLimit-Remaining-Day:
          description: Requests remaining in the current day window.
          schema:
            type: integer
            example: 1200
        X-RateLimit-Reset-Day:
          description: Seconds until the day window resets.
          schema:
            type: integer
            example: 43200
        Retry-After:
          description: >-
            Seconds to wait before retrying. Matches the limit you hit (minute
            or day).
          schema:
            type: integer
            example: 45
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            minute_limit:
              summary: Per-minute limit exceeded
              value:
                error: >-
                  Rate limit exceeded. Maximum 60 requests per minute. Resets in
                  45s.
            day_limit:
              summary: Per-day limit exceeded
              value:
                error: >-
                  Rate limit exceeded. Maximum 1440 requests per day. Resets in
                  5h 20m.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````