TrustGraph WebSocket API 1.8 documentation

TrustGraph WebSocket API 1.8

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, objects, nlp-query, structured-query, structured-diag
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 MessageServiceRequest
Request message for any TrustGraph service
- application/json
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

object
WebSocket request for config service (global service)

Examples values:
{"id":"req-1","service":"config","request":{"operation":"list","type":"flow"}}
{"id":"req-2","service":"config","request":{"operation":"get","keys":[{"type":"flow","key":"my-flow"}]}}
id
required
string
Unique request identifier

service
required
string
Service identifier for config service

Const:"config"
required
object
Configuration service request.

Supports operations: config, list, get, put, delete

operation
required
string
Operation to perform:

config: Get complete configuration

list: List all items of a specific type

get: Get specific configuration items

put: Set/update configuration values

delete: Delete configuration items

Allowed values:
"config"
"list"
"get"
"put"
"delete"
type
string
Configuration type (required for list, get, put, delete operations). Common types: flow, prompt, token-cost, parameter-type, interface-description

array<object>
Keys to retrieve (for get operation) or delete (for delete operation)

object
type
required
string
Configuration type

key
required
string
Configuration key

Additional properties are allowed.
array<object>
Values to set/update (for put operation)

object
type
required
string
Configuration type

key
required
string
Configuration key

required
object
Configuration value (structure depends on type)

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for flow service (global service)

Examples values:
{"id":"req-1","service":"flow","request":{"operation":"list"}}
{"id":"req-2","service":"flow","request":{"operation":"start","flow":"my-flow","blueprint":"default-blueprint"}}
id
required
string
Unique request identifier

service
required
string
Service identifier for flow service

Const:"flow"
required
object
Flow service request for managing flow instances and blueprints.

Operations: start-flow, stop-flow, list-flows, get-flow, list-blueprints, get-blueprint, put-blueprint, delete-blueprint

operation
required
string
Flow operation:

start-flow: Start a new flow instance from a blueprint

stop-flow: Stop a running flow instance

list-flows: List all running flow instances

get-flow: Get details of a running flow

list-blueprints: List available flow blueprints

get-blueprint: Get blueprint definition

put-blueprint: Create/update blueprint definition

delete-blueprint: Delete blueprint definition

Allowed values:
"start-flow"
"stop-flow"
"list-flows"
"get-flow"
"list-blueprints"
"get-blueprint"
"put-blueprint"
"delete-blueprint"
flow-id
string
Flow instance ID (required for start-flow, stop-flow, get-flow)

blueprint-name
string
Flow blueprint name (required for start-flow, get-blueprint, put-blueprint, delete-blueprint)

object
Flow blueprint definition (required for put-blueprint)

Additional properties are allowed.
description
string
Flow description (optional for start-flow)

object
Flow parameters (for start-flow). All values are stored as strings, regardless of input type.

Additional properties:
string
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for librarian service (global service)

Examples values:
{"id":"req-1","service":"librarian","request":{"operation":"list","collection":"default"}}
id
required
string
Unique request identifier

service
required
string
Service identifier for librarian service

Const:"librarian"
required
object
Librarian service request for document library management.

Operations: add-document, remove-document, list-documents, start-processing, stop-processing, list-processing

operation
required
string
Library operation:

add-document: Add document to library

remove-document: Remove document from library

list-documents: List documents in library

start-processing: Start processing library documents

stop-processing: Stop library processing

list-processing: List processing status

Allowed values:
"add-document"
"remove-document"
"list-documents"
"start-processing"
"stop-processing"
"list-processing"
flow
string
Flow ID

collection
string
Collection identifier

Default value:"default"
user
string
User identifier

Default value:"trustgraph"
document-id
string
Document identifier

processing-id
string
Processing task identifier

object
Document metadata for library management

url
string
Document URL or identifier

title
string
Document title

author
string
Document author

date
string
Document date

object
Additional metadata fields

Additional properties are allowed.
Additional properties are allowed.
object
Processing metadata for library document processing

flow
string
Flow ID

collection
string
Collection identifier

status
string
Processing status

Allowed values:
"pending"
"processing"
"completed"
"failed"
timestamp
string
format: date-time
Processing timestamp

error
string
Error message if processing failed

Additional properties are allowed.
content
string
Document content (for add-document with inline content)

array<object>
Search criteria for filtering documents

object
key
required
string
Metadata field name

value
required
string
Value to match

operator
required
string
Comparison operator

Allowed values:
"eq"
"ne"
"gt"
"lt"
"contains"
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for knowledge service (global service)

