Apply Session Graph Mutations

Apply a batch of mutations to a graph session object.

POST `/revisions/:id/data/command` (Command: `apply_session_graph_mutations`)

Mutations are applied atomically in the order listed. Optimistic concurrency is supported per element via if_rev.

Request Body

Parameter	Type	Required	Description
`engine`	string	Yes	Must be `workflow_blobhub`.
`command`	string	Yes	Must be `apply_session_graph_mutations`.
`session_id`	string	Yes	The ID of the session that owns the graph envelope.
`alias`	string	Yes	Alias of the graph session object.
`operations`	array of object	Yes	Ordered list of mutation operations. See operation types below.

Mutation Operation Types

Each entry in operations is an object with an op discriminator and op-specific fields:

`op`	Required fields	Optional fields	Description
`add_vertex`	`labels` (non-empty)	`element_id`, `props`, `if_rev`	Create a new vertex. `labels` is required and must contain at least one label (labels are immutable afterward). `element_id` defaults to a server-generated id; `props` defaults to `{}`.
`add_edge`	`label` (string), `from_id`, `to_id`	`element_id`, `props`, `if_rev`	Create a new directed edge. `label` is the relationship type and is required.
`set_vertex_props`	`element_id`, `props` (object)	`if_rev`	Merge `props` into an existing vertex (shallow merge — keys are added/replaced).
`set_edge_props`	`element_id`, `props` (object)	`if_rev`	Merge `props` into an existing edge.
`remove_vertex_props`	`element_id`, `keys` (string[])	`if_rev`	Remove the listed prop keys from an existing vertex.
`remove_edge_props`	`element_id`, `keys` (string[])	`if_rev`	Remove the listed prop keys from an existing edge.
`delete_vertex`	`element_id`	`if_rev`	Delete a vertex. Also cascades — all incident edges are removed atomically.
`delete_edge`	`element_id`	`if_rev`	Delete a single edge.

add_vertex requires a non-empty labels list. Labels are set only at creation and are immutable afterward, so there are no label-mutation operations (set_labels, add_labels, remove_labels do not exist). Every operation may optionally include if_rev (integer). If present, the server checks that the current rev of the element matches if_rev before applying the operation. A mismatch aborts the entire batch and returns graph_mutation_conflict (409).

Response

Parameter	Type	Description
`elements`	array of object	The current state of every upserted element in this batch (deleted elements are not included).
`changes`	array of object	Change records — one per affected element. Each entry has `op` (`"upsert"` or `"delete"`), `element_id`, and `type`. `rev` is included for `upsert` entries.

Errors

invalid_graph_envelope — the alias does not exist or its value.type is not "graph".
invalid_vertex_labels — an add_vertex op omitted labels or supplied only empty/whitespace labels; a vertex must be created with at least one non-empty label.
graph_element_too_large — a single element’s serialized props exceed the server-side size cap.
graph_mutation_too_large — the total serialized size of the mutation batch exceeds the cap.
graph_mutation_conflict (409) — an if_rev check failed; the batch was not applied.

Example

{
  "engine": "workflow_blobhub",
  "command": "apply_session_graph_mutations",
  "session_id": "sess_001",
  "alias": "task_graph",
  "operations": [
    {
      "op": "add_vertex",
      "element_id": "task:1",
      "labels": ["task"],
      "props": { "title": "Research", "status": "open" }
    },
    {
      "op": "add_vertex",
      "element_id": "task:2",
      "labels": ["task"],
      "props": { "title": "Write report", "status": "open" }
    },
    {
      "op": "add_edge",
      "element_id": "e:1",
      "label": "depends_on",
      "from_id": "task:2",
      "to_id": "task:1",
      "props": {}
    },
    {
      "op": "set_vertex_props",
      "element_id": "task:1",
      "if_rev": 1,
      "props": { "status": "in_progress" }
    }
  ]
}

{
  "elements": [
    {
      "element_id": "task:1",
      "type": "vertex",
      "labels": ["task"],
      "props": { "title": "Research", "status": "in_progress" },
      "rev": 2,
      "created_at": "2026-06-06T10:00:00.000000+00:00",
      "updated_at": "2026-06-06T10:00:01.000000+00:00",
      "user_id": "usr_001"
    },
    {
      "element_id": "task:2",
      "type": "vertex",
      "labels": ["task"],
      "props": { "title": "Write report", "status": "open" },
      "rev": 1,
      "created_at": "2026-06-06T10:00:00.000000+00:00",
      "updated_at": "2026-06-06T10:00:00.000000+00:00",
      "user_id": "usr_001"
    },
    {
      "element_id": "e:1",
      "type": "edge",
      "label": "depends_on",
      "from_id": "task:2",
      "to_id": "task:1",
      "props": {},
      "rev": 1,
      "created_at": "2026-06-06T10:00:00.000000+00:00",
      "updated_at": "2026-06-06T10:00:00.000000+00:00",
      "user_id": "usr_001"
    }
  ],
  "changes": [
    { "op": "upsert", "element_id": "task:1", "type": "vertex", "rev": 1 },
    { "op": "upsert", "element_id": "task:2", "type": "vertex", "rev": 1 },
    { "op": "upsert", "element_id": "e:1",    "type": "edge",   "rev": 1 },
    { "op": "upsert", "element_id": "task:1", "type": "vertex", "rev": 2 }
  ]
}

Overview

Workflow

Scheduler

ONNX

Apply Session Graph Mutations

POST `/revisions/:id/data/command` (Command: `apply_session_graph_mutations`)

Request Body

Mutation Operation Types

Response

Errors

Example

See also

​POST /revisions/:id/data/command (Command: apply_session_graph_mutations)

​Request Body

​Mutation Operation Types

​Response

​Errors

​Example

​See also

POST `/revisions/:id/data/command` (Command: `apply_session_graph_mutations`)

Request Body

Mutation Operation Types

Response

Errors

Example

See also