TrustGraph WebSocket API 2.2

WebSocket API for TrustGraph - providing multiplexed, asynchronous access to all services.

Overview

The WebSocket API provides access to all TrustGraph services over a single persistent connection:

  • Multiplexed: Multiple concurrent requests with ID-based correlation
  • Asynchronous: Non-blocking request/response pattern
  • Efficient: Lower overhead than HTTP REST
  • Streaming: Real-time progressive responses

Protocol Summary

All messages are JSON with:

  • id: Client-generated unique identifier for request/response correlation
  • service: Service identifier (e.g., "config", "agent", "document-rag")
  • flow: Optional flow ID for flow-hosted services
  • request/response: Service-specific payload (identical to REST API schemas)
  • error: Error information on failure

Service Types

Global Services (no flow parameter):

  • config, flow, librarian, knowledge, collection-management

Flow-Hosted Services (require flow parameter):

  • agent, text-completion, prompt, document-rag, graph-rag
  • embeddings, graph-embeddings, document-embeddings
  • triples, rows, nlp-query, structured-query, sparql-query, structured-diag, row-embeddings
  • text-load, document-load, mcp-tool

Schema Reuse

Request and response payloads use identical schemas to the REST API. See OpenAPI specification for detailed schema documentation.

Servers

  • ws://localhost:8088/wsproduction

    Local development WebSocket server

    Security:
    • HTTP API key
      • Name: token
      • In: query

      Bearer token authentication when GATEWAY_SECRET is configured. Include as query parameter: ws://localhost:8088/api/v1/socket?token=

Messages

  • #1Service Request Message

    Request message for any TrustGraph service

    Message IDServiceRequest

    Generic request message that can invoke any TrustGraph service.

    The request field payload varies by service and matches the REST API request body schema.

    oneOf

    Service request envelope with id, service, optional flow, and service-specific request payload

  • #2Service Response Message

    Successful response from any TrustGraph service

    Message IDServiceResponse

    Generic response message from any TrustGraph service.

    The response field payload varies by service and matches the REST API response body schema.

    For streaming services, multiple messages with the same id may be sent.

    object

    WebSocket response message envelope for successful responses.

    Contains the request ID for correlation and the service-specific response payload.

  • #3Service Error Message

    Error response from any TrustGraph service

    Message IDServiceError

    Error message sent when a service request fails.

    Contains the request ID and error details.

    object

    WebSocket error message envelope.

    Sent when a request fails. Contains the request ID and error details.

Schemas

  • object

    WebSocket request message envelope.

    Wraps service-specific request payloads with routing and correlation metadata.

  • object

    WebSocket response message envelope for successful responses.

    Contains the request ID for correlation and the service-specific response payload.

  • object

    WebSocket error message envelope.

    Sent when a request fails. Contains the request ID and error details.