Examples values:
{"id":"req-1","service":"knowledge","request":{"operation":"store","triples":[{"s":{"v":"https://example.com/entity1","e":true},"p":{"v":"https://example.com/relates-to","e":true},"o":{"v":"https://example.com/entity2","e":true}}]}}
id
required
string
Unique request identifier

service
required
string
Service identifier for knowledge service

Const:"knowledge"
required
object
Knowledge graph core management request.

Operations: list-kg-cores, get-kg-core, put-kg-core, delete-kg-core, load-kg-core, unload-kg-core

operation
required
string
Knowledge core operation:

list-kg-cores: List knowledge cores for user

get-kg-core: Get knowledge core by ID

put-kg-core: Store triples and/or embeddings

delete-kg-core: Delete knowledge core by ID

load-kg-core: Load knowledge core into flow

unload-kg-core: Unload knowledge core from flow

Allowed values:
"list-kg-cores"
"get-kg-core"
"put-kg-core"
"delete-kg-core"
"load-kg-core"
"unload-kg-core"
user
string
User identifier (for list-kg-cores, put-kg-core, delete-kg-core)

Default value:"trustgraph"
id
string
Knowledge core ID (for get, put, delete, load, unload)

flow
string
Flow ID (for load-kg-core)

collection
string
Collection identifier (for load-kg-core)

Default value:"default"
object
Triples to store (for put-kg-core)

required
object
id
required
string
Knowledge core ID

user
required
string
User identifier

collection
required
string
Collection identifier

array<object>
Metadata triples

object
RDF triple (subject-predicate-object)

required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
required
array<object>
Knowledge triples

object
RDF triple (subject-predicate-object)

required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
Graph embeddings to store (for put-kg-core)

required
object
id
required
string
Knowledge core ID

user
required
string
User identifier

collection
required
string
Collection identifier

array<object>
Metadata triples

object
RDF triple (subject-predicate-object)

required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
required
array<object>
Entity embeddings

object
required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
required
array<number>
Embedding vectors

Items:
number
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for collection-management service (global service)

Examples values:
{"id":"req-1","service":"collection-management","request":{"operation":"list"}}
id
required
string
Unique request identifier

service
required
string
Service identifier for collection-management service

Const:"collection-management"
required
object
Collection management request.

Operations: list-collections, update-collection, delete-collection

operation
required
string
Collection operation:

list-collections: List collections for user

update-collection: Create or update collection metadata

delete-collection: Delete collection

Allowed values:
"list-collections"
"update-collection"
"delete-collection"
user
string
User identifier

Default value:"trustgraph"
collection
string
Collection identifier (for update, delete)

timestamp
string
format: date-time
ISO timestamp

name
string
Human-readable collection name (for update)

description
string
Collection description (for update)

array<string>
Collection tags for organization (for update)

Items:
string
array<string>
Filter collections by tags (for list)

Items:
string
limit
integer
Maximum number of results (for list)

Default value:0
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for agent service (flow-hosted service)

Examples values:
{"id":"req-1","service":"agent","flow":"my-flow","request":{"question":"What is quantum computing?","streaming":true,"system-prompt":"You are a helpful assistant"}}
id
required
string
Unique request identifier

service
required
string
Service identifier for agent service

Const:"agent"
flow
required
string
Flow ID

required
object
Agent service request - conversational AI agent that can reason and take actions.

question
required
string
User question or prompt for the agent

state
string
Agent state for continuation (optional, for multi-turn)

array<string>
Group identifiers for collaborative agents (optional)

Items:
string
array<object>
Conversation history (optional, list of previous agent steps)

object
thought
string
Agent's reasoning

action
string
Action taken

object
Action arguments

Additional properties:
string
observation
string
Result of the action

user
string
User context for this step

Additional properties are allowed.
user
string
User identifier for multi-tenancy

Default value:"trustgraph"
streaming
boolean
Enable streaming response delivery

Default value:false
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for document-rag service (flow-hosted service)

Examples values:
{"id":"req-1","service":"document-rag","flow":"my-flow","request":{"query":"What are the main features?","streaming":true,"doc-limit":20}}
id
required
string
Unique request identifier

service
required
string
Service identifier for document-rag service

Const:"document-rag"
flow
required
string
Flow ID

required
object
Document RAG (Retrieval-Augmented Generation) query request. Searches document embeddings and generates answer using retrieved context.

query
required
string
User query or question

user
string
User identifier for multi-tenancy

Default value:"trustgraph"
collection
string
Collection to search within

