> ## Documentation Index > Fetch the complete documentation index at: https://docs.kodelabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Add device references > Links the device in the path to one or more other devices in the same building. The device in the path is the referrer. `relationship` describes the link: its `key`, whether it accepts several devices (`multi`), and its direction (`type`). Take the three values from [List connections for a canonical type](https://docs.kodelabs.com/products/kode-api/api-reference/ontology/list-connections-for-a-canonical-type.md), which returns each connection a device can have in exactly this shape. The link is stored on both devices. Each linked device holds the reverse link, with the opposite `type`. Both devices need an ontology applied, and the connection must be valid for them. The request is refused with `400` when: * A device would reference itself. * A listed device is already linked to the device in the path. * The link would create a loop, directly or through other devices, or reverse a link that already exists. * A device has no ontology. A successful request returns `204` with an empty body. Read the links back with [List device references](https://docs.kodelabs.com/products/kode-api/api-reference/devices/list-device-references.md) to confirm they were stored. ## OpenAPI ````yaml /openapi/kode-api.yaml post /api/v1/buildings/{buildingId}/devices/{deviceId}/references openapi: 3.1.0 info: title: KODE API version: 1.0.0 summary: Programmatic access to KODE OS resources and operations. description: > Use the KODE API to work with buildings, data sources, connectors, devices, points, virtual devices, timeseries data, schedules, the ontology, templating, mass writes, spaces, space assignments, tenants, meters, users, actions, and AssetOps work orders. license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.kodelabs.com/kodeos description: KODE API security: - bearerAuth: [] tags: - name: Authentication description: OAuth 2.0 discovery, token, and revocation endpoints. - name: Buildings description: Buildings and their areas. - name: Data sources description: Data sources connected to a building. - name: Devices description: Devices and their points. - name: Points description: Point queries and point writes. - name: Timeseries description: Current and historical point values. - name: Actions description: Actions exposed by building data sources. - name: Work orders description: AssetOps work orders, lookups, comments, and attachments. - name: Connectors description: KODE API connectors and the devices and points ingested through them. - name: Schedules description: Schedules discovered on building data sources. - name: Templating description: Apply ontology templates to groups of points. - name: Virtual devices description: Virtual devices that group points from other devices. - name: Ontology description: Canonical types, fields, units, and connections of the KODE ontology. - name: Users description: Users of the organization and their app access. - name: Mass write description: Write values to many points across buildings, and follow each run. - name: Spaces description: Levels and space units of a building, and the meters located in them. - name: Space assignments description: Assign tenants to leasable spaces of a building for a period. - name: Tenants description: Tenants of a building, the people or companies that lease its spaces. - name: Meters description: >- Meters of a building, their space assignments, parent and child links, and readings. paths: /api/v1/buildings/{buildingId}/devices/{deviceId}/references: post: tags: - Devices summary: Add device references description: >- Links the device in the path to one or more other devices in the same building. operationId: addDeviceReferences parameters: - $ref: '#/components/parameters/BuildingId' - $ref: '#/components/parameters/DeviceId' requestBody: content: application/json: schema: $ref: '#/components/schemas/AddDeviceReferences' required: true responses: '204': description: The links were added. The body is empty. '400': description: >- The body is not valid, or a rule above refused it. For example `relationship` is missing or malformed, `referencedDeviceIds` is empty, a device would reference itself, a device is already linked, the link would create a loop or reverse an existing link, or a device has no ontology. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: BuildingId: name: buildingId in: path required: true description: Building identifier from List buildings. schema: type: string example: 67c960faffaa42223163099e DeviceId: name: deviceId in: path required: true description: Device identifier. schema: type: string example: ahu-01 schemas: AddDeviceReferences: type: object required: - relationship - referencedDeviceIds properties: relationship: $ref: '#/components/schemas/Relationship' referencedDeviceIds: type: array items: type: string minItems: 1 Relationship: type: object required: - key - multi - type properties: key: type: string multi: type: boolean type: $ref: '#/components/schemas/RefType1' RefType1: type: string enum: - INPUT - OUTPUT responses: Unauthorized: description: The access token is missing, invalid, or expired. Request a new token. Forbidden: description: The service account lacks permission for this building or operation. TooManyRequests: description: >- A rate-limit window is exhausted. Wait, then retry with increasing delays. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Paste an access token from [Create an access token](/products/kode-api/api-reference/authentication/create-an-access-token). Tokens expire, so request a new one if you receive `401`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.