Graph Traversal

Overview

Beyond the Argo DSL, Arke provides direct graph traversal endpoints powered by Neo4j (via the GraphDB service binding). Entities and their relationships are synced to a graph database for efficient path-finding and traversal.

Graph Endpoints

Endpoint	Method	Purpose
`/graph/paths`	POST	Find shortest paths between entity sets
`/graph/reachable`	POST	Find entities of a type reachable from sources
`/graph/entity/{id}`	GET	Get entity with all relationships from graph

Find Paths Between Entities

Find all shortest paths between source and target entity sets:

POST /graph/paths
Content-Type: application/json
Authorization: Bearer <token>

{
  "source_pis": ["01KE4ZY69F9R40E88PK9S0TQRQ"],
  "target_pis": ["01KE506KZGD8M2P1XK3VNQT4YR"],
  "max_depth": 3,
  "direction": "both",
  "limit": 10
}

Request Parameters

Parameter	Type	Default	Description
`source_pis`	string[]	required	Starting entity PIs
`target_pis`	string[]	required	Target entity PIs
`max_depth`	number	4	Maximum path depth (1-4)
`direction`	string	"both"	`"outgoing"`, `"incoming"`, or `"both"`
`limit`	number	100	Maximum paths to return (max 1000)

Response

{
  "paths": [
    {
      "source_pi": "01KE4ZY...",
      "target_pi": "01KE506...",
      "length": 2,
      "edges": [
        {
          "subject_pi": "01KE4ZY...",
          "subject_label": "Project Folder",
          "subject_type": "folder",
          "predicate": "contains",
          "object_pi": "01KE506...",
          "object_label": "Research Paper.pdf",
          "object_type": "file"
        }
      ]
    }
  ],
  "truncated": false
}

Find Reachable Entities

Find all entities of a specific type reachable from source entities:

POST /graph/reachable
Content-Type: application/json
Authorization: Bearer <token>

{
  "source_pis": ["01KE4ZY69F9R40E88PK9S0TQRQ"],
  "target_type": "file",
  "max_depth": 3,
  "direction": "outgoing",
  "limit": 50
}

Request Parameters

Parameter	Type	Default	Description
`source_pis`	string[]	required	Starting entity PIs
`target_type`	string	required	Target entity type to find
`max_depth`	number	4	Maximum path depth (1-4)
`direction`	string	"both"	`"outgoing"`, `"incoming"`, or `"both"`
`limit`	number	100	Maximum results (max 1000)

Response

{
  "results": [
    {
      "source_pi": "01KE4ZY...",
      "target_pi": "01KE506...",
      "target_label": "Research Paper.pdf",
      "target_type": "file",
      "length": 1,
      "edges": [...]
    }
  ],
  "truncated": false
}

Get Entity with Relationships

Get entity details with all relationships from the graph:

GET /graph/entity/01KE4ZY69F9R40E88PK9S0TQRQ
Authorization: Bearer <token>

Unlike the entity manifest endpoint, this includes both outgoing AND incoming relationships -- showing not just what this entity links to, but also what links to it.

Response

{
  "pi": "01KE4ZY...",
  "type": "folder",
  "label": "Project Folder",
  "collection_pi": "01JCOLL...",
  "created_at": "2025-01-10T08:00:00.000Z",
  "updated_at": "2025-01-18T16:45:00.000Z",
  "relationships": [
    {
      "direction": "outgoing",
      "predicate": "contains",
      "peer_pi": "01KE506...",
      "peer_type": "file",
      "peer_label": "Research Paper.pdf",
      "properties": {}
    },
    {
      "direction": "incoming",
      "predicate": "contains",
      "peer_pi": "01KPARENT...",
      "peer_type": "folder",
      "peer_label": "Root Folder",
      "properties": {}
    }
  ]
}

Entity Expansion

All graph endpoints support the expand query parameter to fetch fresh entity data:

Value	Description
(omitted) or `preview`	Lightweight previews for path entities
`full`	Complete entity manifests
`none`	Graph metadata only (fastest)

Example:

GET /graph/entity/01KE4ZY...?expand=preview
POST /graph/paths?expand=full

With expansion, edges include additional fields:

subject_preview / subject_entity for the source
object_preview / object_entity for the target
peer_preview / peer_entity for relationships

Performance Note: 100 paths can reference 400-800 unique entities. Use limit: 10-20 when using expansion, or use expand=none for large result sets and fetch specific entities separately.

When to Use Graph vs Argo vs Search

Use Case	Recommended Endpoint
Semantic search + graph traversal with ranking	`POST /query` (Argo DSL)
Exhaustive exploration from known entities	`POST /graph/reachable`
Find all paths between two entity sets	`POST /graph/paths`
Get all relationships for one entity	`GET /graph/entity/{id}`
Find entities by text similarity	`POST /search/*` endpoints

On this page