Default value:"default"
doc-limit
integer
[ 1 .. 100 ]
Maximum number of documents to retrieve

Default value:20
streaming
boolean
Enable streaming response delivery

Default value:false
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for graph-rag service (flow-hosted service)

Examples values:
{"id":"req-1","service":"graph-rag","flow":"my-flow","request":{"query":"What entities are related to quantum computing?","streaming":true,"triple-limit":100}}
id
required
string
Unique request identifier

service
required
string
Service identifier for graph-rag service

Const:"graph-rag"
flow
required
string
Flow ID

required
object
Graph RAG (Retrieval-Augmented Generation) query request. Searches knowledge graph and generates answer using retrieved subgraph.

query
required
string
User query or question

user
string
User identifier for multi-tenancy

Default value:"trustgraph"
collection
string
Collection to search within

Default value:"default"
entity-limit
integer
[ 1 .. 200 ]
Maximum number of entities to retrieve

Default value:50
triple-limit
integer
[ 1 .. 100 ]
Maximum number of triples to retrieve per entity

Default value:30
max-subgraph-size
integer
[ 10 .. 5000 ]
Maximum total subgraph size (triples)

Default value:1000
max-path-length
integer
[ 1 .. 5 ]
Maximum path length for graph traversal

Default value:2
streaming
boolean
Enable streaming response delivery

Default value:false
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for text-completion service (flow-hosted service)

Examples values:
{"id":"req-1","service":"text-completion","flow":"my-flow","request":{"prompt":"Once upon a time","streaming":true,"max-output-tokens":100}}
id
required
string
Unique request identifier

service
required
string
Service identifier for text-completion service

Const:"text-completion"
flow
required
string
Flow ID

required
object
Text completion request - direct LLM completion without RAG.

system
required
string
System prompt that sets behavior and context for the LLM

prompt
required
string
User prompt or question

streaming
boolean
Enable streaming response delivery

Default value:false
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for prompt service (flow-hosted service)

Examples values:
{"id":"req-1","service":"prompt","flow":"my-flow","request":{"template":"default-template","variables":{"topic":"quantum computing","style":"technical"}}}
id
required
string
Unique request identifier

service
required
string
Service identifier for prompt service

Const:"prompt"
flow
required
string
Flow ID

required
object
Prompt service request - template-based text generation.

Execute a stored prompt template with variable substitution.

id
required
string
Prompt template ID (stored in config)

object
Template variables as key-value pairs (values are JSON strings)

Additional properties:
string
object
Alternative to terms - variables as native JSON values (auto-converted)

Additional properties:
any
streaming
boolean
Enable streaming response delivery

Default value:false
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for embeddings service (flow-hosted service)

Examples values:
{"id":"req-1","service":"embeddings","flow":"my-flow","request":{"text":"What is quantum computing?"}}
id
required
string
Unique request identifier

service
required
string
Service identifier for embeddings service

Const:"embeddings"
flow
required
string
Flow ID

required
object
Embeddings request - convert text to vector embedding.

text
required
string
Text to convert to embedding vector

Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for mcp-tool service (flow-hosted service)

Examples values:
{"id":"req-1","service":"mcp-tool","flow":"my-flow","request":{"tool":"calculator","arguments":{"operation":"add","a":5,"b":3}}}
id
required
string
Unique request identifier

service
required
string
Service identifier for mcp-tool service

Const:"mcp-tool"
flow
required
string
Flow ID

required
object
MCP tool request - execute Model Context Protocol tool.

name
required
string
Tool name to execute

object
Tool parameters (JSON object, auto-converted to string internally)

Additional properties:
any
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for triples service (flow-hosted service)

Examples values:
{"id":"req-1","service":"triples","flow":"my-flow","request":{"s":{"v":"https://example.com/entity1","e":true},"limit":100}}
id
required
string
Unique request identifier

service
required
string
Service identifier for triples service

Const:"triples"
flow
required
string
Flow ID

required
object
Triples query request - query knowledge graph by subject/predicate/object pattern.

object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
limit
integer
[ 1 .. 100000 ]
Maximum number of triples to return

Default value:10000
user
string
User identifier

Default value:"trustgraph"
collection
string
Collection to query

Default value:"default"
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for objects service (flow-hosted service)

Examples values:
{"id":"req-1","service":"objects","flow":"my-flow","request":{"query":"{ entity(id: \"https://example.com/entity1\") { properties { key value } } }"}}
id
required
string
Unique request identifier

service
required
string
Service identifier for objects service

Const:"objects"
flow
required
string
Flow ID

