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

# Add a new link

> Create a new link between two dataset columns.



## OpenAPI

````yaml /api-reference/openapi.yml post /links/add
openapi: 3.0.3
info:
  title: DataLinks
  version: 2.2.3
servers:
  - url: https://api.datalinks.com/api/v1
    description: production server
security:
  - bearerAuth: []
  - openId:
      - implicit
paths:
  /links/add:
    post:
      tags:
        - links
      summary: Add a new link
      description: Create a new link between two dataset columns.
      operationId: addLink
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddLinkRequest'
            examples:
              exactMatch:
                summary: Exact match between movie datasets
                value:
                  from:
                    username: johndoe
                    namespace: cinematography
                    dataset: movies
                    columnName: director
                  to:
                    username: janedoe
                    namespace: entertainment
                    dataset: films
                    columnName: director_name
                  matchType: ExactMatch
              geoMatch:
                summary: Geographic match between location datasets
                value:
                  from:
                    username: alice
                    namespace: geography
                    dataset: cities
                    columnName: coordinates
                  to:
                    username: bob
                    namespace: mapping
                    dataset: locations
                    columnName: gps_coords
                  matchType: GeoMatch
        required: true
      responses:
        '200':
          description: Link existed, no creation required.
        '201':
          description: Creates a new link.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The source or target dataset was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    AddLinkRequest:
      required:
        - from
        - matchType
        - to
      type: object
      properties:
        from:
          $ref: '#/components/schemas/ApiStringColumnIdentifier'
        to:
          $ref: '#/components/schemas/ApiStringColumnIdentifier'
        options:
          description: Flexible options map for match configuration.
          oneOf:
            - $ref: '#/components/schemas/ExactMatchConfig'
            - $ref: '#/components/schemas/GeoMatchConfig'
        matchType:
          type: string
          description: Type of match to create between the columns.
          example: ExactMatch
          enum:
            - ExactMatch
            - GeoMatch
    ErrorResponse:
      required:
        - error_code
        - message
      type: object
      properties:
        error_code:
          type: string
          example: UNAUTHORIZED
        error_message:
          type: string
          example: ''
        message:
          type: string
          example: Missing authentication token
        sub_errors:
          type: array
          items:
            required:
              - code
              - message
            type: object
            properties:
              code:
                type: string
              message:
                type: string
    ApiStringColumnIdentifier:
      required:
        - columnName
        - dataset
        - namespace
        - username
      type: object
      properties:
        username:
          type: string
          description: Username of the dataset owner.
          example: johndoe
        namespace:
          type: string
          description: Namespace of the dataset.
          example: cinematography
        dataset:
          type: string
          description: Name of the dataset.
          example: movies
        columnName:
          type: string
          description: Column name in the dataset.
          example: director
      example:
        - username: username
        - namespace: namespace
        - dataset: dataset
        - columnName: columnName
    ExactMatchConfig:
      type: object
      properties:
        minDistinct:
          type: number
        minVariation:
          type: number
      nullable: true
    GeoMatchConfig:
      type: object
      properties:
        distance:
          type: number
        distanceUnit:
          type: string
      nullable: true
  responses:
    BadRequest:
      description: Bad request. The request was malformed or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: >-
        Unauthorized. This error occurs if the authentication token is missing
        or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden. The user does not have access to this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      description: >
        Use a Bearer token for authentication. Submit the token using the
        `Authorization`

        header: `Authorization: Bearer <token>`.
      scheme: bearer
    openId:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: >-
            https://login.datalinks.com/realms/datalinks-realm/protocol/openid-connect/auth
          scopes:
            openid: openid

````