graph-management

name	graph-management
description	Inspect and mutate GraphOS graphs through HTTP APIs. Use when reading topology, validating node types/plugins, and applying atomic graph transactions with retries on partial success.
argument-hint	Describe your graph task, e.g. "add a node and connect it to n2 in graph main"
user-invocable	true

GraphOS Skill: graph-management

AI-operable protocol for reading and mutating GraphOS graphs through HTTP-first APIs.

When to Use

• Inspect graph structure, node relations, and selected-node context.
• Validate available node types before write operations.
• Check plugin runtime status when type schemas appear missing.
• Apply coherent mutation batches with transaction-like behavior.

Runtime Base URL

Default local runtime:

• http://localhost:3411

If your environment uses a different host or port, replace the base URL accordingly.

API Reference

get_graph_description

Get a full graph snapshot for planning and verification.

• Method: GET
• Path: /api/graph/description
• Query:
  • graphId?: string
• Success response includes:
  • graph: id, name, nodeCount, edgeCount, rootNodeIds, leafNodeIds, selectedNodeId
  • nodes: AI-friendly node descriptions
  • edges: edge list with edge ids
  • adjacency: parent/child ids per node
  • aiSummary: natural language summary
• Typical errors:
  • 404 if graph is not found

get_graph_node

Get one focus node and its local context (parents and children).

• Method: GET
• Path: /api/graph/node
• Query:
  • graphId?: string
  • nodeId?: string
• Behavior:
  • if nodeId is omitted, server falls back to the graph synced selected node
• Success response includes:
  • graph: id, name, selectedNodeId
  • selectedNode
  • parentNodes
  • childNodes
  • aiSummary: focus metadata + naturalLanguage
• Typical errors:
  • 400 if nodeId missing and no synced selected node exists
  • 404 if graph or node does not exist

get_available_node_types

List node type schemas registered by plugins.

• Method: GET
• Path: /api/node-types
• Query: none
• Success response:
  • array of node type definitions (type, description, properties, inTypes, outTypes)

get_plugins

List plugin runtime status.

• Method: GET
• Path: /api/plugins
• Query: none
• Success response:
  • array of plugin status objects:
    • name
    • status
    • error
    • nodeTypeCount

apply_graph_transaction

Apply a batch of graph operations atomically from the caller perspective.

• Method: POST
• Path: /api/graph/apply
• Body:
  • graphId?: string
  • ops: Operation[]

Operation schema:

• CREATE_NODE
  • metadata: { id, type, position: { x, y }, data? }
• UPDATE_NODE
  • metadata: { id, data }
• DELETE_NODE
  • metadata: { id }
• CONNECT
  • metadata: { id, source, target, sourceHandle?, targetHandle? }
• DISCONNECT
  • metadata: { id }

Notes:

• node validation runs against registered node type schema
• CONNECT requires source and target nodes to exist
• duplicate node ids and duplicate edges are rejected
• DISCONNECT uses edge id, typically edge_

Success response includes:

• success, appliedCount, errorCount
• applied: string[]
• errors: { op, index, reason }[]
• updated graph, nodes, edges
• aiSummary

Procedure

Step 1: Read Constraints and Current State

1. Call get_available_node_types to learn schema constraints.
2. Call get_graph_description to capture full topology.
3. If operating on one node area, call get_graph_node for local context.

Completion check:

• Required node types are present.
• You know exact source/target ids and expected deltas.

Step 2: Plan the Transaction

1. Build one coherent apply_graph_transaction request with all related ops.
2. Order ops so dependencies are valid (create before connect, disconnect before delete).
3. Keep ids stable and deterministic for repeatable retries.

Decision points:

• If a node type is missing, inspect get_plugins before retrying writes.
• If editing risks data loss, narrow ops to intended scope only.

Completion check:

• Transaction has all required ops and no redundant mutations.

Step 3: Apply and Verify

1. Submit apply_graph_transaction.
2. Inspect applied and errors from response.
3. Re-run get_graph_description to verify post-state.

Decision points:

• If partial success occurs, retry only failed intent instead of replaying the full batch.
• If validation errors occur, patch payloads to match node schema before retry.

Completion check:

• Graph topology matches expected post-change state.
• No unresolved critical errors remain.

Safety Rules

• Prefer one coherent transaction over many micro calls.
• Validate node property payloads against node type requirements before submit.
• For destructive updates, inspect current graph first and include only intended operations.
• Treat partial success as normal: check errors and retry only failed intent.

Request Examples

Example: Read graph

GET /api/graph/description?graphId=main

Example: Apply transaction

POST /api/graph/apply Content-Type: application/json

{ "graphId": "main", "ops": [ { "op": "CREATE_NODE", "metadata": { "id": "n_fetch", "type": "http.request", "position": { "x": 120, "y": 80 }, "data": { "properties": { "url": "https://example.com" } } } }, { "op": "CONNECT", "metadata": { "id": "edge_manual_n_fetch_n2", "source": "n_fetch", "target": "n2" } } ] }