Manual · Graph
Graph Index
SapixDB maintains a separate graph layer that stores typed directional edges between agents. Graph edges describe the structureof your data model — which agents relate to which — independently of the records stored in each agent's strand.
Multi-agent joins are data-level field matches. A join query scans the records of two agents at query time and pairs rows that share a field value.
Use graph edges to model your data hierarchy and drive traversal. Use joins when you need to correlate specific record values across agents. The two features are complementary.
Creating an edge
An edge is a directional, typed link from one agent to another. The edge_type is a free-form string you define — it describes the nature of the relationship.
POST /v1/graph/edges
Authorization: Bearer spx_root_YOUR_ROOT_KEY
Content-Type: application/json
{
"from_agent": "users",
"to_agent": "orders",
"edge_type": "has_orders",
"meta": {
"established": "2026-07-09"
}
}| Field | Required | Description |
|---|---|---|
from_agent | Yes | Agent ID the edge originates from. |
to_agent | Yes | Agent ID the edge points to. |
edge_type | Yes | A label describing the relationship (e.g. "has_orders", "belongs_to"). |
meta | No | Arbitrary JSON object stored alongside the edge. |
Listing edges
Edges from an agent
GET /v1/graph/edges?from=users Authorization: Bearer spx_root_YOUR_ROOT_KEY
Returns all edges where from_agent is users — i.e. everything that users points to.
{
"edges": [
{
"from_agent": "users",
"to_agent": "orders",
"edge_type": "has_orders",
"meta": { "established": "2026-07-09" }
},
{
"from_agent": "users",
"to_agent": "profiles",
"edge_type": "has_profile",
"meta": {}
}
]
}Edges to an agent
GET /v1/graph/edges?to=orders Authorization: Bearer spx_root_YOUR_ROOT_KEY
Returns all edges where to_agent is orders — i.e. which agents point to orders.
Deleting an edge
Delete a specific edge by specifying the from agent, to agent, and edge type in the URL path:
DELETE /v1/graph/edges/users/orders/has_orders Authorization: Bearer spx_root_YOUR_ROOT_KEY
Returns 204 No Content on success. Deleting an edge does not affect records stored in either agent.
Graph traversal
Traversal follows edges outward from a starting agent up to a specified hop depth. It returns all agents reachable within that depth along with the edge types connecting them.
GET /v1/graph/traverse?from=users&depth=2 Authorization: Bearer spx_root_YOUR_ROOT_KEY
{
"origin": "users",
"depth": 2,
"nodes": [
{ "agent": "orders", "via": "has_orders", "hops": 1 },
{ "agent": "profiles", "via": "has_profile", "hops": 1 },
{ "agent": "shipments", "via": "has_shipments", "hops": 2 }
]
}With depth=2, the traversal visits direct neighbours (1 hop) and their neighbours (2 hops). Increasing depth follows longer paths but may return a large result set on densely connected graphs.
nodes at the shortest hop distance.Record-level links
Edges can be scoped to specific records within agents by supplying from_record and to_record content hashes. This creates a link between individual records rather than between agents as a whole.
POST /v1/graph/edges
Authorization: Bearer spx_root_YOUR_ROOT_KEY
Content-Type: application/json
{
"from_agent": "users",
"to_agent": "orders",
"edge_type": "placed",
"from_record": "usr_hash_b3a7c2...",
"to_record": "order_hash_9d2e4f...",
"meta": {
"amount": 299.99
}
}| Field | Description |
|---|---|
from_record | Content hash of the source record within from_agent. |
to_record | Content hash of the target record within to_agent. |
Record-level links are stored in the same graph layer as agent-level edges. They appear in GET /v1/graph/edges responses alongside agent-level edges. Traversal at depth=1 from an agent returns all agents it has edges to, regardless of whether those edges are record-level or agent-level.
Worked example — company hierarchy
Model a three-level hierarchy: a company has departments, and departments have employees.
Step 1 — create the edges
POST /v1/graph/edges
{
"from_agent": "company",
"to_agent": "departments",
"edge_type": "has_departments"
}POST /v1/graph/edges
{
"from_agent": "departments",
"to_agent": "employees",
"edge_type": "has_employees"
}Step 2 — traverse from company at depth 2
GET /v1/graph/traverse?from=company&depth=2
{
"origin": "company",
"depth": 2,
"nodes": [
{ "agent": "departments", "via": "has_departments", "hops": 1 },
{ "agent": "employees", "via": "has_employees", "hops": 2 }
]
}Step 3 — link a specific employee to a specific department
POST /v1/graph/edges
{
"from_agent": "departments",
"to_agent": "employees",
"edge_type": "member",
"from_record": "dept_hash_e4a1b2...",
"to_record": "emp_hash_7f3c9d...",
"meta": { "joined": "2025-03-15" }
}API reference
| Method | Path | Action |
|---|---|---|
POST | /v1/graph/edges | Create an agent-level or record-level edge. |
GET | /v1/graph/edges?from=:agent | List all edges originating from an agent. |
GET | /v1/graph/edges?to=:agent | List all edges pointing to an agent. |
DELETE | /v1/graph/edges/:from/:to/:type | Delete a specific edge by from, to, and type. |
GET | /v1/graph/traverse?from=:agent&depth=:n | Breadth-first traversal from an agent up to depth n. |
POST/GET /v1/graph/edges and DELETE /v1/graph/edges/:src/:type/:dst require the root key or a scoped key holding admin:graph — distinct from the row-policy-filtered refs routes and from GET /v1/graph/traverse, which stay ordinary reads. Creating/deleting an edge directly reveals or changes structural links between agents platform-wide, so it's treated the same as other cluster-wide config, not a per-tenant read/write.