TrustGraph WebSocket API 2.4

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

Authentication

The /api/v1/socket endpoint uses in-band authentication. The WebSocket handshake is accepted unconditionally. The client must authenticate by sending a bearer token as the first message after connecting. The gateway resolves the token to an authenticated identity and workspace.

All subsequent requests execute within the workspace context established by the authentication frame.

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-scoped services
  • request/response: Service-specific payload (identical to REST API schemas)
  • error: Error information on failure

Service Tiers

Global Services (no workspace scoping):

  • iam

Workspace-Scoped Services (workspace resolved from token):

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

Flow-Scoped Services (require flow parameter, workspace from token):

  • 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: Authorization
      • In: header

      Bearer token authentication. The /api/v1/socket endpoint uses in-band authentication: the WebSocket handshake is accepted unconditionally and the client sends a bearer token as the first frame after connecting. The token is an opaque string obtained via the IAM service.

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.