---
title: "Create Relationship"
method: POST
path: "/api/relationships"
tags: ["relationships"]
---

# Create Relationship

`POST /api/relationships`

## Request

- Base URL: `https://www.gateco.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://www.gateco.ai/api/relationships`
- Auth: none declared

Create a direct relationship edge.

Idempotent: if the exact same (org, subject, relation, object) tuple already
exists the existing row is returned with HTTP 201 rather than raising 409.
This makes the operation safe to retry without any client-side deduplication.

The creating user is recorded in ``created_by_user_id`` for auditability.

## Request body

- CreateRelationshipRequest: Body for POST /api/relationships. Attributes: subject_principal_id: UUID of the principal who holds the relation. relation_name: Named relation (e.g. ``"viewer"``, ``"editor"``). Between 1 and 64 characters. object_resource_id: UUID of the gated resource being related to.
  - `subject_principal_id` string, uuid, required
  - `relation_name` string, required
  - `object_resource_id` string, uuid, required

## Response `201`

Successful Response

- RelationshipResponse: Safe serialization of a Relationship row. All UUID fields are returned as strings for JSON compatibility. ``created_by_user_id`` is ``None`` when the creator user has been deleted (SET NULL on FK) or was not provided at creation time.
  - `id` string, required
  - `organization_id` string, required
  - `subject_principal_id` string, required
  - `relation_name` string, required
  - `object_resource_id` string, required
  - `created_by_user_id` string, nullable, required
  - `created_at` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/gateco/apis/gateco-api.md) · [All operations](https://skmtc.dev/gateco/apis/gateco-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gateco/apis/gateco-api/revisions/5debaf204950?raw)