Introduction

A graph session object is a mutable property graph of vertices and edges. The envelope marks the object as a graph and holds optional metadata about it; elements themselves live in a separate element store managed by dedicated commands.

Envelope

Upload a graph envelope with upload_session_object, setting value.type to "graph":

{
  "type": "graph",
  "graph": {
    "attributes": {
      "id": "uuid-for-tracking",
      "created_at": "2026-06-06T10:00:00.000000+00:00",
      "name": "Task dependency graph",
      "description": "..."
    },
    "metadata": {}
  }
}

The graph object inside value carries two optional sub-fields:

Field	Type	Description
`attributes`	object	Optional named metadata: `id`, `created_at`, `name`, `description`.
`metadata`	object	Optional arbitrary JSON.

The envelope is read back as-is via download_session_object. No elements are included in that response — elements are fetched exclusively through the graph commands.

Element Model

The graph stores two kinds of elements: vertices and edges.

Vertex Fields

Field	Type	Description
`element_id`	string	Graph-scoped unique id. May be client-supplied or server-generated.
`type`	string	Always `"vertex"`.
`labels`	array of string	Label set assigned at creation. Labels are immutable after `add_vertex`.
`props`	object	Arbitrary key/value properties. Mutable via `set_vertex_props` / `remove_vertex_props`.
`rev`	integer	Optimistic-concurrency revision counter. Increments on every mutation.
`created_at`	string	ISO 8601 timestamp set at creation.
`updated_at`	string	ISO 8601 timestamp of the last mutation.
`user_id`	string	Id of the user who last mutated this element.

Edge Fields

Field	Type	Description
`element_id`	string	Graph-scoped unique id. May be client-supplied or server-generated.
`type`	string	Always `"edge"`.
`label`	string	Single edge label (type). Set at `add_edge` and immutable thereafter.
`from_id`	string	`element_id` of the source vertex.
`to_id`	string	`element_id` of the target vertex.
`props`	object	Arbitrary key/value properties. Mutable via `set_edge_props` / `remove_edge_props`.
`rev`	integer	Optimistic-concurrency revision counter. Increments on every mutation.
`created_at`	string	ISO 8601 timestamp set at creation.
`updated_at`	string	ISO 8601 timestamp of the last mutation.
`user_id`	string	Id of the user who last mutated this element.

Mutations

All writes go through apply_session_graph_mutations, which accepts an ordered list of operations applied atomically. A single call may contain at most 100 operations (subject to a server-enforced action budget).

`op`	Required fields	Description
`add_vertex`	`labels` (non-empty)	Create a new vertex. `labels` is required at creation and immutable afterward; `element_id` may be client-supplied.
`add_edge`	`label`, `from_id`, `to_id`	Create a new directed edge between two existing vertices.
`set_vertex_props`	`element_id`, `props`	Merge `props` into the existing vertex (shallow set; does not remove unmentioned keys).
`set_edge_props`	`element_id`, `props`	Merge `props` into the existing edge.
`remove_vertex_props`	`element_id`, `keys`	Remove the specified property keys from the vertex.
`remove_edge_props`	`element_id`, `keys`	Remove the specified property keys from the edge.
`delete_vertex`	`element_id`	Delete a vertex and all of its incident edges (cascade).
`delete_edge`	`element_id`	Delete a single edge.

Optional field available on all mutation ops:

Field	Type	Description
`if_rev`	integer	If present, the server verifies the element’s current `rev` matches before applying the op.

Optimistic Concurrency

Each element carries a rev integer that increments on every successful mutation. To guard against lost updates in concurrent environments, pass if_rev with the last-known rev of the element. If the stored rev no longer matches, the entire batch is rejected with a graph_mutation_conflict (HTTP 409) error and nothing is written.

{
  "op": "set_vertex_props",
  "element_id": "task:1",
  "if_rev": 3,
  "props": { "status": "done" }
}

Operations

Operation	Description
Apply Session Graph Mutations	Atomically apply a batch of create/update/delete operations.
Query Session Graph	Traverse the graph with a structured query AST.
List Session Graph Elements	Paginate all elements; supports `updated_since` for incremental syncs.
List Session Graph Neighbors	Fetch edges and neighbor vertices for a set of seed vertex ids.
Get Session Graph Element	Fetch a single element by `element_id`.
Get Session Graph Elements	Batch-fetch multiple elements by `element_id`.

All commands require the alias of the graph envelope. If the envelope does not exist or its value.type is not "graph", the server returns invalid_graph_envelope.

Events

After each apply_session_graph_mutations call the server emits a session_graph_changed event carrying the change delta:

{
  "type": "session_graph_changed",
  "session_object": {
    "alias": "task_graph",
    "changes": [
      { "op": "upsert", "element_id": "task:1", "type": "vertex", "rev": 4 },
      { "op": "delete", "element_id": "e:7",    "type": "edge" }
    ]
  }
}

Each entry in changes describes one logical effect of the batch:

`op`	Meaning
`upsert`	The element was created or updated. Fetch its new state via `get_session_graph_elements`.
`delete`	The element was deleted. Remove it from any local cache.

The recommended client sync pattern is: apply delete entries locally, then call get_session_graph_elements with the element_id values from upsert entries to fetch their updated state. For a full resync, use list_session_graph_elements with updated_since.

Overview

Workflow

Scheduler

ONNX

Envelope

Element Model

Vertex Fields

Edge Fields

Mutations

Optimistic Concurrency

Operations

Events

See also

​Envelope

​Element Model

​Vertex Fields

​Edge Fields

​Mutations

​Optimistic Concurrency

​Operations

​Events

​See also

Envelope

Element Model

Vertex Fields

Edge Fields

Mutations

Optimistic Concurrency

Operations

Events

See also