# Create or replace a twin relationship

Only one relationship between twin T1 and twin T2 with the same name and properties can be present -- if the given relationship already exists, the operation is idempotent.
Id of the relationship will be derived by the system and will override the value present in the request.

Endpoint: PUT /twins/relationships
Version: v3
Security: oauth2

## Request fields (application/json):

  - `id` (string)
    The unique Id of the relationship entity.

  - `targetId` (string, required)
    The Id of the target twin.
    Example: "Chiller-1"

  - `sourceId` (string, required)
    The Id of the source twin.
    Example: "AHU-1"

  - `name` (string, required)
    The name of the relationship, which defines the type of link from source twin to target twin (e.g. isPartOf, locatedIn, servedBy, etc.. ).
    Example: "isFedBy"

  - `properties` (object)
    Additional properties of the relationship as defined in the DTDL model.
    Example: {"substance":"ChilledWater"}

## Response 200 fields (application/json):

  - `id` (string)
    The unique Id of the relationship entity.

  - `targetId` (string, required)
    The Id of the target twin.
    Example: "Chiller-1"

  - `sourceId` (string, required)
    The Id of the source twin.
    Example: "AHU-1"

  - `name` (string, required)
    The name of the relationship, which defines the type of link from source twin to target twin (e.g. isPartOf, locatedIn, servedBy, etc.. ).
    Example: "isFedBy"

  - `properties` (object)
    Additional properties of the relationship as defined in the DTDL model.
    Example: {"substance":"ChilledWater"}