Restormel Connect API

Wire agents and apps to a workspace-scoped knowledge graph. After ingest builds your corpus, these endpoints serve retrieval and verification — the production layer between your documents and your AI products.

Public REST lives on restormel.dev under /connect/v1/*. Authenticate with a Gateway key (rk_…) and include a Keys workspace_id on every request body.

Endpoints

  • POST /connect/v1/verify — Connect Verify (@restormel/reasoning-core)
  • POST /connect/v1/retrieve — Connect Retrieve (@restormel/graphrag-core)
  • POST /connect/v1/graph — Graph orchestrator: higher-order retrieval (@restormel/graphrag-core)
  • POST /connect/v1/ingest/jobs — create ingest job (workspace-scoped persistence)
  • GET /connect/v1/ingest/jobs — list jobs for a workspace
  • GET /connect/v1/ingest/jobs/{jobId} — job status and stage progress
  • GET /connect/v1/traces/{traceId} — fetch a stored provenance trace
  • GET /connect/v1/traces/{traceId}/export?format=json — download a provenance trace as JSON

Graph orchestrator

POST /connect/v1/graph exposes the curated, "smart MCP not dumb pipe" operations: each returns a ranked, structured subgraph (or paths) with a compact audit trace — never raw rows. Pick the operation with the operation field:

  • retrieve_context — vector-seeded, graph-expanded context for a query (the primary entry point)
  • expand_context — graph expansion from explicit seed_node_ids (where graph-RAG beats vector-RAG)
  • find_relevant_subgraph — topic subgraph with reasoning_mode: semantic · causal · temporal (causal/temporal re-weight edge priors)
  • find_paths — ranked paths between source_node_id and target_node_id
  • summarise_subgraph — condense a retrieved subgraph under a max_tokens budget (dedup + salience prune, seeds preserved)

Trust by default: every operation accepts an optional verification_policy and defaults to supported-only (flagged claims excluded). Opt into weaker evidence explicitly with { "verification_policy": { "include": ["supported", "weak"] } }. The response trace.verification reports what was included and excluded, by trust category.

Pass max_tokens on any operation to fit your model's context window; trace.tokens_used and trace.nodes_dropped report the budgeting outcome.

Provenance traces

Every POST /connect/v1/retrieve and POST /connect/v1/graph query stores a full audit trace and returns its trace_id in the response. Fetch the structured document later with GET /connect/v1/traces/{traceId}, or download it with GET /connect/v1/traces/{traceId}/export?format=json (sets Content-Disposition so it saves as a file). Both take the same workspace_id (and optional project_id) query parameters and Gateway-key auth as the rest of Connect v1.

What a trace contains (schema_version 1.0, from @restormel/contracts/provenance-trace):

  • the query, domain_pack, graph_store_type, and the verification_policy actually applied;
  • seeds — the entry-point claims chosen by vector/lexical search;
  • expansion — the traversal band(s): depth, claims traversed, relations kept, edge types;
  • claims — a per-claim verdict for every claim considered: whether it was included, its verification_state/trust_score/confidence_score, its hop_depth and edge_path, and (when excluded) the exclusion_reason;
  • result — claims retrieved vs filtered, tokens used vs budget, whether the context was truncated;
  • timing — total wall-clock duration (sub-phase timings are reserved in 1.0).

Retention: traces are kept for 90 days, then pruned. Use them to debug why a claim was (or was not) returned, audit the trust filter on a specific answer, compare retrieval quality across queries, and — with restormel replay — deterministically reproduce an agent's retrieval. A trace owned by another workspace returns 404.

Contract

Request/response envelopes use CONNECT_API_CONTRACT_VERSION = 2026-06-01 from @restormel/contracts/connect. OpenAPI draft: openapi-suite-v1-draft.yaml.

MCP tools (BYO graph — hero path)

Configure a Bring-Your-Own SurrealDB graph store in the Connect hub first. Then wire agents with @restormel/mcp:

  • connect.search — semantic search → structured claims, relations, and pass-specific context_pack
  • connect.get_context_for — topic + optional seed_claim_id from Claims
  • connect.retrieve — deprecated alias of connect.search
  • connect.verify, connect.ingest.* — verify and ingest job helpers

Graph orchestrator tools (model-agnostic; map 1:1 to POST /connect/v1/graph) — curated, ranked, token-budgeted context for any agent host:

  • connect.graph.retrieve_context — primary retrieval (vector + graph), token-budgeted
  • connect.graph.expand_context — expand from explicit seed node ids, optional edge-type filter
  • connect.graph.find_relevant_subgraph — semantic / causal / temporal reasoning modes
  • connect.graph.find_paths — ranked paths between two nodes
  • connect.graph.summarise_subgraph — condense a subgraph under a token budget

Every graph tool defaults to supported-only retrieval (the trust promise, visible in each tool's schema) — set verification_policy.include to widen.

Env: RESTORMEL_CONNECT_API_BASE (e.g. https://restormel.dev), RESTORMEL_GATEWAY_KEY (rk_…), RESTORMEL_WORKSPACE_ID. HTTP mirror: POST /keys/dashboard/api/connect/invoke with { "tool": "connect.search", "payload": { … } }.

Restormel does not host your graph corpus in MVP — your Surreal endpoint must be reachable from hosted retrieve. See MCP integration guide.

Operator hub

Signed-in operators: /keys/dashboard/connect.

Related