#Entities

---

#GET /{o}/{p}/entities/facets

Entity facet counts

Faceted counts by kind, state, owner label, and cell label. Each dimension is counted with every other dimension's filters applied (cross-exclusion).

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
o	string
p	string

Query parameters

Name	Type	Description
kind	string	JSON-encoded string array — entity type names. '' matches rows where the label is unset
state	string	JSON-encoded string array — states. '' matches rows where the label is unset
owner	string	JSON-encoded string array — owner label values. '' matches rows where the label is unset
cell	string	JSON-encoded string array — cell label values. '' matches rows where the label is unset
search	string	Substring match on name + entity type
cellKey	string	Project cell label key; omit to skip the cell dimension

Responses

Status	Description	Schema
200	OK	EntityFacets
401	Unauthorized	Error
403	Forbidden	Error

---

#GET /{o}/{p}/entities/groups

Entity counts per group

Membership counts per group — cell, entity type, or label value — with the per-type state and open-conformance roll-ups a collapsed group renders, in place of the member entities themselves. An entity in two cells is counted under both; entities no group claims land in ungrouped.

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
o	string
p	string

Query parameters

Name	Type	Description
groupBy	cell | entityType | label	Grouping axis: cell membership, entity type, or a label key (required)
labelKey	string	Label key to group by — required when groupBy=label

Responses

Status	Description	Schema
200	OK	EntityGroups
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error

---

#GET /{o}/{p}/entities

List entities

List entities in this project with optional filtering and keyset pagination. source narrows to one import source; the project-wide graph is the default (R3).

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
o	string
p	string

Query parameters

Name	Type	Description
entityType	string	Filter by entity type
state	string	Filter by state
limit	integer	Max results (1-2000)
cursor	string	Keyset cursor from the previous page
driftStatus	current | stale | missing	Filter by drift status
source	string	Filter to entities bound to one canonical source URI

Responses

Status	Description	Schema
200	OK	EntityPage
401	Unauthorized	Error
403	Forbidden	Error

---

#GET /{o}/{p}/entities/stream

Stream entity changes (SSE)

Server-Sent Events stream of entity create/update/delete in this project.

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
o	string
p	string

Responses

Status	Description	Schema
200	text/event-stream stream; the connection stays open and frames are delivered as they occur
401	Unauthorized	Error
403	Forbidden	Error

---

#GET /{o}/{p}/entities/metrics

Batch-read entity metric values

Read metric values for many entities in one call, keyed by entity name. Unknown/out-of-scope names are omitted.

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
o	string
p	string

Query parameters

Name	Type	Description
names	string	Comma-separated entity names to fetch metrics for (max 500) (required)

Responses

Status	Description	Schema
200	OK	EntityMetricsBatch
401	Unauthorized	Error
403	Forbidden	Error

---

#GET /{o}/{p}/entities/{name}/drift

Get entity drift status

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
name	string	Entity name
o	string
p	string

Responses

Status	Description	Schema
200	OK	EntityDriftStatus
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#GET /{o}/{p}/entities/{name}

Get an entity by name

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
name	string	Entity name
o	string
p	string

Responses

Status	Description	Schema
200	OK	Entity
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#GET /{o}/{p}/entities/{name}/relationships

List an entity's relationships

Returns all relationships incident on the entity (explicit ∪ derived). Derived edges carry null id/state/fromEntityId/toEntityId and origin: "derived".

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
name	string	Entity name
o	string
p	string

Responses

Status	Description	Schema
200	OK	ResolvedRelationshipList
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#GET /{o}/{p}/entities/{name}/metrics

Get an entity's metric values

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
name	string	Entity name
o	string
p	string

Responses

Status	Description	Schema
200	OK	EntityMetrics
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#PUT /{o}/{p}/entities/{name}/metrics/{metricName}

Set a manual/push metric value

Auth: Bearer token required · Permission: metrics:write

Path parameters

Name	Type	Description
name	string	Entity name
metricName	string	Metric name
o	string
p	string

Request body (application/json)

Field	Type	Description
value	number	Metric value (required)

Responses

Status	Description	Schema
200	OK	EntityMetricValue
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#GET /{o}/{p}/entities/{name}/actions

List available instance actions for an entity

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
name	string	Entity name
o	string
p	string

Responses

Status	Description	Schema
200	OK	ActionList
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#POST /{o}/{p}/entities/{name}/actions/{actionName}

Trigger an instance action on an entity

Auth: Bearer token required · Permission: actions:trigger

Path parameters

Name	Type	Description
name	string	Entity name
actionName	string	Action name
o	string
p	string

Request body (application/json)

