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

# Create Relationship Record between Entities

Use this API to create a new Relationship Record between entities.

> 🗒 Things to Know
> 
> - This API only supports AI Governance entities (Models, Datasets, AI Systems, and AI Agents).
> - AI Governance APIs will become available over the course of the Spring as customer tenants are upgraded to enhanced AI Governance services. No customer action is required and more detailed information will be published in upcoming release notes and product documentation. 

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "AI Governance - AI Governance",
    "version": "1.0",
    "contact": {
      "name": "OneTrust Support",
      "url": "https://my.onetrust.com/s/contactsupport"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0"
    },
    "description": "The AI Governance APIs are used to integrate external systems and streamline the flow of data with AI Governance in the OneTrust Platform."
  },
  "servers": [
    {
      "url": "https://{hostname}",
      "variables": {
        "hostname": {
          "default": "hostname",
          "description": "The OneTrust hostname such as app.onetrust.com, app-eu.onetrust.com, app-de.onetrust.com, app-uk.onetrust.com, app-apac.onetrust.com, trial.onetrust.com, or uat.onetrust.com."
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Relationship Management",
      "description": "The Relationship Management APIs are used to manage relationships between AI Governance entities.",
      "externalDocs": {
        "description": "OpenAPI 3.1.0 - Download Definition",
        "url": "https://developer.onetrust.com/onetrust/openapi/ai-governance.json"
      }
    }
  ],
  "x-onetrust": {
    "spec-label": "OpenAPI 3.1.0"
  },
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false,
    "metrics-enabled": false
  },
  "paths": {
    "/api/ai-governance/v1/links": {
      "post": {
        "operationId": "createLinkRecordBetweenEntitiesUsingLinkTypeIdUsingPOST",
        "summary": "Create Relationship Record between Entities",
        "description": "Use this API to create a new Relationship Record between entities.\n\n> 🗒 Things to Know\n> \n> - This API only supports AI Governance entities (Models, Datasets, AI Systems, and AI Agents).\n> - AI Governance APIs will become available over the course of the Spring as customer tenants are upgraded to enhanced AI Governance services. No customer action is required and more detailed information will be published in upcoming release notes and product documentation. ",
        "tags": [
          "Relationship Management"
        ],
        "x-onetrust": {
          "spec-label": "https://developer.onetrust.com/onetrust/openapi/ai-governance.json"
        },
        "parameters": [
          {
            "name": "linkTypeId",
            "in": "query",
            "description": "Unique identifier of the link type to use for creating the relationship",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "2aa71ead-0c9a-416a-8471-bdfb67c8d113"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LinkRequest"
              },
              "examples": {
                "Create Model - AISystem Relationship": {
                  "summary": "Example of creating a relationship between a model and AISystem",
                  "description": "Create Model - AISystem Relationship",
                  "value": {
                    "entity2": {
                      "id": "296c0a2d-b5f6-450d-8b13-3c2327775042",
                      "entityType": {
                        "name": "models"
                      }
                    },
                    "entity1": {
                      "id": "0f79003f-b177-4f02-aa83-9bf11deec7c7",
                      "entityType": {
                        "name": "aisystems"
                      }
                    },
                    "attributes": null,
                    "context": null
                  }
                },
                "Create model-vendor Relationship": {
                  "summary": "Example of creating a is source from relationship between a model and a vendor",
                  "description": "Create model-vendor Relationship",
                  "value": {
                    "entity1": {
                      "id": "b4c4991c-ab14-4bb2-abae-dad255a513c3",
                      "entityType": {
                        "name": "models"
                      }
                    },
                    "entity2": {
                      "id": "690c2d22-d864-4ec7-92ad-850c678a1cd3",
                      "entityType": {
                        "name": "vendors"
                      }
                    },
                    "attributes": null,
                    "context": null
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created - The relationship was successfully established",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LinkInformation"
                },
                "examples": {
                  "Model - AISystem Relationship": {
                    "summary": "Example of created relationship information",
                    "description": "Model - AISystem Relationship",
                    "value": {
                      "id": "c0f18be7-1205-4417-874c-e5b8d292ac9f",
                      "linkType": {
                        "id": "8857005c-662f-4f90-9e4e-481b225a666a",
                        "name": "ai-system-composition",
                        "nameKey": "CE.Link.AISystemComposition.Name",
                        "idOrNamePresent": true
                      },
                      "linkTypeLabel": {
                        "id": 5,
                        "entityType1ToEntityType2EntityLinkName": "is composed of",
                        "entityType1ToEntityType2EntityLinkNameKey": "CE.Link.AISystemComposition.ForwardLabel",
                        "entityType2ToEntityType1EntityLinkName": "is a component of",
                        "entityType2ToEntityType1EntityLinkNameKey": "CE.Link.AISystemComposition.BackwardLabel"
                      },
                      "entity1": {
                        "linkEntityDetail": null,
                        "id": "0f79003f-b177-4f02-aa83-9bf11deec7c7",
                        "number": null,
                        "name": "AISystem 1",
                        "entityType": {
                          "id": "8a0b318a-d206-4ff9-b1db-00c8c8611d37",
                          "name": "aisystems",
                          "nameKey": "CE.AISystems.Name",
                          "seeded": true,
                          "moduleName": "AIGovernance",
                          "schemaName": "aisystems"
                        },
                        "deleted": false
                      },
                      "entity2": {
                        "linkEntityDetail": null,
                        "id": "296c0a2d-b5f6-450d-8b13-3c2327775042",
                        "number": null,
                        "name": "Model Test",
                        "entityType": {
                          "id": "963bbab3-8bc9-4787-9ebb-a502775bef54",
                          "name": "models",
                          "nameKey": "CE.Models.Name",
                          "seeded": true,
                          "moduleName": "AIGovernance",
                          "schemaName": "models"
                        },
                        "deleted": false
                      },
                      "schemaId": "f48f80ee-78b6-4dbe-adb4-9872b69b804b",
                      "entityLinkDetail": null,
                      "auditFields": {
                        "createdDate": "2026-02-10T13:10:23.267Z",
                        "lastUpdatedDate": "2026-02-10T13:10:23.267Z",
                        "createdBy": {
                          "id": "d59129eb-7fa7-45b9-a1fb-b29a7f3b13cd",
                          "name": null,
                          "email": null,
                          "initials": null
                        },
                        "lastModifiedBy": {
                          "id": "d59129eb-7fa7-45b9-a1fb-b29a7f3b13cd",
                          "name": null,
                          "email": null,
                          "initials": null
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "429": {
            "description": "Too Many Requests. \nFor more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview).",
            "headers": {
              "Retry-After": {
                "schema": {
                  "description": "The number of seconds after which requests will be allowed again.",
                  "format": "int32"
                }
              },
              "ot-period": {
                "schema": {
                  "description": "The unit of time for which the rate limit applies",
                  "enum": [
                    "HOUR",
                    "MINUTE"
                  ]
                }
              },
              "ot-ratelimit-event-id": {
                "schema": {
                  "description": "The unique identifier for the rate-limiting event.",
                  "format": "uuid"
                }
              },
              "ot-request-made": {
                "schema": {
                  "description": "The number of requests made within the specified period.",
                  "format": "int32"
                }
              },
              "ot-requests-allowed": {
                "schema": {
                  "description": "The number of requests allowed within the specified period.",
                  "format": "int32"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "OAUTH2": [
              "AI_GOVERNANCE",
              "AI_GOVERNANCE_WRITE"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "AssociatedAttributeValueInformation": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Unique identifier for the attribute option",
            "type": "string",
            "format": "uuid",
            "example": "a34ccec7-1ec0-4d65-9075-bdd0d923f1d1"
          },
          "value": {
            "description": "Attribute value",
            "type": "string",
            "example": "Text Value"
          },
          "valueKey": {
            "description": "Translation key used for localizing the value",
            "type": "string",
            "example": "attribute.option.valueKey"
          },
          "colorCode": {
            "description": "Color code associated with the option. Used for score-based attributes.",
            "type": "string",
            "example": "red"
          }
        },
        "required": [
          "value"
        ]
      },
      "AttributeValueInformation": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Unique identifier for the attribute option",
            "type": "string",
            "format": "uuid",
            "example": "a34ccec7-1ec0-4d65-9075-bdd0d923f1d1"
          },
          "value": {
            "description": "Attribute value",
            "type": "string",
            "example": "Text Value"
          },
          "valueKey": {
            "description": "Translation key used for localizing the value",
            "type": "string",
            "example": "attribute.option.valueKey"
          },
          "colorCode": {
            "description": "Color code associated with the option. Used for score-based attributes.",
            "type": "string",
            "example": "red"
          },
          "optionSelectionValue": {
            "description": "Selection score value linked to the option. Used for score-based or numerical-based attributes.",
            "type": "string",
            "example": "3.5"
          },
          "displayLabel": {
            "description": "Display name for the option, used for external attributes managed by other systems",
            "type": "string",
            "example": "United State | San Francisco"
          },
          "associatedAttributeValueInformation": {
            "description": "Associated attribute option information",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AssociatedAttributeValueInformation"
            }
          },
          "disabled": {
            "description": "Indicates whether this attribute option is currently disabled.",
            "type": "boolean",
            "example": false,
            "default": "false"
          }
        },
        "required": [
          "value"
        ]
      },
      "BasicEntityTypeInformation": {
        "type": "object",
        "properties": {
          "id": {
            "description": "The unique identifier for the entity type.",
            "type": "string",
            "format": "uuid",
            "example": "f2229953-b4b5-4042-8cb9-b78038cc4c46"
          },
          "name": {
            "description": "The name of the entity type.",
            "type": "string",
            "example": "Vendor"
          },
          "seeded": {
            "description": "This parameter indicates whether the entity type is seeded or custom.",
            "type": "boolean",
            "example": true
          },
          "moduleName": {
            "description": "The name of the module where the entity exists.",
            "type": "string",
            "example": "Vendor",
            "enum": [
              "Vendor",
              "DataMapping",
              "Risk",
              "Assessments",
              "CustomEntityManagement"
            ]
          },
          "schemaName": {
            "description": "The name of the schema.",
            "type": "string",
            "example": "vendor",
            "enum": [
              "vendor",
              "projects",
              "models",
              "datasets",
              "aisystems"
            ]
          }
        },
        "example": "{\n \"id\": \"f2229953-b4b5-4042-8cb9-b78038cc4c46\",\n \"name\": \"Vendor\",\n \"nameKey\": \"EntityType.Vendor.Name\",\n \"seeded\": true,\n \"moduleName\": \"Vendor\",\n \"schemaName\": \"vendor\"\n},\n",
        "required": [
          "id",
          "name"
        ]
      },
      "EntityDetailRequest": {
        "type": "object",
        "properties": {
          "extendedBaseAttributes": {
            "description": "Base Seeded Attributes",
            "type": "object",
            "example": {
              "textAttributeName": [
                {
                  "value": "Text"
                }
              ],
              "optionBasedAttributeName": [
                {
                  "id": "f2229953-b4b5-4042-8cb9-b78038cc4c46"
                }
              ]
            },
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/AttributeValueInformation"
              }
            }
          }
        }
      },
      "LinkRequest": {
        "type": "object",
        "properties": {
          "attributes": {
            "description": "Custom Attributes based on schema defined for given link type",
            "type": "object",
            "example": {
              "textAttributeName": [
                {
                  "value": "Text"
                }
              ],
              "optionBasedAttributeName": [
                {
                  "id": "f2229953-b4b5-4042-8cb9-b78038cc4c46"
                }
              ]
            },
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/AttributeValueInformation"
              }
            }
          },
          "entity1": {
            "description": "Associated Entity Instance for given Entity Type",
            "example": {
              "id": "f2229953-b4b5-4042-8cb9-b78038cc4c46",
              "entityType": {
                "id": "d1119953-b4b5-4042-8cb9-b78038cc4c46",
                "name": "Vendor"
              }
            },
            "$ref": "#/components/schemas/LinkedEntityInformation"
          },
          "entity2": {
            "description": "Associated Entity Instance for given Entity Type",
            "example": {
              "id": "a2129953-b4b5-4042-8cb9-b78038cc4c46",
              "entityType": {
                "id": "d1119953-b4b5-4042-8cb9-b78038cc4c46",
                "name": "Vendor"
              }
            },
            "$ref": "#/components/schemas/LinkedEntityInformation"
          }
        },
        "required": [
          "entity1",
          "entity2"
        ]
      },
      "LinkedEntityInformation": {
        "type": "object",
        "properties": {
          "linkEntityDetail": {
            "description": "Link entity details extended base properties",
            "example": {
              "includeCustomFields": true,
              "includeStandardFields": true
            },
            "$ref": "#/components/schemas/EntityDetailRequest"
          },
          "id": {
            "description": "Unique identifier of the entity",
            "type": "string",
            "format": "uuid",
            "example": "f2229953-b4b5-4042-8cb9-b78038cc4c46"
          },
          "number": {
            "description": "Auto-generated sequential entity number",
            "type": "integer",
            "format": "int64",
            "example": 1024,
            "maximum": 9999999,
            "minimum": 1,
            "readOnly": true
          },
          "name": {
            "description": "Name of the entity",
            "type": "string",
            "example": "OneTrust DataGuidance",
            "maxLength": 255,
            "minLength": 1
          },
          "detailsAccessRestricted": {
            "description": "Flag indicating whether entity is view-only",
            "type": "boolean",
            "example": false
          },
          "redirectURL": {
            "description": "Redirect URL for the entity",
            "type": "string",
            "example": "/entity/product/f2229953-b4b5-4042-8cb9-b78038cc4c46"
          },
          "entityType": {
            "description": "Basic information about the entity type",
            "example": {
              "id": "d1119953-b4b5-4042-8cb9-b78038cc4c46",
              "name": "Product",
              "displayName": "Product",
              "nameKey": "entity.type.product",
              "displayNameKey": "entity.type.product.display",
              "module": "VENDOR"
            },
            "$ref": "#/components/schemas/BasicEntityTypeInformation"
          },
          "deleted": {
            "type": "boolean"
          }
        },
        "example": {
          "id": "f2229953-b4b5-4042-8cb9-b78038cc4c46",
          "number": 1024,
          "name": "OneTrust DataGuidance",
          "isDeleted": false,
          "detailsAccessRestricted": false,
          "redirectURL": "/entity/product/f2229953-b4b5-4042-8cb9-b78038cc4c46",
          "entityType": {
            "id": "d1119953-b4b5-4042-8cb9-b78038cc4c46",
            "name": "Product",
            "displayName": "Product",
            "nameKey": "entity.type.product",
            "displayNameKey": "entity.type.product.display",
            "module": "VENDOR"
          },
          "linkEntityDetail": {
            "includeCustomFields": true,
            "includeStandardFields": true
          }
        },
        "required": [
          "entityType",
          "id",
          "number"
        ],
        "title": "Linked Entity Information"
      },
      "BasicLinkTypeLabelInformation": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Pk of an Link Type Object Type Pair",
            "type": "integer",
            "format": "int64",
            "example": 1
          },
          "entityType1ToEntityType2EntityLinkName": {
            "description": "Link type name from EntityType1-EntityType2",
            "type": "string",
            "example": "OneTrust provides GRC"
          },
          "entityType2ToEntityType1EntityLinkName": {
            "description": "Link type name from EntityType2-EntityType1",
            "type": "string",
            "example": "GRC belongs to OneTrust"
          }
        },
        "required": [
          "id"
        ]
      },
      "EntityBasicUserInformation": {
        "type": "object",
        "properties": {
          "id": {
            "description": "The unique identifier of the user.",
            "type": "string",
            "format": "uuid",
            "example": "f2229953-b4b5-4042-8cb9-b78038cc4c46"
          },
          "name": {
            "description": "The full name of the user.",
            "type": "string",
            "example": "First Last"
          },
          "email": {
            "description": "The email address of the user.",
            "type": "string",
            "example": "user@gmail.com"
          },
          "initials": {
            "description": "The initials for the first and last name of the user.",
            "type": "string",
            "example": "FL"
          }
        }
      },
      "EntityRecordAuditInformation": {
        "type": "object",
        "properties": {
          "createdDate": {
            "description": "The date and time that the entity was last created.",
            "type": "string",
            "format": "date-time",
            "example": "2021-05-13T13:06:49.853Z"
          },
          "lastUpdatedDate": {
            "description": "The date and time that the entity was last updated.",
            "type": "string",
            "format": "date-time",
            "example": "2021-05-13T13:06:49.853Z"
          },
          "createdBy": {
            "description": "The information of the user who last created/modified the entity.",
            "example": {
              "id": "c21319953-b4b5-4042-8cb9-b78038cc4c51",
              "name": "Name"
            },
            "$ref": "#/components/schemas/EntityBasicUserInformation"
          },
          "lastModifiedBy": {
            "description": "The information of the user who last created/modified the entity.",
            "example": {
              "id": "c21319953-b4b5-4042-8cb9-b78038cc4c51",
              "name": "Name"
            },
            "$ref": "#/components/schemas/EntityBasicUserInformation"
          }
        },
        "required": [
          "createdDate"
        ]
      },
      "IdOrNameLinkType": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Unique Identifier of an Link Type",
            "type": "string",
            "format": "uuid",
            "example": "f2229953-b4b5-4042-8cb9-b78038cc4c46"
          },
          "name": {
            "description": "Name of an Link Type",
            "type": "string",
            "example": "Product/Service"
          },
          "idOrNamePresent": {
            "type": "boolean"
          }
        }
      },
      "LinkInformation": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Unique identifier of the link record. Auto-generated when a new link is created.",
            "type": "string",
            "format": "uuid",
            "example": "d1119953-b4b5-4042-8cb9-b78038cc4c46",
            "readOnly": true
          },
          "linkType": {
            "description": "Link type information defining the type of relationship. Can be specified by ID or name.",
            "example": {
              "name": "Related"
            },
            "$ref": "#/components/schemas/IdOrNameLinkType"
          },
          "linkTypeLabel": {
            "description": "Link type label information showing the directional relationship names between the two entities.",
            "example": {
              "entityType1ToEntityType2EntityLinkName": "Send Data To",
              "entityType2ToEntityType1EntityLinkName": "Receive Data From"
            },
            "$ref": "#/components/schemas/BasicLinkTypeLabelInformation"
          },
          "entity1": {
            "description": "Source entity information for this relationship. Contains entity identifier and type details.",
            "example": {
              "id": "f2229953-b4b5-4042-8cb9-b78038cc4c46",
              "entityType": {
                "id": "d1119953-b4b5-4042-8cb9-b78038cc4c46",
                "name": "Vendor"
              }
            },
            "$ref": "#/components/schemas/LinkedEntityInformation"
          },
          "entity2": {
            "description": "Target entity information for this relationship. Contains entity identifier and type details.",
            "example": {
              "id": "a2129953-b4b5-4042-8cb9-b78038cc4c46",
              "entityType": {
                "id": "d1119953-b4b5-4042-8cb9-b78038cc4c46",
                "name": "Vendor"
              }
            },
            "$ref": "#/components/schemas/LinkedEntityInformation"
          },
          "schemaId": {
            "description": "Unique identifier of the schema used for this link type.",
            "type": "string",
            "format": "uuid",
            "example": "d1119953-b4b5-4042-8cb9-b78038cc4c46",
            "readOnly": true
          },
          "auditFields": {
            "description": "Audit information for the link including creation and modification details. Contains information about when the link was created/modified and by whom.",
            "example": {
              "createdBy": "admin@example.com",
              "createdTimestamp": "2023-01-15T10:30:45Z",
              "lastModifiedBy": "system@example.com",
              "lastModifiedTimestamp": "2025-03-22T14:15:22Z"
            },
            "$ref": "#/components/schemas/EntityRecordAuditInformation",
            "readOnly": true
          }
        },
        "example": {
          "id": "d1119953-b4b5-4042-8cb9-b78038cc4c46",
          "linkType": {
            "name": "Related"
          }
        },
        "required": [
          "entity1",
          "entity2",
          "id",
          "linkType"
        ],
        "title": "Link Information"
      }
    },
    "securitySchemes": {
      "OAUTH2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://{hostname}/api/access/v1/oauth/token",
            "scopes": {
              "AI_GOVERNANCE": "Grants full permissions to manage AI Governance operations for external systems",
              "AI_GOVERNANCE_READ": "Allows read-only access to AI Governance entities",
              "AI_GOVERNANCE_WRITE": "Grants permissions to create and modify AI Governance entities"
            }
          }
        }
      }
    }
  }
}
```