POST /v1/link

Create a manual relationship between two entities in the knowledge graph. Manual links have full confidence and supplement the automatically extracted relationships.

Request

POST /v1/link
Content-Type: application/json
Authorization: Bearer <api-key>

Body

{
  "tenant_id": "my-app",
  "source_entity": "ent_002",
  "target_entity": "ent_001",
  "relationship": "uses",
  "metadata": {
    "since": "2026-03-10",
    "note": "Migration completed in PR #456"
  },
  "namespace": "engineering"
}

Parameters

| Field | Type | Required | Description | |---|---|---|---| | tenant_id | string | Yes | Tenant identifier | | source_entity | string | Yes | Source entity ID | | target_entity | string | No* | Target entity ID | | target_episode | string | No* | Target episode ID (for entity-to-episode links) | | relationship | string | Yes | Relationship type (e.g., uses, owns, depends_on) | | metadata | object | No | Additional metadata for the relationship | | namespace | string | No | Namespace |

*Either target_entity or target_episode must be provided.

Response

Status: 201 Created

{
  "link_id": "lnk_x1y2z3",
  "source": {"id": "ent_002", "name": "payments service", "type": "service"},
  "target": {"id": "ent_001", "name": "CockroachDB", "type": "technology"},
  "relationship": "uses",
  "confidence": 1.0,
  "created_at": "2026-03-15T12:00:00Z"
}

Example

curl -X POST https://api.cortexdb.io/v1/link \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my-app",
    "source_entity": "ent_002",
    "target_entity": "ent_001",
    "relationship": "uses"
  }'

Common Relationship Types

| Type | Example | |---|---| | uses | service uses technology | | owns | person owns service | | depends_on | service depends_on service | | created | person created feature | | decided | person decided decision | | replaced | technology replaced technology | | part_of | component part_of system | | caused | event caused event | | blocked_by | task blocked_by task | | related_to | general association |