API reference
KYE Protocol™ Core API — v3 Entity Hierarchy + Relationships
46 operations · core.openapi.yaml
KYE Protocol™ Core API: try the first operations
Demo dataYou learn: What a call to this API sends and gets back. You can: Send a request.
API client · List tenants
Request
GET /api/v1/tenants
Response 200
{
"data": [
{
"activated_at": "2026-10-01T09:00:00Z",
"clerk_org_id": "<clerk_org_id>",
"contract_status": "lead",
"created_at": "2026-10-01T09:00:00Z",
"created_by": "<created_by>",
"deleted_at": "2026-10-01T09:00:00Z",
"env": "prod",
"id": "<id>",
"name": "<name>",
"notes": "<notes>",
"owner_email": "name@example.org",
"region": "<region>",
"schema_version": "kye.entity.tenant.v1",
"sla_tier": "pilot",
"slug": "<slug>",
"state": "provisioning"
}
]
}API client · Get a tenant
Request
GET /api/v1/tenants/%3Ctenant_id%3E
Response 200
{
"data": {
"activated_at": "2026-10-01T09:00:00Z",
"clerk_org_id": "<clerk_org_id>",
"contract_status": "lead",
"created_at": "2026-10-01T09:00:00Z",
"created_by": "<created_by>",
"deleted_at": "2026-10-01T09:00:00Z",
"env": "prod",
"id": "<id>",
"name": "<name>",
"notes": "<notes>",
"owner_email": "name@example.org",
"region": "<region>",
"schema_version": "kye.entity.tenant.v1",
"sla_tier": "pilot",
"slug": "<slug>",
"state": "provisioning"
}
}API client · List workspaces
Request
GET /api/v1/workspaces
Response 200
{
"data": [
{
"created_at": "2026-10-01T09:00:00Z",
"created_by": "<created_by>",
"data_residency": "<data_residency>",
"deleted_at": "2026-10-01T09:00:00Z",
"env": "prod",
"id": "<id>",
"kind": "<kind>",
"name": "<name>",
"policy_id": "<policy_id>",
"region": "<region>",
"schema_version": "<schema_version>",
"slug": "<slug>",
"state": "provisioning",
"tenant_id": "<tenant_id>"
}
]
}How this widget is built
- Demonstrates
- KYE™ API
- Components
- The OpenAPI 3.1 contract
- Request and response examples from the contract
- Flow
- Request → response, from the published contract. Architecture diagram
- Used on
- /developers/api/core/: On every contract's reference page.
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
GET/api/v1/tenantsList tenants
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
env | query | string | |
state | query | string |
Responses
200List of tenants
POST/api/v1/tenantsCreate 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
201Created
GET/api/v1/tenants/{tenant_id}Get a tenant
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id required | path | string |
Responses
200Tenant404Not 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
200Updated
DELETE/api/v1/tenants/{tenant_id}Delete (soft-delete) a tenant
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id required | path | string |
Responses
204Deleted
workspaces
GET/api/v1/workspacesList workspaces
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
env | query | string | |
state | query | string |
Responses
200List of workspaces
POST/api/v1/workspacesCreate 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
201Created
GET/api/v1/workspaces/{workspace_id}Get a workspace
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
workspace_id required | path | string |
Responses
200Workspace404Not 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
200Updated
DELETE/api/v1/workspaces/{workspace_id}Delete workspace
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
workspace_id required | path | string |
Responses
204Deleted
principals
GET/api/v1/principalsList principals
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
principal_class | query | string | |
state | query | string |
Responses
200List of principals
POST/api/v1/principalsCreate 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
201Created
POST/api/v1/principals/inviteInvite 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
201Invited
GET/api/v1/principals/{principal_id}Get a principal
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
principal_id required | path | string |
Responses
200Principal404Not 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
200Updated
DELETE/api/v1/principals/{principal_id}Delete a principal
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
principal_id required | path | string |
Responses
204Deleted
teams
GET/api/v1/teamsList teams
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string |
Responses
200Teams
POST/api/v1/teamsCreate 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
201Created
GET/api/v1/teams/{team_id}Get a team
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
team_id required | path | string |
Responses
200Team
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
200Updated
DELETE/api/v1/teams/{team_id}Delete a team
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
team_id required | path | string |
Responses
204Deleted
projects
GET/api/v1/projectsList projects
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
workspace_id | query | string |
Responses
200Projects
POST/api/v1/projectsCreate 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
201Created
GET/api/v1/projects/{project_id}Get a project
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
project_id required | path | string |
Responses
200Project
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
200Updated
DELETE/api/v1/projects/{project_id}Delete a project
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
project_id required | path | string |
Responses
204Deleted
resources
GET/api/v1/resourcesList resources
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
workspace_id | query | string | |
tenant_id | query | string |
Responses
200Resources
POST/api/v1/resourcesCreate 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
201Created
GET/api/v1/resources/{resource_id}Get a resource
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
resource_id required | path | string |
Responses
200Resource
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
200Updated
DELETE/api/v1/resources/{resource_id}Delete a resource
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
resource_id required | path | string |
Responses
204Deleted
relationships
GET/api/v1/relationships/member-ofList principal-team membership rows
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
principal_id | query | string | |
team_id | query | string |
Responses
200Member-of rows
POST/api/v1/relationships/member-ofAdd 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
201Created
DELETE/api/v1/relationships/member-of/{id}Remove principal from team
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
204Deleted
GET/api/v1/relationships/acts-inList principal-workspace binding rows
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
principal_id | query | string | |
workspace_id | query | string |
Responses
200Acts-in rows
POST/api/v1/relationships/acts-inGrant 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
201Created
DELETE/api/v1/relationships/acts-in/{id}Revoke principal workspace access
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
204Deleted
GET/api/v1/relationships/applies-toList policy-target binding rows
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
policy_id | query | string | |
target_id | query | string |
Responses
200Applies-to rows
POST/api/v1/relationships/applies-toBind 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
201Created
DELETE/api/v1/relationships/applies-to/{id}Remove policy binding
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
204Deleted
GET/api/v1/relationships/granted-access-toList resource access grant rows
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
grantee_id | query | string | |
resource_id | query | string |
Responses
200Granted-access-to rows
POST/api/v1/relationships/granted-access-toGrant 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
201Created
DELETE/api/v1/relationships/granted-access-to/{id}Revoke resource access
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
204Deleted
GET/api/v1/relationships/usesList agent-tool/model usage rows
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
agent_id | query | string | |
used_id | query | string |
Responses
200Uses rows
POST/api/v1/relationships/usesBind 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
201Created
DELETE/api/v1/relationships/uses/{id}Remove agent-tool binding
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
204Deleted