Field	Type	Description
parameters	object	Action parameters as JSON
recommendations	object	Recommendation selections as JSON

Responses

Status	Description	Schema
202	Accepted	ActionRun
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#POST /{o}/{p}/entities/{name}/sync-stamp

Record a sync observation for an entity

Auth: Bearer token required · Permission: observations:write

Path parameters

Name	Type	Description
name	string	Entity name
o	string
p	string

Request body (application/json)

Field	Type	Description
source	string	Source-of-truth name (e.g. argo, k8s, aws) (required)
observedAt	string(date-time)	ISO-8601 observation timestamp; defaults to server time

Responses

Status	Description	Schema
200	OK	EntitySyncStamp
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

#Schemas

#Action

Field	Type	Description
name	string	(required)
displayName	string | null	(required)
description	string | null	(required)
associatedWith	object	(required)
conditions	object[]	(required)
parameters	object[]	(required)
recommendations	object[]	(required)
operation	object | object | object | object | object | object | object | object	(required)
trigger	object | object | object | object | object | object | null	(required)
dependsOn	object[] | null	(required)
mutatesProperty	string | null	(required)
timeoutMinutes	integer | null	(required)
orgId	string	(required)
projectId	string	(required)
createdAt	string | string	(required)
updatedAt	string | string	(required)

#ActionList

Type: Action[]

#ActionRun

Field	Type	Description
id	string(uuid)	(required)
actionName	string	(required)
entityId	string(uuid) | null	(required)
status	pending | running | succeeded | failed | cancelled | dispatching | blocked	(required)
parameters	object	(required)
recommendations	object	(required)
triggeredBy	string	(required)
createdAt	string | string	(required)
startedAt	string | string | null	(required)
completedAt	string | string | null	(required)
error	string | null	(required)
output	object | null	(required)
orgId	string	(required)
projectId	string	(required)
operationEntityId	string | null	(required)
metadata	object | null	(required)
resolvedTargets	object	(required)

#Entity

Field	Type	Description
id	string(uuid)	(required)
entityTypeName	string	(required)
name	string	(required)
state	string	(required)
properties	object	(required)
labels	object	(required)
lastSyncedAt	string | string | null	(required)
syncSource	string | null	(required)
createdAt	string | string	(required)
updatedAt	string | string	(required)
orgId	string	(required)
projectId	string	(required)

#EntityDriftStatus

Field	Type	Description
name	string	(required)
driftStatus	string | null	(required)
lastSyncedAt	string | null	(required)
syncSource	string | null	(required)
message	string	(required)

#EntityFacets

Field	Type	Description
kind	object[]	(required)
state	object[]	(required)
owner	object[]	(required)
cell	object[]	(required)
total	integer	(required)

#EntityGroups

Field	Type	Description
groupBy	cell | entityType | label	(required)
labelKey	string | null	(required)
groups	object[]	(required)
ungrouped	object	(required)

#EntityMetricValue

Field	Type	Description
entityName	string	(required)
metricName	string	(required)
value	number	(required)

#EntityMetrics

Type: object

#EntityMetricsBatch

Type: object

#EntityPage

Field	Type	Description
items	Entity[]	(required)
nextCursor	string | null	Cursor for the next page; null on the final page (required)

#EntitySyncStamp

Field	Type	Description
id	string(uuid)	(required)
name	string	(required)
lastSyncedAt	string | string | null	(required)
syncSource	string | null	(required)

#Error

Field	Type	Description
error	string	(required)
code	string

#PlacementDecision

Field	Type	Description
groupingKind	Cell | DeploymentTargetSet	(required)
group	string	(required)
policy	least-loaded | round-robin | random	(required)
metric	string | null	(required)
metricValue	number | null	(required)
candidates	integer	(required)

#ResolvedRelationshipList

Type: ResolvedRelationshipListRow[]

#ResolvedRelationshipListRow

Field	Type	Description
id	string(uuid) | null	(required)
relationshipTypeName	string	(required)
fromEntityName	string	(required)
toEntityName	string	(required)
origin	explicit | derived	(required)
state	string | null	(required)
labels	object	(required)
fromEntityId	string | null	(required)
toEntityId	string | null	(required)
orgId	string | null	(required)
projectId	string | null	(required)
createdAt	string | string | null	(required)
updatedAt	string | string | null	(required)
deletionScheduledAt	string | string | null	(required)
deletionGracePeriodSeconds	integer | null	(required)

#ResolvedTargetRecord

Field	Type	Description
name	string	(required)
provider	aws | gcp | s3-backend | tfc-workspace | generic	(required)
placement	PlacementDecision