---
title: "Create relationship"
method: POST
path: "/entities/{id}/relationships"
tags: ["entities"]
---

# Create relationship

`POST /entities/{id}/relationships`

Creates a relationship between two Entities.  
Specify the source entity via the URL path (`{id}`), and the target entity and relationship type in the request body.

The `type` field determines the direction and nature of the relationship.  
Supported values:
- `parent` – declare the target as the parent of the source
- `child` – declare the target as the child of the source
- `link` – create a non-hierarchical connection between entities
- `isBlockedBy` – create a dependency between entities
- `isBlocking` – create a dependency between entities

## Limitations
- Only valid combinations of source and target entities are allowed for each relationship type.
- The target entity must exist and be accessible.

## Path parameters

- `id` string, uuid, required — A universally unique identifier (UUID).

## Request body

- object
  - `data` EntityRelationshipCreate — Payload representing a new relationship towards target entity.
    - `type` 'parent' | 'child' | 'link' | 'isBlockedBy' | 'isBlocking' — The type of the relationship to be established. ## Relationships - `parent`: Hierarchical relationship indicating the entity is a child of the target - `child`: Hierarchical relationship indicating the entity contains the target - `link`: Generic bidirectional relationship without semantic meaning - `isBlockedBy`: Dependency relationship indicating the entity cannot proceed until the target is resolved - `isBlocking`: Dependency relationship indicating the entity prevents progress on the target
    - `target` ResourceReferenceAssign, required — Entity reference assignment using unique identifier for Entities. ## Behavior - Simple ID-only assignment for referencing other entities - Used for establishing relationships between entities (parent, child, link) - UUID must match an existing entity in the workspace - Commonly used in relationship creation and updates
      - `id` string, uuid — A universally unique identifier (UUID).

## Response `201`

Relationship created successfully

- object
  - `data` EntityRelationship — Represents a relationship between two entities. The source entity is implicit from the request context (the entity being queried).
    - `type` 'parent' | 'child' | 'link' | 'isBlockedBy' | 'isBlocking', required — The type of the relationship to be established. ## Relationships - `parent`: Hierarchical relationship indicating the entity is a child of the target - `child`: Hierarchical relationship indicating the entity contains the target - `link`: Generic bidirectional relationship without semantic meaning - `isBlockedBy`: Dependency relationship indicating the entity cannot proceed until the target is resolved - `isBlocking`: Dependency relationship indicating the entity prevents progress on the target
    - `target` ResourceReference, required — # Description A common response object of entity reference. # Validation # Filtering
      - `id` string, uuid, required — A universally unique identifier (UUID).
      - `type` 'product' | 'component' | 'feature' | 'subfeature' | 'initiative' | 'objective' | 'keyResult' | 'release' | 'releaseGroup' | 'company' | 'user', required — Supported Entity types: - product - component - feature - subfeature - initiative - objective - keyResult - release - releaseGroup - company - user The exact types available may vary based on the configuration of the workspace.
      - `links` EntityLinks
        - `self` string, required
        - `html` string, nullable, required — Deep link to the entity in the Productboard web UI. Null when the parent space has no domain configured (e.g. newly-onboarded spaces or replays).
  - `links` ResourceLinks
    - `self` string, required

## Other responses

- `400` — Bad Request - Invalid input format or malformed request
- `401` — Unauthorized - Missing or invalid authentication credentials
- `403` — Forbidden - Insufficient permissions
- `404` — Not Found - The requested resource does not exist or is not accessible
- `408` — Request Timeout - The server did not receive a complete request within the allowed time
- `409` — Conflict - Action cannot be performed due to current state or constraint violation
- `422` — Unprocessable Entity - Validation failed (e.g., missing required fields, unknown fields)
- `429` — Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time
- `500` — Internal Server Error - An unexpected error occurred on the server, please retry or contact support

---

[API](https://skmtc.dev/productboard/apis/notes.md) · [All operations](https://skmtc.dev/productboard/apis/notes/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/productboard/notes/revisions/b4004749b60f/schema)