required
object
Objects query request - GraphQL query over knowledge graph.

query
required
string
GraphQL query string

object
GraphQL query variables

Additional properties:
string
operation-name
string
Operation name (for multi-operation documents)

user
string
User identifier

Default value:"trustgraph"
collection
string
Collection to query

Default value:"default"
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for nlp-query service (flow-hosted service)

Examples values:
{"id":"req-1","service":"nlp-query","flow":"my-flow","request":{"query":"Show me all entities related to quantum computing","limit":50}}
id
required
string
Unique request identifier

service
required
string
Service identifier for nlp-query service

Const:"nlp-query"
flow
required
string
Flow ID

required
object
NLP query request - convert natural language question to structured query.

question
required
string
Natural language question

max-results
integer
[ 1 .. 10000 ]
Maximum results to return when query is executed

Default value:100
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for structured-query service (flow-hosted service)

Examples values:
{"id":"req-1","service":"structured-query","flow":"my-flow","request":{"query":{"type":"entity","filters":[{"property":"type","value":"Person"}]}}}
id
required
string
Unique request identifier

service
required
string
Service identifier for structured-query service

Const:"structured-query"
flow
required
string
Flow ID

required
object
Structured query request - natural language question with automatic execution.

Combines NLP query generation and execution in one call.

question
required
string
Natural language question

user
string
User identifier

Default value:"trustgraph"
collection
string
Collection to query

Default value:"default"
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for structured-diag service (flow-hosted service)

Examples values:
{"id":"req-1","service":"structured-diag","flow":"my-flow","request":{"operation":"status"}}
id
required
string
Unique request identifier

service
required
string
Service identifier for structured-diag service

Const:"structured-diag"
flow
required
string
Flow ID

required
object
Structured data diagnosis request - analyze and understand structured data formats.

Operations: detect-type, generate-descriptor, diagnose, schema-selection

operation
required
string
Diagnosis operation:

detect-type: Identify data format (CSV, JSON, XML)

generate-descriptor: Create schema descriptor for data

diagnose: Full analysis (detect + generate descriptor)

schema-selection: Find matching schemas for data

Allowed values:
"detect-type"
"generate-descriptor"
"diagnose"
"schema-selection"
sample
required
string
Data sample to analyze (text content)

type
string
Data type (required for generate-descriptor)

Allowed values:
"csv"
"json"
"xml"
schema-name
string
Target schema name for descriptor generation (optional)

object
Format-specific options (e.g., CSV delimiter)

Additional properties:
string
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for graph-embeddings service (flow-hosted service)

Examples values:
{"id":"req-1","service":"graph-embeddings","flow":"my-flow","request":{"text":"quantum computing","limit":10}}
id
required
string
Unique request identifier

service
required
string
Service identifier for graph-embeddings service

Const:"graph-embeddings"
flow
required
string
Flow ID

required
object
Graph embeddings query request - find similar entities by vector similarity.

required
array<number>
Query embedding vector

Items:
number
limit
integer
[ 1 .. 1000 ]
Maximum number of entities to return

Default value:10
user
string
User identifier

Default value:"trustgraph"
collection
string
Collection to search

Default value:"default"
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for document-embeddings service (flow-hosted service)

Examples values:
{"id":"req-1","service":"document-embeddings","flow":"my-flow","request":{"text":"quantum computing","limit":10}}
id
required
string
Unique request identifier

service
required
string
Service identifier for document-embeddings service

Const:"document-embeddings"
flow
required
string
Flow ID

required
object
Document embeddings query request - find similar documents by vector similarity.

required
array<number>
Query embedding vector

Items:
number
limit
integer
[ 1 .. 1000 ]
Maximum number of document chunks to return

Default value:10
user
string
User identifier

Default value:"trustgraph"
collection
string
Collection to search

Default value:"default"
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for text-load service (flow-hosted service)

Examples values:
{"id":"req-1","service":"text-load","flow":"my-flow","request":{"text":"This is the document content to be loaded into the knowledge graph.","collection":"default"}}
id
required
string
Unique request identifier

service
required
string
Service identifier for text-load service

Const:"text-load"
flow
required
string
Flow ID

required
object
Text load request - load text document into processing pipeline.

Fire-and-forget operation (no response).

text
required
string
format: byte
Text content (base64 encoded)

id
string
Document identifier

user
string
User identifier

Default value:"trustgraph"
collection
string
Collection for document

Default value:"default"
charset
string
Text character encoding

Default value:"utf-8"
array<object>
Document metadata as RDF triples

object
RDF triple (subject-predicate-object)

