VegaGraph API reference

REST resource groups, workspace scoping, mutation semantics and traversal endpoints.

The VegaGraph API is rooted under an organization and workspace:

/api/v1/vegagraph/orgs/{org_id}/workspaces/{workspace_id}

All IDs in a request are resolved again inside that scope. Supplying a valid entity ID from another workspace returns no cross-tenant access.

Read API fundamentals for service base paths and authentication, or follow the API quickstart for a small graph example.

Request conventions

JSON request and response bodies use the field names shown by the service schema.
PUT replaces editable fields; PATCH preserves omitted fields and uses explicit clear_fields where supported.
Lists are bounded and may expose q, type/category, context, lifecycle and paging filters.
Deletes return 204 No Content; do not parse a JSON response body.
Resource versions should be preserved for optimistic concurrency when returned.
Timestamps are ISO 8601 values; IDs are opaque strings.

Error model

Errors include an HTTP status and structured details. Preserve the machine-readable code, field/location errors and request identity where supplied.

Status	Meaning
`400`	Invalid request field or unsupported transition.
`401`	Authentication is missing or invalid.
`403`	The principal lacks a required permission.
`404`	The scoped resource is missing or not visible.
`409`	Identity, cardinality, cycle, version or dependency conflict.
`422`	Schema or relationship-contract validation failed.

Do not retry validation and conflict errors unchanged. A safe retry of a failed network request should first reconcile by stable FQN, alias, edge identity or returned resource ID.

Type catalog

Resource	Routes
Entity types	`POST/GET /entity-types`, `GET/PUT/PATCH/DELETE /entity-types/{id}`
Aspect types	`POST/GET /aspect-types`, `GET/PUT/PATCH/DELETE /aspect-types/{id}`
Relationship types	`POST/GET /relationship-types`, `GET/PUT/PATCH/DELETE /relationship-types/{id}`
Aspect bindings	`POST/GET /entity-types/{id}/aspects`, `DELETE /entity-types/{id}/aspects/{aspect_id}`
Impact preview	`POST /type-impact:preview`

POST/GET /contexts creates and lists contexts. Resolve the default context with /contexts/default, an FQN with /contexts/by-fqn?fqn=..., and one row with /contexts/{id}. Update with PUT or partial PATCH; delete with DELETE after dependency checks.

Entities and aspects

POST   /entities
GET    /entities
GET    /entities/{entity_id}
PUT    /entities/{entity_id}
PATCH  /entities/{entity_id}
DELETE /entities/{entity_id}

POST /entities/{entity_id}/aliases
GET  /entities/{entity_id}/aliases

POST /entities/{entity_id}/aspects
GET  /entities/{entity_id}/aspects
GET  /entities/{entity_id}/aspects/{aspect_type_id}
GET  /entities/{entity_id}/aspects/{aspect_type_id}/versions

List endpoints support resource-specific filters and visibility enforcement. Use aspect history only for an audit/change view; current aspect reads apply context overlay behavior.

Field references

POST   /entities/{entity_id}/field-refs
GET    /entities/{entity_id}/field-refs
GET    /field-refs/{field_ref_id}
GET    /field-refs/{field_ref_id}/lineage
DELETE /field-refs/{field_ref_id}

Edges and traversal

POST   /edges
GET    /edges
GET    /entities/{entity_id}/edges
GET    /edges/{edge_id}
PUT    /edges/{edge_id}
PATCH  /edges/{edge_id}
DELETE /edges/{edge_id}

GET /entities/{entity_id}/traverse
GET /entities/{entity_id}/hierarchy/path
GET /entities/{entity_id}/hierarchy/children
GET /entities/{entity_id}/360

Edge writes validate endpoint type constraints, field compatibility, context boundaries, cardinality and acyclic rules. A successful HTTP request is therefore stronger than a syntactically valid edge document.

Labels and search

Labels have CRUD routes under /labels, including /labels/by-fqn. Assignments have create/list/get/delete routes under /label-assignments.

Search uses GET /search. A search document is replaced with PUT /entities/{id}/search-document, read with GET and removed with DELETE.

Built-in collections

GET /tables
GET /kpis
GET /services
GET /repositories
GET /environments

Each collection supports /{entity_id} and /{entity_id}/360. Product-specific projections include table columns/path, KPI lineage/impact, service dependencies/runtime, repository services and environment runtime.

Error and delete behavior

Validation errors are structured and keep a stable machine-readable code where the implementation provides one. Authorization is checked separately from not-found handling to avoid leaking cross-workspace existence.

DELETE routes return 204 with no body. PATCH routes preserve omitted fields and use the resource's explicit clear_fields allowlist for nullable values.