mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-05-29 17:25:15 +02:00
104 lines
3.4 KiB
YAML
104 lines
3.4 KiB
YAML
asyncapi: 3.0.0
|
|
|
|
info:
|
|
title: TrustGraph WebSocket API
|
|
version: "2.4"
|
|
description: |
|
|
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.
|
|
|
|
contact:
|
|
name: TrustGraph Project
|
|
url: https://trustgraph.ai
|
|
license:
|
|
name: Apache 2.0
|
|
url: https://www.apache.org/licenses/LICENSE-2.0.html
|
|
|
|
servers:
|
|
production:
|
|
host: localhost:8088
|
|
protocol: ws
|
|
description: Local development WebSocket server
|
|
security:
|
|
- $ref: '#/components/securitySchemes/bearerAuth'
|
|
|
|
defaultContentType: application/json
|
|
|
|
channels:
|
|
socket:
|
|
$ref: './channels/socket.yaml'
|
|
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: httpApiKey
|
|
name: Authorization
|
|
in: header
|
|
description: |
|
|
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:
|
|
ServiceRequest:
|
|
$ref: './components/messages/ServiceRequest.yaml'
|
|
ServiceResponse:
|
|
$ref: './components/messages/ServiceResponse.yaml'
|
|
ServiceError:
|
|
$ref: './components/messages/ServiceError.yaml'
|
|
|
|
schemas:
|
|
RequestEnvelope:
|
|
$ref: './components/schemas/RequestEnvelope.yaml'
|
|
ResponseEnvelope:
|
|
$ref: './components/schemas/ResponseEnvelope.yaml'
|
|
ErrorEnvelope:
|
|
$ref: './components/schemas/ErrorEnvelope.yaml'
|