mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-05-30 01:35:14 +02:00
Update API docs for 2.4 (#960)
- Update API specs for 2.4 (#960) - Update API docs - Regenerate Python docs
This commit is contained in:
cybermaggedon
GitHub
parent
961ad35469
commit
8eac99c182
62 changed files with 2036 additions and 1949 deletions
|
|
@ -2,7 +2,7 @@ asyncapi: 3.0.0
|
|||
|
||||
info:
|
||||
title: TrustGraph WebSocket API
|
||||
version: "2.2"
|
||||
version: "2.4"
|
||||
description: |
|
||||
WebSocket API for TrustGraph - providing multiplexed, asynchronous access to all services.
|
||||
|
||||
|
|
@ -14,21 +14,35 @@ info:
|
|||
- **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-hosted services
|
||||
- `flow`: Optional flow ID for flow-scoped services
|
||||
- `request`/`response`: Service-specific payload (identical to REST API schemas)
|
||||
- `error`: Error information on failure
|
||||
|
||||
## Service Types
|
||||
## Service Tiers
|
||||
|
||||
**Global Services** (no `flow` parameter):
|
||||
**Global Services** (no workspace scoping):
|
||||
- iam
|
||||
|
||||
**Workspace-Scoped Services** (workspace resolved from token):
|
||||
- config, flow, librarian, knowledge, collection-management
|
||||
|
||||
**Flow-Hosted Services** (require `flow` parameter):
|
||||
**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
|
||||
|
|
@ -64,11 +78,14 @@ components:
|
|||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: httpApiKey
|
||||
name: token
|
||||
in: query
|
||||
name: Authorization
|
||||
in: header
|
||||
description: |
|
||||
Bearer token authentication when GATEWAY_SECRET is configured.
|
||||
Include as query parameter: ws://localhost:8088/api/v1/socket?token=<token>
|
||||
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:
|
||||
|
|
|
|||
|
|
@ -3,8 +3,16 @@ description: |
|
|||
Primary WebSocket channel for all TrustGraph services.
|
||||
|
||||
This single channel provides multiplexed access to:
|
||||
- All global services (config, flow, librarian, knowledge, collection-management)
|
||||
- All flow-hosted services (agent, RAG, embeddings, queries, loading, etc.)
|
||||
- Global services (IAM)
|
||||
- Workspace-scoped services (config, flow, librarian, knowledge, collection-management)
|
||||
- Flow-scoped services (agent, RAG, embeddings, queries, loading, etc.)
|
||||
|
||||
## Authentication
|
||||
|
||||
The handshake is accepted unconditionally. The client must send a
|
||||
bearer token as the first frame after connecting (in-band auth).
|
||||
The gateway resolves the token to an identity and workspace. All
|
||||
subsequent requests execute within that workspace context.
|
||||
|
||||
## Multiplexing
|
||||
|
||||
|
|
@ -13,16 +21,17 @@ description: |
|
|||
|
||||
## Message Flow
|
||||
|
||||
1. Client sends request with unique `id`, `service`, optional `flow`, and `request` payload
|
||||
2. Server processes request asynchronously
|
||||
3. Server sends response(s) with matching `id` and either `response` or `error`
|
||||
4. For streaming services, multiple responses may be sent with the same `id`
|
||||
1. Client connects and sends bearer token as first frame (authentication)
|
||||
2. Client sends requests with unique `id`, `service`, optional `flow`, and `request` payload
|
||||
3. Server processes request asynchronously
|
||||
4. Server sends response(s) with matching `id` and either `response` or `error`
|
||||
5. For streaming services, multiple responses may be sent with the same `id`
|
||||
|
||||
## Service Routing
|
||||
|
||||
Messages are routed to services based on:
|
||||
- `service`: Service identifier (required)
|
||||
- `flow`: Flow ID (required for flow-hosted services, omitted for global services)
|
||||
- `flow`: Flow ID (required for flow-scoped services, omitted for workspace-scoped and global services)
|
||||
|
||||
messages:
|
||||
request:
|
||||
|
|
|
|||
|
|
@ -9,14 +9,14 @@ description: |
|
|||
payload:
|
||||
description: Service request envelope with id, service, optional flow, and service-specific request payload
|
||||
oneOf:
|
||||
# Global services (no flow parameter)
|
||||
# Workspace-scoped services (no flow parameter)
|
||||
- $ref: './requests/ConfigRequest.yaml'
|
||||
- $ref: './requests/FlowRequest.yaml'
|
||||
- $ref: './requests/LibrarianRequest.yaml'
|
||||
- $ref: './requests/KnowledgeRequest.yaml'
|
||||
- $ref: './requests/CollectionManagementRequest.yaml'
|
||||
|
||||
# Flow-hosted services (require flow parameter)
|
||||
# Flow-scoped services (require flow parameter)
|
||||
- $ref: './requests/AgentRequest.yaml'
|
||||
- $ref: './requests/DocumentRagRequest.yaml'
|
||||
- $ref: './requests/GraphRagRequest.yaml'
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for agent service (flow-hosted service)
|
||||
description: WebSocket request for agent service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for collection-management service (global service)
|
||||
description: WebSocket request for collection-management service (workspace-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for config service (global service)
|
||||
description: WebSocket request for config service (workspace-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for document-embeddings service (flow-hosted service)
|
||||
description: WebSocket request for document-embeddings service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for document-load service (flow-hosted service)
|
||||
description: WebSocket request for document-load service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for document-rag service (flow-hosted service)
|
||||
description: WebSocket request for document-rag service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for embeddings service (flow-hosted service)
|
||||
description: WebSocket request for embeddings service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for flow service (global service)
|
||||
description: WebSocket request for flow service (workspace-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for graph-embeddings service (flow-hosted service)
|
||||
description: WebSocket request for graph-embeddings service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for graph-rag service (flow-hosted service)
|
||||
description: WebSocket request for graph-rag service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for knowledge service (global service)
|
||||
description: WebSocket request for knowledge service (workspace-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for librarian service (global service)
|
||||
description: WebSocket request for librarian service (workspace-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for mcp-tool service (flow-hosted service)
|
||||
description: WebSocket request for mcp-tool service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for nlp-query service (flow-hosted service)
|
||||
description: WebSocket request for nlp-query service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for prompt service (flow-hosted service)
|
||||
description: WebSocket request for prompt service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for row-embeddings service (flow-hosted service)
|
||||
description: WebSocket request for row-embeddings service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for rows service (flow-hosted service)
|
||||
description: WebSocket request for rows service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for sparql-query service (flow-hosted service)
|
||||
description: WebSocket request for sparql-query service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for structured-diag service (flow-hosted service)
|
||||
description: WebSocket request for structured-diag service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for structured-query service (flow-hosted service)
|
||||
description: WebSocket request for structured-query service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for text-completion service (flow-hosted service)
|
||||
description: WebSocket request for text-completion service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for text-load service (flow-hosted service)
|
||||
description: WebSocket request for text-load service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
type: object
|
||||
description: WebSocket request for triples service (flow-hosted service)
|
||||
description: WebSocket request for triples service (flow-scoped service)
|
||||
required:
|
||||
- id
|
||||
- service
|
||||
|
|
|
|||
|
|
@ -23,8 +23,9 @@ properties:
|
|||
description: |
|
||||
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,
|
||||
Global services: iam
|
||||
Workspace-scoped services: config, flow, librarian, knowledge, collection-management
|
||||
Flow-scoped 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:
|
||||
|
|
@ -34,10 +35,12 @@ properties:
|
|||
flow:
|
||||
type: string
|
||||
description: |
|
||||
Flow ID for flow-hosted services. Required for services accessed via
|
||||
Flow ID for flow-scoped 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).
|
||||
Omit for global services (iam) and workspace-scoped services
|
||||
(config, flow, librarian, knowledge, collection-management).
|
||||
Workspace context is resolved from the authenticated token.
|
||||
examples:
|
||||
- my-flow
|
||||
- production-flow
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue