VegaGraph API reference

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.

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

Contexts

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.

Quality and check history

Quality lists and scores accept an optional publication context_urn. Omitting it selects the dataset's default publication. The context must belong to that dataset; a pending binding with no default returns published_asset_default_pending until a default is available.

GET /vegagraph/dq-checks?target_urn={dataset_urn}&context_urn={environment_urn}
GET /vegagraph/quality/scores?scope_urn={dataset_urn}&context_urn={environment_urn}
GET /vegagraph/dq-checks/{entity_id}/history?context_urn={environment_urn}&from={timestamp}&to={timestamp}&cursor={cursor}&limit=100

The list exposes current status and the bounded 30-run summary with Graph read permission. A history read additionally requires read on both the check and its selected target, plus VegaDB workspace use. VegaDB executes the series query with the viewer's credential and SQL-editor warehouse defaults. A viewer without VegaDB access receives 403 history_access_denied; this is not an empty history. Keep showing the Graph summary from the check list. Load history only after a user action or when its panel is expanded; never start a history query on a passive page view. A read waits a bounded time for a cold warehouse to become ready. 503 warehouse_starting and 503 history_unavailable are retryable and carry a Retry-After header in seconds; preserve the selected context and retry after at least that long. Warehouse-stopped, unavailable, start-failed and query-timeout errors remain explicit.

An authored-check mutation that exhausts retries because the graph changed concurrently returns HTTP 409. Reload the check and its current ETag before retrying. Pipeline checks remain source-managed and read-only.

History pages default to 100 rows (maximum 500), a 30-day window (maximum 365 days), and a 1 MiB response. Follow the returned opaque cursor without changing check, context or window; cursors expire after 15 minutes. A 400 history_cursor_invalid requires reloading the first page. Pages contain persisted observation values, never failed-key samples. history_pending indicates known evidence has not appeared in the available ops history; summary_complete is false when publication or retained evidence cannot prove completeness. Reload the first page after delayed history publication. retention_start is the earliest matching persisted observation, or null. Malformed persisted observations are skipped and counted in invalid_rows; valid observations remain available.

For a published dataset, logical-asset target rows are included only under the default context when their observation time predates the first successful default-publication binding; they are marked legacy_target: true. Later logical-asset rows are excluded. Each environment's current pipeline observations target its own published object, including when VegaDB metadata lookup is unavailable. An unpublished asset's canonical asset-target rows are its ordinary series and are never marked legacy. The immutable history schema has no environment identity, so genuinely pre-binding logical-asset rows cannot be separated further.

History distinguishes a confirmed missing ops table from a failed query. Generic catalog errors return 502 history_query_failed; they are never an empty history. A metadata service that cannot confirm freshness returns an explicit retryable error, including 503 history_unavailable while support is unavailable. Keep the current context and show a retry action. 502 history_result_invalid means the returned page could not be validated, including a continuation that did not advance; do not repeat that cursor automatically.

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.