---
title: "Create a knowledge graph external reference"
method: POST
path: "/knowledgeGraph/nodes/{node_id}/externalRefs"
tags: ["KnowledgeGraph"]
---

# Create a knowledge graph external reference

`POST /knowledgeGraph/nodes/{node_id}/externalRefs`

Creates a new external reference attached to the node identified in the path. The composite PK is (workspace_id, node_id, entity_type, entity_id, relationship). On duplicate PK returns 409 with the existing row so the agent can decide to no-op or PATCH.

## Path parameters

- `node_id` string, required

## Request body

- CreateKnowledgeGraphExternalRefRequest — Request body for creating a new knowledge graph external reference. The parent node_id is taken from the path, not the body.
  - `workspace_id` string, required — The workspace to create the reference in
  - `application_id` string — The application ID (used for auth scope)
  - `entity_type` string, required — The type of external entity
  - `entity_id` string, required — The ID of the external entity
  - `relationship` string, required — The relationship between the node and the entity
  - `entity_variant_id` string — The variant/version ID of the external entity
  - `referenced_entity_version` string — The version of the externally referenced entity
  - `description` string — Human-readable description of this reference
  - `properties` object — Additional structured properties
  - `agent_type` string — Agent type creating this reference
  - `agent_version` string — Agent version creating this reference

## Response `201`

The created external reference

- KnowledgeGraphExternalRef — An external reference linking a knowledge graph node to an external entity. Composite primary key: (workspace_id, node_id, entity_type, entity_id, relationship).
  - `workspace_id` string — The workspace this reference belongs to
  - `node_id` string — The knowledge graph node this reference is attached to
  - `entity_type` string — The type of external entity (e.g. test, flow, plan, step_execution)
  - `entity_id` string — The ID of the external entity
  - `relationship` string — The relationship between the node and the external entity
  - `entity_variant_id` string — The variant/version ID of the external entity at time of linking
  - `referenced_entity_version` string — The version of the externally referenced entity (not the ETag)
  - `description` string — Human-readable description of this reference
  - `properties` object — Additional structured properties for this reference
  - `version` integer — Monotonic edit counter (server-managed, readOnly)
  - `u_version_` string — ETag for optimistic locking (server-managed, readOnly)
  - `last_updated_by` string — Principal who last updated this reference (server-managed, readOnly)
  - `created_by` string — Principal who created this reference (server-managed, readOnly)
  - `agent_type` string — Agent type that wrote this reference
  - `agent_version` string — Agent version that wrote this reference
  - `created_at` string, date-time — Creation timestamp
  - `updated_at` string, date-time — Last update timestamp

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `404` — Entity not found
- `409` — Unknown error
- `422` — Unknown error
- `default` — Unknown error

---

[API](https://skmtc.net/mabl/apis/mabl-api.md) · [All operations](https://skmtc.net/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/d0fc0114da66/schema)