VegaGraph API quickstart

Create a typed entity, add governed metadata, connect lineage and inspect a 360 view.

This walkthrough creates two existing-type entities, adds an ownership aspect and connects them with a typed relationship. Use type IDs returned by your workspace; names below are illustrative.

For an existing graph, use the dashboard walkthrough. Before making API requests, check authentication and workspace scope.

API base

{api-base}/orgs/{org_id}/workspaces/{workspace_id}

All IDs are resolved again inside this scope. A valid ID from another workspace does not grant cross-workspace visibility.

1. Find types

GET {workspace-base}/entity-types?q=table
GET {workspace-base}/aspect-types?q=ownership
GET {workspace-base}/relationship-types?q=computed_from

Record the exact IDs. Do not assume that a display name is a stable API identifier.

2. Create an entity

POST {workspace-base}/entities
Content-Type: application/json

{
  "entity_type_id": "etype_table...",
  "name": "fact_orders",
  "display_name": "Fact orders",
  "fqn": "table/vegadb/analytics/sales/fact_orders",
  "lifecycle": "active",
  "source_system": "vegadb",
  "external_id": "analytics.sales.fact_orders",
  "confidence": 1
}

The FQN is workspace-unique and should remain stable across display-name changes. Connectors should reuse the entity when they can prove source identity.

3. Add an aspect

POST {workspace-base}/entities/{entity_id}/aspects
Content-Type: application/json

{
  "aspect_type_id": "atype_ownership...",
  "aspect_key": "default",
  "data": {
    "teams": ["growth-data"],
    "technical_owner": "data-platform-oncall"
  },
  "source_system": "manual",
  "confidence": 1
}

VegaGraph validates data against the aspect type's JSON Schema and creates a new version. It does not overwrite aspect history.

4. Add a field reference

POST {workspace-base}/entities/{entity_id}/field-refs

{
  "aspect_type_id": "atype_table_schema...",
  "field_key": "customer_id",
  "field_path": "/columns/customer_id",
  "fqn": "table/vegadb/analytics/sales/fact_orders#customer_id",
  "display_name": "Customer ID",
  "field_kind": "column",
  "data_type": "BIGINT",
  "ordinal": 1
}

Use field references for items that need lineage or classification but not the full lifecycle of a separate entity.

5. Connect entities or fields

POST {workspace-base}/edges

{
  "relationship_type_id": "rtype_computed_from...",
  "from_entity_id": "entity_model_output...",
  "to_entity_id": "entity_source_table...",
  "from_field_ref_id": "field_output_customer_id...",
  "to_field_ref_id": "field_source_customer_id...",
  "source_system": "vegaflow",
  "source_run_id": "run_01...",
  "confidence": 1,
  "evidence": {"pipeline_version_id": "pver_01..."}
}

The relationship contract validates endpoint types, optional field endpoints, cardinality, context and acyclic behavior.

6. Read the result

GET {workspace-base}/entities/{entity_id}/360
GET {workspace-base}/entities/{entity_id}/traverse?direction=outbound&max_depth=3

The 360 view returns a bounded detail projection. Traversal returns a graph result. Use the appropriate endpoint rather than assembling dozens of unrelated list calls.