required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket request for document-load service (flow-hosted service)

Examples values:
{"id":"req-1","service":"document-load","flow":"my-flow","request":{"url":"https://example.com/document.pdf","collection":"default"}}
id
required
string
Unique request identifier

service
required
string
Service identifier for document-load service

Const:"document-load"
flow
required
string
Flow ID

required
object
Document load request - load binary document (PDF, etc.) into processing pipeline.

Fire-and-forget operation (no response).

data
required
string
format: byte
Document data (base64 encoded)

id
string
Document identifier

user
string
User identifier

Default value:"trustgraph"
collection
string
Collection for document

Default value:"default"
array<object>
Document metadata as RDF triples

object
RDF triple (subject-predicate-object)

required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
required
object
RDF value - can be entity/URI or literal

v
required
string
Value (URI or literal text)

e
required
boolean
True if entity/URI, false if literal

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
#2Service Response MessageServiceResponse
Successful response from any TrustGraph service
- application/json
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.

id
required
string
Request identifier from the original request. Client uses this to match responses to requests in multiplexed communication.

Examples values:
"req-123"
"request-abc-456"
required
object
Service-specific response payload. Structure is identical to the response body in the corresponding REST API endpoint.

For streaming services, multiple response messages may be sent with the same id. Look for end-of-stream or service-specific completion flags to detect the final message.

See OpenAPI specification for detailed schemas per service.

Examples values:
{"type":"flow","keys":["my-flow","production-flow"]}
{"chunk-type":"answer","content":"Quantum computing uses quantum bits...","end-of-stream":false}
Additional properties are allowed.
Additional properties are allowed.
#3Service Error MessageServiceError
Error response from any TrustGraph service
- application/json
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.

id
required
string
Request identifier from the original request that failed.

Examples values:
"req-123"
"request-abc-456"
required
object
Error information

type
required
string
Error type/category

Examples values:
"gateway-error"
"service-error"
"timeout"
message
required
string
Human-readable error message

Examples values:
"Flow not found"
"Service timeout"
"Invalid request format"
Additional properties are allowed.
Additional properties are allowed.

Schemas

object
WebSocket request message envelope.

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

id
required
string
Client-generated unique identifier for this request within the WebSocket session. Used to correlate responses with requests in multiplexed async communication. Can be any string, but must be unique per active request.

Examples values:
"req-123"
"request-abc-456"
"b5f8d9a2-4c3e-11ef-9c8a-0242ac120002"
service
required
string
Service identifier. Same as {kind} in REST API URLs.

Global services: config, flow, librarian, knowledge, collection-management Flow-hosted services: agent, text-completion, prompt, document-rag, graph-rag, embeddings, graph-embeddings, document-embeddings, triples, objects, nlp-query, structured-query, structured-diag, text-load, document-load, mcp-tool

Examples values:
"config"
"agent"
"document-rag"
flow
string
Flow ID for flow-hosted services. Required for services accessed via /api/v1/flow/{flow}/service/{kind} in REST API.

Omit this field for global services (config, flow, librarian, knowledge, collection-management).

Examples values:
"my-flow"
"production-flow"
required
object
Service-specific request payload. Structure is identical to the request body in the corresponding REST API endpoint.

See OpenAPI specification for detailed schemas per service.

Examples values:
{"operation":"list","type":"flow"}
{"question":"What is quantum computing?","streaming":true,"system-prompt":"You are a helpful assistant"}
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket response message envelope for successful responses.

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

id
required
string
Request identifier from the original request. Client uses this to match responses to requests in multiplexed communication.

Examples values:
"req-123"
"request-abc-456"
required
object
Service-specific response payload. Structure is identical to the response body in the corresponding REST API endpoint.

For streaming services, multiple response messages may be sent with the same id. Look for end-of-stream or service-specific completion flags to detect the final message.

See OpenAPI specification for detailed schemas per service.

Examples values:
{"type":"flow","keys":["my-flow","production-flow"]}
{"chunk-type":"answer","content":"Quantum computing uses quantum bits...","end-of-stream":false}
Additional properties are allowed.
Additional properties are allowed.
object
WebSocket error message envelope.

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

id
required
string
Request identifier from the original request that failed.

Examples values:
"req-123"
"request-abc-456"
required
object
Error information

type
required
string
Error type/category

Examples values:
"gateway-error"
"service-error"
"timeout"
message
required
string
Human-readable error message

Examples values:
"Flow not found"
"Service timeout"
"Invalid request format"
Additional properties are allowed.
Additional properties are allowed.