---
title: "KYE Protocol™ Core API — v3 Entity Hierarchy + Relationships | API reference"
description: "KYE Protocol™ Core API — v3 Entity Hierarchy + Relationships: 46 operations from core.openapi.yaml, a published KYE Protocol™ OpenAPI contract."
url: https://kyeprotocol.com/developers/api/core/
lang: en
source: "KYE Protocol"
---

> KYE Protocol™ Core API — v3 Entity Hierarchy + Relationships: 46 operations from core.openapi.yaml, a published KYE Protocol™ OpenAPI contract.

API reference

# KYE Protocol™ Core API — v3 Entity Hierarchy + Relationships

46 operations · `core.openapi.yaml`

**Servers**

`https://api.kyeprotocol.com`

**Version**

3.0.0

**Source**

[core.openapi.yaml](https://kyeprotocol.com/developers/api/core.openapi.yaml)

CRUD endpoints for the v3 KYE™ entity hierarchy (Tenant → Workspace → Principal, Team, Project, Resource, Policy, Legal Entity, Billing Account, Domain, Model, Tool, External App, Audit Stream) and the five typed relationship tables (member-of, acts-in, applies-to, granted-access-to, uses).

Base path: /api/v1/

tenants 5 workspaces 5 principals 6 teams 5 projects 5 resources 5 relationships 15

## tenants

GET `/api/v1/tenants` List tenants

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `env` | query | string |  |
| `state` | query | string |  |

### Responses

- `200` List of tenants

POST `/api/v1/tenants` Create a tenant

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `slug` **required** | string |  |
| `name` **required** | string |  |
| `env` **required** | string | One of prod, sandbox, test |
| `region` | string |  |
| `owner_email` | string |  |
| `sla_tier` | string |  |

### Responses

- `201` Created

GET `/api/v1/tenants/{tenant_id}` Get a tenant

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` **required** | path | string |  |

### Responses

- `200` Tenant
- `404` Not found

PUT `/api/v1/tenants/{tenant_id}` Update tenant metadata

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` **required** | path | string |  |

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `name` | string |  |
| `state` | string |  |
| `notes` | string |  |

### Responses

- `200` Updated

DELETE `/api/v1/tenants/{tenant_id}` Delete (soft-delete) a tenant

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` **required** | path | string |  |

### Responses

- `204` Deleted

## workspaces

GET `/api/v1/workspaces` List workspaces

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` | query | string |  |
| `env` | query | string |  |
| `state` | query | string |  |

### Responses

- `200` List of workspaces

POST `/api/v1/workspaces` Create a workspace

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `id` **required** | string |  |
| `tenant_id` **required** | string |  |
| `slug` **required** | string |  |
| `name` **required** | string |  |
| `env` **required** | string | One of prod, sandbox, test, dev |
| `region` **required** | string |  |
| `kind` | string |  |
| `data_residency` | string,null |  |
| `policy_id` | string,null |  |
| `state` **required** | string | One of provisioning, active, archived, deleted |
| `created_by` **required** | string |  |
| `created_at` **required** | string |  |
| `deleted_at` | string,null |  |

### Responses

- `201` Created

GET `/api/v1/workspaces/{workspace_id}` Get a workspace

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `workspace_id` **required** | path | string |  |

### Responses

- `200` Workspace
- `404` Not found

PUT `/api/v1/workspaces/{workspace_id}` Update workspace

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `workspace_id` **required** | path | string |  |

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `id` **required** | string |  |
| `tenant_id` **required** | string |  |
| `slug` **required** | string |  |
| `name` **required** | string |  |
| `env` **required** | string | One of prod, sandbox, test, dev |
| `region` **required** | string |  |
| `kind` | string |  |
| `data_residency` | string,null |  |
| `policy_id` | string,null |  |
| `state` **required** | string | One of provisioning, active, archived, deleted |
| `created_by` **required** | string |  |
| `created_at` **required** | string |  |
| `deleted_at` | string,null |  |

### Responses

- `200` Updated

DELETE `/api/v1/workspaces/{workspace_id}` Delete workspace

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `workspace_id` **required** | path | string |  |

### Responses

- `204` Deleted

## principals

GET `/api/v1/principals` List principals

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` | query | string |  |
| `principal_class` | query | string |  |
| `state` | query | string |  |

### Responses

- `200` List of principals

POST `/api/v1/principals` Create a principal

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `id` **required** | string |  |
| `tenant_id` **required** | string |  |
| `workspace_id` | string,null |  |
| `principal_class` **required** | string | One of human, system, agent, external\_app |
| `subclass` | string |  |
| `display_name` **required** | string |  |
| `state` **required** | string | One of pending, active, suspended, revoked, deleted |
| `human` | object,null |  |
| `system` | object,null |  |
| `agent` | object,null |  |
| `external_app` | object,null |  |
| `created_at` **required** | string |  |
| `updated_at` | string,null |  |
| `deleted_at` | string,null |  |

### Responses

- `201` Created

POST `/api/v1/principals/invite` Invite a human principal by email

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `tenant_id` **required** | string |  |
| `principal_class` **required** | string | One of human |
| `display_name` **required** | string |  |
| `state` | string |  |
| `human` | object |  |
| `invite` **required** | object |  |

### Responses

- `201` Invited

GET `/api/v1/principals/{principal_id}` Get a principal

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `principal_id` **required** | path | string |  |

### Responses

- `200` Principal
- `404` Not found

PUT `/api/v1/principals/{principal_id}` Update a principal

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `principal_id` **required** | path | string |  |

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `id` **required** | string |  |
| `tenant_id` **required** | string |  |
| `workspace_id` | string,null |  |
| `principal_class` **required** | string | One of human, system, agent, external\_app |
| `subclass` | string |  |
| `display_name` **required** | string |  |
| `state` **required** | string | One of pending, active, suspended, revoked, deleted |
| `human` | object,null |  |
| `system` | object,null |  |
| `agent` | object,null |  |
| `external_app` | object,null |  |
| `created_at` **required** | string |  |
| `updated_at` | string,null |  |
| `deleted_at` | string,null |  |

### Responses

- `200` Updated

DELETE `/api/v1/principals/{principal_id}` Delete a principal

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `principal_id` **required** | path | string |  |

### Responses

- `204` Deleted

## teams

GET `/api/v1/teams` List teams

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` | query | string |  |

### Responses

- `200` Teams

POST `/api/v1/teams` Create a team

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `id` **required** | string |  |
| `tenant_id` **required** | string |  |
| `workspace_id` | string,null |  |
| `slug` **required** | string |  |
| `name` **required** | string |  |
| `state` | string |  |
| `created_by` | string |  |
| `created_at` **required** | string |  |

### Responses

- `201` Created

GET `/api/v1/teams/{team_id}` Get a team

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `team_id` **required** | path | string |  |

### Responses

- `200` Team

PUT `/api/v1/teams/{team_id}` Update a team

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `team_id` **required** | path | string |  |

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `id` **required** | string |  |
| `tenant_id` **required** | string |  |
| `workspace_id` | string,null |  |
| `slug` **required** | string |  |
| `name` **required** | string |  |
| `state` | string |  |
| `created_by` | string |  |
| `created_at` **required** | string |  |

### Responses

- `200` Updated

DELETE `/api/v1/teams/{team_id}` Delete a team

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `team_id` **required** | path | string |  |

### Responses

- `204` Deleted

## projects

GET `/api/v1/projects` List projects

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `workspace_id` | query | string |  |

### Responses

- `200` Projects

POST `/api/v1/projects` Create a project

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `id` **required** | string |  |
| `tenant_id` **required** | string |  |
| `workspace_id` **required** | string |  |
| `slug` **required** | string |  |
| `name` **required** | string |  |
| `state` | string |  |
| `created_by` | string |  |
| `created_at` **required** | string |  |

### Responses

- `201` Created

GET `/api/v1/projects/{project_id}` Get a project

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `project_id` **required** | path | string |  |

### Responses

- `200` Project

PUT `/api/v1/projects/{project_id}` Update a project

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `project_id` **required** | path | string |  |

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `id` **required** | string |  |
| `tenant_id` **required** | string |  |
| `workspace_id` **required** | string |  |
| `slug` **required** | string |  |
| `name` **required** | string |  |
| `state` | string |  |
| `created_by` | string |  |
| `created_at` **required** | string |  |

### Responses

- `200` Updated

DELETE `/api/v1/projects/{project_id}` Delete a project

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `project_id` **required** | path | string |  |

### Responses

- `204` Deleted

## resources

GET `/api/v1/resources` List resources

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `workspace_id` | query | string |  |
| `tenant_id` | query | string |  |

### Responses

- `200` Resources

POST `/api/v1/resources` Create a resource

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `id` **required** | string |  |
| `tenant_id` **required** | string |  |
| `workspace_id` | string,null |  |
| `name` **required** | string |  |
| `resource_type` | string |  |
| `state` | string |  |
| `created_by` | string |  |
| `created_at` **required** | string |  |

### Responses

- `201` Created

GET `/api/v1/resources/{resource_id}` Get a resource

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `resource_id` **required** | path | string |  |

### Responses

- `200` Resource

PUT `/api/v1/resources/{resource_id}` Update a resource

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `resource_id` **required** | path | string |  |

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `id` **required** | string |  |
| `tenant_id` **required** | string |  |
| `workspace_id` | string,null |  |
| `name` **required** | string |  |
| `resource_type` | string |  |
| `state` | string |  |
| `created_by` | string |  |
| `created_at` **required** | string |  |

### Responses

- `200` Updated

DELETE `/api/v1/resources/{resource_id}` Delete a resource

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `resource_id` **required** | path | string |  |

### Responses

- `204` Deleted

## relationships

GET `/api/v1/relationships/member-of` List principal-team membership rows

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `principal_id` | query | string |  |
| `team_id` | query | string |  |

### Responses

- `200` Member-of rows

POST `/api/v1/relationships/member-of` Add principal to team

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `principal_id` **required** | string |  |
| `team_id` **required** | string |  |
| `role` **required** | string | One of owner, admin, member, approver, viewer, auditor |
| `joined_at` **required** | string |  |
| `left_at` | string,null |  |

### Responses

- `201` Created

DELETE `/api/v1/relationships/member-of/{id}` Remove principal from team

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `id` **required** | path | string |  |

### Responses

- `204` Deleted

GET `/api/v1/relationships/acts-in` List principal-workspace binding rows

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `principal_id` | query | string |  |
| `workspace_id` | query | string |  |

### Responses

- `200` Acts-in rows

POST `/api/v1/relationships/acts-in` Grant principal workspace access

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `principal_id` **required** | string |  |
| `workspace_id` **required** | string |  |
| `since` **required** | string |  |
| `until` | string,null |  |
| `allowed_actions` | array |  |

### Responses

- `201` Created

DELETE `/api/v1/relationships/acts-in/{id}` Revoke principal workspace access

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `id` **required** | path | string |  |

### Responses

- `204` Deleted

GET `/api/v1/relationships/applies-to` List policy-target binding rows

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `policy_id` | query | string |  |
| `target_id` | query | string |  |

### Responses

- `200` Applies-to rows

POST `/api/v1/relationships/applies-to` Bind a policy to a target

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `policy_id` **required** | string |  |
| `target_class` **required** | string |  |
| `target_id` **required** | string |  |
| `effective_from` | string |  |
| `effective_until` | string,null |  |

### Responses

- `201` Created

DELETE `/api/v1/relationships/applies-to/{id}` Remove policy binding

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `id` **required** | path | string |  |

### Responses

- `204` Deleted

GET `/api/v1/relationships/granted-access-to` List resource access grant rows

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `grantee_id` | query | string |  |
| `resource_id` | query | string |  |

### Responses

- `200` Granted-access-to rows

POST `/api/v1/relationships/granted-access-to` Grant resource access

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `grantee_id` **required** | string |  |
| `grantee_kind` **required** | string |  |
| `resource_id` **required** | string |  |
| `access_level` **required** | string | One of read, write, admin, execute, owner |
| `granted_by` **required** | string |  |
| `granted_at` **required** | string |  |
| `expires_at` | string,null |  |
| `revoked_at` | string,null |  |

### Responses

- `201` Created

DELETE `/api/v1/relationships/granted-access-to/{id}` Revoke resource access

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `id` **required** | path | string |  |

### Responses

- `204` Deleted

GET `/api/v1/relationships/uses` List agent-tool/model usage rows

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `agent_id` | query | string |  |
| `used_id` | query | string |  |

### Responses

- `200` Uses rows

POST `/api/v1/relationships/uses` Bind an agent to a tool or model

**Auth:** bearerAuth

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `schema_version` | string |  |
| `agent_id` **required** | string |  |
| `used_id` **required** | string |  |
| `usage_kind` **required** | string |  |
| `allowed` **required** | boolean |  |
| `since` | string |  |
| `until` | string,null |  |

### Responses

- `201` Created

DELETE `/api/v1/relationships/uses/{id}` Remove agent-tool binding

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `id` **required** | path | string |  |

### Responses

- `204` Deleted