diff --git a/README.md b/README.md index 432fbb29..c366a3d9 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ -[![PyPI version](https://img.shields.io/pypi/v/trustgraph.svg)](https://pypi.org/project/trustgraph/) ![License](https://img.shields.io/badge/license-Apache%202.0-blue) ![E2E Tests](https://github.com/trustgraph-ai/trustgraph/actions/workflows/release.yaml/badge.svg) +[![PyPI version](https://img.shields.io/pypi/v/trustgraph.svg)](https://pypi.org/project/trustgraph/) [![License](https://img.shields.io/github/license/trustgraph-ai/trustgraph?color=blue)](LICENSE) ![E2E Tests](https://github.com/trustgraph-ai/trustgraph/actions/workflows/release.yaml/badge.svg) [![Discord](https://img.shields.io/discord/1251652173201149994 )](https://discord.gg/sQMwkRz5GX) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/trustgraph-ai/trustgraph) @@ -11,11 +11,11 @@ trustgraph-ai%2Ftrustgraph | Trendshift -# The semantic deployment platform +# The agent runtime platform -TrustGraph is a comprehensive semantic infrastructure for agents built around context graphs — structured, queryable representations of your domain knowledge that ground every agent query in verified, explainable facts in private deployments with sovereign control. The platform is the full stack for agentic systems: context graphs, memory, retrieval, orchestration, and inference for deterministic agent workloads. +TrustGraph is an agent runtime platform built around context graphs — structured, queryable representations of your domain knowledge that ground every agent query in verified, explainable facts in private deployments with sovereign control. The platform is the full stack for agentic systems: context graphs, memory, retrieval, orchestration, and inference for precision-critical agent workloads. The platform: - [x] Multi-model and multimodal database system @@ -99,21 +99,23 @@ For a browser based configuration, try the [Configuration Terminal](https://conf - [**Developer APIs and CLI**](https://docs.trustgraph.ai/reference) - [**Deployment Guides**](https://docs.trustgraph.ai/deployment) -## Context Graph UI +## Workbench -Image +The **Workbench** provides tools for all major features of TrustGraph. The **Workbench** is on port `8888` by default. -The UI provides tools for all major features of TrustGraph. The UI deploys on port `8888` by default. - -- **Agent Console** — Query your agents directly with streaming responses and live explainability event tracking, so you can watch reasoning unfold in real time -- **GraphRAG View** — Interactive graph RAG queries with a visual explainability DAG and inline provenance display, making it easy to see exactly where answers came from -- **Context Explorer** — An interactive 3D context graph explorer with dynamic graph loading, BFS neighborhood extraction, edge pulse animation, and multiple navigation views -- **Document Ingestion** — A complete upload and submission workflow with page and chunk inspection and document structure browsing -- **Ontology Workbench** — A full ontology editor with class and property trees, OWL/XML and Turtle import/export with round-trip fidelity, circular dependency detection, and safe-delete confirmation dialogs -- **Schema Workbench** — Interactive schema management with list, create, edit, and delete operations including field and index management -- **Flow Management** — Flow creation and detail views with configurable parameters, temperature controls, and grouped storage layout -- **Workspace UX** — Workspace selection and management surfaced directly in the interface -- **Prompt Editor** — A dedicated prompt editing workflow +- **Vector Search**: Search the installed knowledge bases +- **Agentic, GraphRAG and LLM Chat**: Chat interface for agents, GraphRAG queries, or direct to LLMs +- **Relationships**: Analyze deep relationships in the installed knowledge bases +- **Graph Visualizer**: 3D GraphViz of the installed knowledge bases +- **Library**: Staging area for installing knowledge bases +- **Flow Classes**: Workflow preset configurations +- **Flows**: Create custom workflows and adjust LLM parameters during runtime +- **Knowledge Cores**: Manage resuable knowledge bases +- **Prompts**: Manage and adjust prompts during runtime +- **Schemas**: Define custom schemas for structured data knowledge bases +- **Ontologies**: Define custom ontologies for unstructured data knowledge bases +- **Agent Tools**: Define tools with collections, knowledge cores, MCP connections, and tool groups +- **MCP Tools**: Connect to MCP servers ## TypeScript Library for UIs diff --git a/containers/Containerfile.hf b/containers/Containerfile.hf index 9cc6c2c8..93768b54 100644 --- a/containers/Containerfile.hf +++ b/containers/Containerfile.hf @@ -23,7 +23,7 @@ RUN pip3 install --no-cache-dir \ langchain==1.2.16 langchain-core==1.3.2 langchain-huggingface==1.2.2 \ langchain-community==0.4.1 \ sentence-transformers==5.4.1 transformers==5.7.0 \ - huggingface-hub==1.13.0 click \ + huggingface-hub==1.13.0 \ pulsar-client==3.11.0 # Most commonly used embeddings model, just build it into the container diff --git a/containers/Containerfile.unstructured b/containers/Containerfile.unstructured index 2b9a18f7..6de8a800 100644 --- a/containers/Containerfile.unstructured +++ b/containers/Containerfile.unstructured @@ -7,7 +7,7 @@ FROM docker.io/fedora:42 AS base ENV PIP_BREAK_SYSTEM_PACKAGES=1 -RUN dnf install -y python3.13 libxcb mesa-libGL poppler-utils && \ +RUN dnf install -y python3.13 libxcb mesa-libGL && \ alternatives --install /usr/bin/python python /usr/bin/python3.13 1 && \ python -m ensurepip --upgrade && \ pip3 install --no-cache-dir --upgrade 'pip>=26.0' 'setuptools>=78.1.1' && \ diff --git a/dev-tools/library_client.py b/dev-tools/library_client.py index 30e0c344..ae9d6857 100644 --- a/dev-tools/library_client.py +++ b/dev-tools/library_client.py @@ -25,7 +25,7 @@ BUCKET_URL = "https://storage.googleapis.com/trustgraph-library" INDEX_URL = f"{BUCKET_URL}/index.json" default_url = os.getenv("TRUSTGRAPH_URL", "http://localhost:8088/") -default_workspace = os.getenv("TRUSTGRAPH_WORKSPACE", "default") +default_user = "trustgraph" default_token = os.getenv("TRUSTGRAPH_TOKEN", None) @@ -113,7 +113,7 @@ def convert_metadata(metadata_json): return triples -def load_document(api, doc_entry): +def load_document(api, user, doc_entry): """Fetch metadata and content for a document, then load into TrustGraph.""" doc_id = doc_entry["id"] title = doc_entry["title"] @@ -133,6 +133,7 @@ def load_document(api, doc_entry): api.add_document( id=doc["id"], metadata=metadata, + user=user, kind=doc["kind"], title=doc["title"], comments=doc["comments"], @@ -143,12 +144,12 @@ def load_document(api, doc_entry): print(f" done.") -def load_documents(api, docs): +def load_documents(api, user, docs): """Load a list of documents.""" print(f"Loading {len(docs)} document(s)...\n") for doc in docs: try: - load_document(api, doc) + load_document(api, user, doc) except Exception as e: print(f" FAILED: {e}", file=sys.stderr) print() @@ -165,8 +166,8 @@ def main(): help=f"TrustGraph API URL (default: {default_url})", ) parser.add_argument( - "-w", "--workspace", default=default_workspace, - help=f"Workspace (default: {default_workspace})", + "-U", "--user", default=default_user, + help=f"User ID (default: {default_user})", ) parser.add_argument( "-t", "--token", default=default_token, @@ -211,22 +212,22 @@ def main(): return # Load commands need the API - api = Api(args.url, token=args.token, workspace=args.workspace).library() + api = Api(args.url, token=args.token).library() if args.command == "load-all": - load_documents(api, index) + load_documents(api, args.user, index) elif args.command == "load-doc": matches = [d for d in index if str(d.get("id")) == args.id] if not matches: print(f"No document with ID '{args.id}' found.", file=sys.stderr) sys.exit(1) - load_documents(api, matches) + load_documents(api, args.user, matches) elif args.command == "load-match": results = search_index(index, args.query) if results: - load_documents(api, results) + load_documents(api, args.user, results) else: print("No matches found.", file=sys.stderr) sys.exit(1) diff --git a/docs/api.html b/docs/api.html index a98b3675..2a03a38b 100644 --- a/docs/api.html +++ b/docs/api.html @@ -12,417 +12,417 @@ margin: 0; } - -

TrustGraph API Gateway (2.4)

Download OpenAPI specification:

REST API for TrustGraph - an AI-powered knowledge graph and RAG system.

-

Overview

TrustGraph API Gateway (2.2)

Download OpenAPI specification:

REST API for TrustGraph - an AI-powered knowledge graph and RAG system.

+

Overview

The API provides access to:

    -
  • Global Services: IAM (user management, authentication)
  • -
  • Workspace-Scoped Services: Configuration, flow management, knowledge storage, library management
  • -
  • Flow-Scoped Services: AI services like RAG, text completion, embeddings (require running flow)
  • +
  • Global Services: Configuration, flow management, knowledge storage, library management
  • +
  • Flow-Hosted Services: AI services like RAG, text completion, embeddings (require running flow)
  • Import/Export: Bulk data operations for triples, embeddings, entity contexts
  • WebSocket: Multiplexed interface for all services
-

Authentication

Clients authenticate by passing an opaque bearer token in the -Authorization header. The token is obtained via the IAM service -(e.g. tg-login or tg-create-api-key).

-
Authorization: Bearer <token>
-
-

The gateway resolves the token to an authenticated identity and an -associated workspace. The token is an opaque string — clients must -not make assumptions about its internal structure.

-

Service Tiers

Service Types

Global Services

-

System-wide services with no workspace scoping:

-
    -
  • iam - User management, authentication, API key lifecycle
  • -
-

Workspace-Scoped Services

-

Operate within the workspace associated with the authenticated -token. The workspace is resolved by the gateway — it is not -passed as an explicit parameter.

Fixed endpoints accessible via /api/v1/{kind}:

  • config - Configuration management
  • @@ -519,10 +483,8 @@ passed as an explicit parameter.

  • knowledge - Knowledge graph core management
  • collection-management - Collection metadata
-

Flow-Scoped Services

-

Require a flow parameter identifying the processing flow to use. -Workspace context comes from the authenticated token.

-

Accessed via /api/v1/flow/{flow}/service/{kind}:

+

Flow-Hosted Services

+

Require running flow instance, accessed via /api/v1/flow/{flow}/service/{kind}:

  • AI services: agent, text-completion, prompt, RAG (document/graph)
  • Embeddings: embeddings, graph-embeddings, document-embeddings
  • @@ -530,9 +492,19 @@ Workspace context comes from the authenticated token.

  • Data loading: text-load, document-load
  • Utilities: mcp-tool, structured-diag
-

Field Naming

Authentication

Bearer token authentication when GATEWAY_SECRET environment variable is set. +Include token in Authorization header:

+
Authorization: Bearer <token>
+
+

If GATEWAY_SECRET is not set, API runs without authentication (development mode).

+

Field Naming

All JSON fields use kebab-case: flow-id, blueprint-name, doc-limit, etc.

-

Error Responses

Error Responses

} } -

Config

Configuration management (workspace-scoped)

-

Configuration service (workspace-scoped)

Config

Configuration management (global service)

+

Configuration service

Manage TrustGraph configuration including flows, prompts, token costs, -parameter types, and more.

-

This is a workspace-scoped service. All operations apply to the -workspace associated with the authenticated bearer token.

+" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

Manage TrustGraph configuration including flows, prompts, token costs, parameter types, and more.

Operations

config

Get the complete system configuration including all flows, prompts, token costs, etc.

@@ -614,7 +580,7 @@ The flow service (/api/v1/flow) manages runnin
  • Use config service to store/retrieve flow definitions
  • Use flow service to start/stop/manage running flows
  • -
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "config" "list" "get" "put" "delete"
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "config" "list" "get" "put" "delete"

    Operation to perform:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Operation to perform:

    • config: Get complete configuration
    • list: List all items of a specific type
    • @@ -630,27 +596,25 @@ The flow service (/api/v1/flow) manages runnin
    • put: Set/update configuration values
    • delete: Delete configuration items
    -
    type
    string
    type
    string

    Configuration type (required for list, get, put, delete operations). +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

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

    -
    Array of objects

    Keys to retrieve (for get operation) or delete (for delete operation)

    -
    Array of objects

    Values to set/update (for put operation)

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "config"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "version": 42,
    • "config": {
      }
    }

    Flow

    Flow lifecycle and blueprint management (workspace-scoped)

    -

    Flow lifecycle and blueprint management (workspace-scoped)

    Array of objects

    Keys to retrieve (for get operation) or delete (for delete operation)

    +
    Array of objects

    Values to set/update (for put operation)

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "config"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "version": 42,
    • "config": {
      }
    }

    Flow

    Flow lifecycle and blueprint management (global service)

    +

    Flow lifecycle and blueprint management

    Manage flow instances and blueprints.

    -

    This is a workspace-scoped service. All operations apply to the -workspace associated with the authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Manage flow instances and blueprints.

    Important Distinction

    The flow service manages running flow instances. The config service (/api/v1/config) manages stored configuration.

    @@ -730,7 +692,7 @@ The config service (/api/v1/config) manages st

    delete-blueprint

    Delete a custom blueprint definition. Built-in blueprints cannot be deleted.

    -
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "start-flow" "stop-flow" "list-flows" "get-flow" "list-blueprints" "get-blueprint" "put-blueprint" "delete-blueprint"
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "start-flow" "stop-flow" "list-flows" "get-flow" "list-blueprints" "get-blueprint" "put-blueprint" "delete-blueprint"

    Flow operation:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Flow operation:

    • start-flow: Start a new flow instance from a blueprint
    • stop-flow: Stop a running flow instance
    • @@ -752,32 +714,29 @@ The config service (/api/v1/config) manages st
    • put-blueprint: Create/update blueprint definition
    • delete-blueprint: Delete blueprint definition
    -
    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)

    -
    description
    string

    Flow description (optional for start-flow)

    -
    object
    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)

    +
    description
    string

    Flow description (optional for start-flow)

    +
    object

    Flow parameters (for start-flow). +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

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

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "start-flow",
    • "flow-id": "my-flow",
    • "blueprint-name": "document-rag",
    • "description": "My document processing flow",
    • "parameters": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "flow-id": "my-flow"
    }

    Librarian

    Document library management (workspace-scoped)

    -

    Document library management (workspace-scoped)

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "start-flow",
    • "flow-id": "my-flow",
    • "blueprint-name": "document-rag",
    • "description": "My document processing flow",
    • "parameters": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "flow-id": "my-flow"
    }

    Librarian

    Document library management (global service)

    +

    Document library management

    Manage document library: add, remove, list documents, and control -processing.

    -

    This is a workspace-scoped service. All operations apply to the -workspace associated with the authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Manage document library: add, remove, list documents, and control processing.

    Document Library

    The librarian service manages a persistent library of documents that can be:

      @@ -828,7 +784,7 @@ for processing and handled asynchronously.

      Stop ongoing library document processing.

      list-processing

      List current processing tasks and their status.

      -
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "add-document" "remove-document" "list-documents" "get-document-metadata" "get-document-content" "stream-document" "add-child-document" "list-children" "begin-upload" "upload-chunk" "complete-upload" "abort-upload" "get-upload-status" "list-uploads" "start-processing" "stop-processing" "list-processing"
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "add-document" "remove-document" "list-documents" "get-document-metadata" "get-document-content" "stream-document" "add-child-document" "list-children" "begin-upload" "upload-chunk" "complete-upload" "abort-upload" "get-upload-status" "list-uploads" "start-processing" "stop-processing" "list-processing"

    Library operation:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Library operation:

    • add-document: Add document to library
    • remove-document: Remove document from library
    • @@ -876,36 +832,35 @@ for all document sizes.
    • stop-processing: Stop library processing
    • list-processing: List processing status
    -
    flow
    string

    Flow ID

    -
    collection
    string
    Default: "default"

    Collection identifier

    -
    document-id
    string

    Document identifier

    -
    processing-id
    string

    Processing task identifier

    -
    object (DocumentMetadata)

    Document metadata for library management

    -
    object (ProcessingMetadata)

    Processing metadata for library document processing

    -
    content
    string

    Document content (for add-document with inline content)

    -
    Array of objects

    Search criteria for filtering documents

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "add-document",
    • "flow": "my-flow",
    • "collection": "default",
    • "document-metadata": {}
    }

    Response samples

    Content type
    application/json
    Example
    {}

    Knowledge

    Knowledge graph core management (workspace-scoped)

    -

    Knowledge graph core management (workspace-scoped)

    flow
    string

    Flow ID

    +
    collection
    string
    Default: "default"

    Collection identifier

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    document-id
    string

    Document identifier

    +
    processing-id
    string

    Processing task identifier

    +
    object (DocumentMetadata)

    Document metadata for library management

    +
    object (ProcessingMetadata)

    Processing metadata for library document processing

    +
    content
    string

    Document content (for add-document with inline content)

    +
    Array of objects

    Search criteria for filtering documents

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "add-document",
    • "flow": "my-flow",
    • "collection": "default",
    • "document-metadata": {}
    }

    Response samples

    Content type
    application/json
    Example
    {}

    Knowledge

    Knowledge graph core management (global service)

    +

    Knowledge graph core management

    Manage knowledge graph cores - persistent storage of triples and -embeddings.

    -

    This is a workspace-scoped service. All operations apply to the -workspace associated with the authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Manage knowledge graph cores - persistent storage of triples and embeddings.

    Knowledge Cores

    Knowledge cores are the foundational storage units for:

      @@ -948,10 +900,10 @@ workspace associated with the authenticated bearer token.

    • Graph Embeddings: Vector embeddings for entities
    • Metadata: Descriptive information about the knowledge
    -

    Each core has an ID and collection for organization (within the workspace).

    +

    Each core has an ID, user, and collection for organization.

    Operations

    list-kg-cores

    -

    List all knowledge cores in the workspace. Returns array of core IDs.

    +

    List all knowledge cores for a user. Returns array of core IDs.

    get-kg-core

    Retrieve a knowledge core by ID. Returns triples and/or graph embeddings. Response is streamed - may receive multiple messages followed by EOS marker.

    @@ -972,138 +924,137 @@ Removes data from flow instance but doesn't delete the core.

  • Multiple messages with triples or graph-embeddings
  • Final message with eos: true to signal completion
  • -
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "list-kg-cores" "get-kg-core" "put-kg-core" "delete-kg-core" "load-kg-core" "unload-kg-core"
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "list-kg-cores" "get-kg-core" "put-kg-core" "delete-kg-core" "load-kg-core" "unload-kg-core"

    Knowledge core operation:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Knowledge core operation:

      -
    • list-kg-cores: List knowledge cores in the current workspace (resolved from token)
    • +
    • 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
    -
    id
    string

    Knowledge core ID (for get, put, delete, load, unload)

    -
    flow
    string

    Flow ID (for load-kg-core)

    -
    collection
    string
    Default: "default"

    Collection identifier (for load-kg-core)

    -
    object

    Triples to store (for put-kg-core)

    -
    object

    Graph embeddings to store (for put-kg-core)

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "list-kg-cores"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "ids": [
      ]
    }

    Collection

    Collection metadata management (workspace-scoped)

    -

    Collection metadata management (workspace-scoped)

    user
    string
    Default: "trustgraph"

    User identifier (for list-kg-cores, put-kg-core, delete-kg-core)

    +
    id
    string

    Knowledge core ID (for get, put, delete, load, unload)

    +
    flow
    string

    Flow ID (for load-kg-core)

    +
    collection
    string
    Default: "default"

    Collection identifier (for load-kg-core)

    +
    object

    Triples to store (for put-kg-core)

    +
    object

    Graph embeddings to store (for put-kg-core)

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "list-kg-cores",
    • "user": "alice"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "ids": [
      ]
    }

    Collection

    Collection metadata management (global service)

    +

    Collection metadata management

    Manage collection metadata for organizing documents and knowledge.

    -

    This is a workspace-scoped service. All operations apply to the -workspace associated with the authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Manage collection metadata for organizing documents and knowledge.

    Collections

    Collections are organizational units for grouping:

    • Documents in the librarian
    • Knowledge cores
    • -
    • Workspace data
    • +
    • User data

    Each collection has:

      -
    • collection: Unique collection ID (within the workspace)
    • +
    • user: Owner identifier
    • +
    • collection: Unique collection ID
    • name: Human-readable display name
    • description: Purpose and contents
    • tags: Labels for filtering and organization

    Operations

    list-collections

    -

    List all collections in the workspace. Optionally filter by tags and limit results. +

    List all collections for a user. Optionally filter by tags and limit results. Returns array of collection metadata.

    update-collection

    Create or update collection metadata. If collection doesn't exist, it's created. If it exists, metadata is updated. Allows setting name, description, and tags.

    delete-collection

    -

    Delete a collection by collection ID. This removes the metadata but +

    Delete a collection by user and collection ID. This removes the metadata but typically does not delete the associated data (documents, knowledge cores).

    -
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "list-collections" "update-collection" "delete-collection"
    Authorizations:
    bearerAuth
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "list-collections" "update-collection" "delete-collection"

    Collection operation:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Collection operation:

      -
    • list-collections: List collections in the current workspace (resolved from token)
    • +
    • list-collections: List collections for user
    • update-collection: Create or update collection metadata
    • delete-collection: Delete collection
    -
    collection
    string

    Collection identifier (for update, delete)

    -
    timestamp
    string <date-time>

    ISO timestamp

    -
    name
    string

    Human-readable collection name (for update)

    -
    description
    string

    Collection description (for update)

    -
    tags
    Array of strings

    Collection tags for organization (for update)

    -
    tag-filter
    Array of strings

    Filter collections by tags (for list)

    -
    limit
    integer
    Default: 0

    Maximum number of results (for list)

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "list-collections"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "timestamp": "2024-01-15T10:30:00Z",
    • "collections": [
      ]
    }

    Flow Services

    AI and query services hosted within flow instances (flow-scoped)

    -

    Agent service - conversational AI with reasoning

    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string

    Collection identifier (for update, delete)

    +
    timestamp
    string <date-time>

    ISO timestamp

    +
    name
    string

    Human-readable collection name (for update)

    +
    description
    string

    Collection description (for update)

    +
    tags
    Array of strings

    Collection tags for organization (for update)

    +
    tag-filter
    Array of strings

    Filter collections by tags (for list)

    +
    limit
    integer
    Default: 0

    Maximum number of results (for list)

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "list-collections",
    • "user": "alice"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "timestamp": "2024-01-15T10:30:00Z",
    • "collections": [
      ]
    }

    Flow Services

    Services hosted within flow instances

    +

    Agent service - conversational AI with reasoning

    AI agent that can understand questions, reason about them, and take actions.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    AI agent that can understand questions, reason about them, and take actions.

    Agent Overview

    The agent service provides a conversational AI that:

      @@ -1192,30 +1140,29 @@ authenticated bearer token.

      Multi-turn Conversations

      Include history array with previous steps to maintain context. Each step has: thought, action, arguments, observation.

      -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    question
    required
    string

    User question or prompt for the agent

    -
    state
    string

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

    -
    group
    Array of strings

    Group identifiers for collaborative agents (optional)

    -
    Array of objects

    Conversation history (optional, list of previous agent steps)

    -
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "What is the capital of France?"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "chunk-type": "thought",
    • "content": "I need to search for information about quantum computing",
    • "end-of-message": false,
    • "end-of-dialog": false
    }

    Document RAG - retrieve and generate from documents

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    question
    required
    string

    User question or prompt for the agent

    +
    state
    string

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

    +
    group
    Array of strings

    Group identifiers for collaborative agents (optional)

    +
    Array of objects

    Conversation history (optional, list of previous agent steps)

    +
    user
    string
    Default: "trustgraph"

    User identifier for multi-tenancy

    +
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "What is the capital of France?",
    • "user": "alice"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "chunk-type": "thought",
    • "content": "I need to search for information about quantum computing",
    • "end-of-message": false,
    • "end-of-dialog": false
    }

    Document RAG - retrieve and generate from documents

    Retrieval-Augmented Generation over document embeddings.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieval-Augmented Generation over document embeddings.

    Document RAG Overview

    Document RAG combines:

      @@ -1289,29 +1234,29 @@ inline in the stream, so no follow-up knowledge graph query is needed.

    1. collection: Target specific document collection
    2. +
    3. user: Multi-tenant isolation
    4. -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    query
    required
    string

    User query or question

    -
    collection
    string
    Default: "default"

    Collection to search within

    -
    doc-limit
    integer [ 1 .. 100 ]
    Default: 20

    Maximum number of documents to retrieve

    -
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "What are the key findings in the research papers?",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "The research papers present three key findings:\n1. Quantum entanglement exhibits non-local correlations\n2. Bell's inequality is violated in experimental tests\n3. Applications in quantum cryptography are promising\n",
    • "end-of-stream": false
    }

    Graph RAG - retrieve and generate from knowledge graph

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    query
    required
    string

    User query or question

    +
    user
    string
    Default: "trustgraph"

    User identifier for multi-tenancy

    +
    collection
    string
    Default: "default"

    Collection to search within

    +
    doc-limit
    integer [ 1 .. 100 ]
    Default: 20

    Maximum number of documents to retrieve

    +
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "What are the key findings in the research papers?",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "The research papers present three key findings:\n1. Quantum entanglement exhibits non-local correlations\n2. Bell's inequality is violated in experimental tests\n3. Applications in quantum cryptography are promising\n",
    • "end-of-stream": false
    }

    Graph RAG - retrieve and generate from knowledge graph

    Retrieval-Augmented Generation over knowledge graph.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieval-Augmented Generation over knowledge graph.

    Graph RAG Overview

    Graph RAG combines:

      @@ -1412,34 +1354,33 @@ inline in the stream, so no follow-up knowledge graph query is needed.

    1. Multi-hop reasoning ("What's the path from A to B?")
    2. Structural analysis ("What are the main entities related to X?")
    3. -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    query
    required
    string

    User query or question

    -
    collection
    string
    Default: "default"

    Collection to search within

    -
    entity-limit
    integer [ 1 .. 200 ]
    Default: 50

    Maximum number of entities to retrieve

    -
    triple-limit
    integer [ 1 .. 100 ]
    Default: 30

    Maximum number of triples to retrieve per entity

    -
    max-subgraph-size
    integer [ 10 .. 5000 ]
    Default: 1000

    Maximum total subgraph size (triples)

    -
    max-path-length
    integer [ 1 .. 5 ]
    Default: 2

    Maximum path length for graph traversal

    -
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "What connections exist between quantum physics and computer science?",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "Quantum physics and computer science intersect primarily through quantum computing.\nThe knowledge graph shows connections through:\n- Quantum algorithms (Shor's algorithm, Grover's algorithm)\n- Quantum information theory\n- Computational complexity theory\n",
    • "end-of-stream": false
    }

    Text completion - direct LLM generation

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    query
    required
    string

    User query or question

    +
    user
    string
    Default: "trustgraph"

    User identifier for multi-tenancy

    +
    collection
    string
    Default: "default"

    Collection to search within

    +
    entity-limit
    integer [ 1 .. 200 ]
    Default: 50

    Maximum number of entities to retrieve

    +
    triple-limit
    integer [ 1 .. 100 ]
    Default: 30

    Maximum number of triples to retrieve per entity

    +
    max-subgraph-size
    integer [ 10 .. 5000 ]
    Default: 1000

    Maximum total subgraph size (triples)

    +
    max-path-length
    integer [ 1 .. 5 ]
    Default: 2

    Maximum path length for graph traversal

    +
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "What connections exist between quantum physics and computer science?",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "Quantum physics and computer science intersect primarily through quantum computing.\nThe knowledge graph shows connections through:\n- Quantum algorithms (Shor's algorithm, Grover's algorithm)\n- Quantum information theory\n- Computational complexity theory\n",
    • "end-of-stream": false
    }

    Text completion - direct LLM generation

    Direct text completion using LLM without retrieval augmentation.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Direct text completion using LLM without retrieval augmentation.

    Text Completion Overview

    Pure LLM generation for:

      @@ -1536,26 +1474,23 @@ authenticated bearer token.

    • Want to leverage knowledge graph relationships
    • Require citations or provenance
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    system
    required
    string

    System prompt that sets behavior and context for the LLM

    -
    prompt
    required
    string

    User prompt or question

    -
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "system": "You are a helpful assistant that provides concise answers.",
    • "prompt": "Explain the concept of recursion in programming."
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "Recursion is a programming technique where a function calls itself\nto solve a problem by breaking it down into smaller, similar subproblems.\nEach recursive call works on a simpler version until reaching a base case.\n",
    • "in-token": 45,
    • "out-token": 128,
    • "model": "gpt-4",
    • "end-of-stream": false
    }

    Prompt service - template-based generation

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    system
    required
    string

    System prompt that sets behavior and context for the LLM

    +
    prompt
    required
    string

    User prompt or question

    +
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "system": "You are a helpful assistant that provides concise answers.",
    • "prompt": "Explain the concept of recursion in programming."
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "response": "Recursion is a programming technique where a function calls itself\nto solve a problem by breaking it down into smaller, similar subproblems.\nEach recursive call works on a simpler version until reaching a base case.\n",
    • "in-token": 45,
    • "out-token": 128,
    • "model": "gpt-4",
    • "end-of-stream": false
    }

    Prompt service - template-based generation

    Execute stored prompt templates with variable substitution.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Execute stored prompt templates with variable substitution.

    Prompt Service Overview

    The prompt service enables:

      @@ -1676,28 +1608,25 @@ authenticated bearer token.

    • Data transformation
    • Any repeatable LLM task with consistent prompting
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    id
    required
    string

    Prompt template ID (stored in config)

    -
    object

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

    -
    object

    Alternative to terms - variables as native JSON values (auto-converted)

    -
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "id": "summarize-document",
    • "terms": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "text": "This document provides an overview of quantum computing fundamentals and cryptographic applications.",
    • "end-of-stream": false
    }

    Embeddings - text to vector conversion

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    id
    required
    string

    Prompt template ID (stored in config)

    +
    object

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

    +
    object

    Alternative to terms - variables as native JSON values (auto-converted)

    +
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "id": "summarize-document",
    • "terms": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "text": "This document provides an overview of quantum computing fundamentals and cryptographic applications.",
    • "end-of-stream": false
    }

    Embeddings - text to vector conversion

    Convert text to embedding vectors for semantic similarity search.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Convert text to embedding vectors for semantic similarity search.

    Embeddings Overview

    Embeddings transform text into dense vector representations that:

      @@ -1756,22 +1682,19 @@ authenticated bearer token.

      Single Request

      Unlike batch embedding APIs, this endpoint processes one text at a time. For bulk operations, use document-load or text-load services.

      -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    text
    required
    string

    Text to convert to embedding vector

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "text": "Machine learning"
    }

    Response samples

    Content type
    application/json
    {
    • "vectors": [
      ]
    }

    MCP Tool - execute Model Context Protocol tools

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    text
    required
    string

    Text to convert to embedding vector

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "text": "Machine learning"
    }

    Response samples

    Content type
    application/json
    {
    • "vectors": [
      ]
    }

    MCP Tool - execute Model Context Protocol tools

    Execute MCP (Model Context Protocol) tools for agent capabilities.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Execute MCP (Model Context Protocol) tools for agent capabilities.

    MCP Tool Overview

    MCP tools provide agent capabilities through standardized protocol:

      @@ -1866,24 +1786,21 @@ authenticated bearer token.

    • File operations: Read/write files
    • Code execution: Run scripts
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    name
    required
    string

    Tool name to execute

    -
    object

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

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "name": "search",
    • "parameters": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "text": "The result is 309"
    }

    Triples query - pattern-based graph queries

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    name
    required
    string

    Tool name to execute

    +
    object

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

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "name": "search",
    • "parameters": {
      }
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "text": "The result is 309"
    }

    Triples query - pattern-based graph queries

    Query knowledge graph using subject-predicate-object patterns.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Query knowledge graph using subject-predicate-object patterns.

    Triples Query Overview

    Query RDF triples with flexible pattern matching:

      @@ -1978,46 +1892,45 @@ authenticated bearer token.

    • More specific patterns = faster queries
    • Consider limit for large result sets
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    object (RdfValue)

    Subject filter (optional)

    -
    object (RdfValue)

    Predicate filter (optional)

    -
    object (RdfValue)

    Object filter (optional)

    -
    limit
    integer [ 1 .. 100000 ]
    Default: 10000

    Maximum number of triples to return

    -
    collection
    string
    Default: "default"

    Collection to query

    -
    g
    string
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    object (RdfValue)

    Subject filter (optional)

    +
    object (RdfValue)

    Predicate filter (optional)

    +
    object (RdfValue)

    Object filter (optional)

    +
    limit
    integer [ 1 .. 100000 ]
    Default: 10000

    Maximum number of triples to return

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to query

    +
    g
    string

    Named graph filter (optional).

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Named graph filter (optional).

    • Omitted/null: all graphs
    • Empty string: default graph only
    • URI string: specific named graph (e.g., urn:graph:source, urn:graph:retrieval)
    -
    streaming
    boolean
    Default: false

    Enable streaming response delivery

    -
    batch-size
    integer [ 1 .. 1000 ]
    Default: 20

    Number of triples per streaming batch

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {}

    Response samples

    Content type
    application/json
    {}

    Rows query - GraphQL over structured data

    streaming
    boolean
    Default: false

    Enable streaming response delivery

    +
    batch-size
    integer [ 1 .. 1000 ]
    Default: 20

    Number of triples per streaming batch

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {}

    Response samples

    Content type
    application/json
    {}

    Rows query - GraphQL over structured data

    Query structured data using GraphQL for row-oriented data access.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Query structured data using GraphQL for row-oriented data access.

    Rows Query Overview

    GraphQL interface to structured data:

      @@ -2114,28 +2024,27 @@ authenticated bearer token.

      Schema Definition

      Schema defines available types via config service. Use introspection query to discover schema.

      -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    query
    required
    string

    GraphQL query string

    -
    object

    GraphQL query variables

    -
    operation-name
    string

    Operation name (for multi-operation documents)

    -
    collection
    string
    Default: "default"

    Collection to query

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "{\n person(id: \"https://example.com/person/alice\") {\n name\n email\n }\n}\n",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "data": {
      },
    • "extensions": {
      }
    }

    NLP Query - natural language to structured query

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    query
    required
    string

    GraphQL query string

    +
    object

    GraphQL query variables

    +
    operation-name
    string

    Operation name (for multi-operation documents)

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to query

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "{\n person(id: \"https://example.com/person/alice\") {\n name\n email\n }\n}\n",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "data": {
      },
    • "extensions": {
      }
    }

    NLP Query - natural language to structured query

    Convert natural language questions to structured GraphQL queries.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Convert natural language questions to structured GraphQL queries.

    NLP Query Overview

    Transforms user questions into executable GraphQL:

      @@ -2242,24 +2148,21 @@ authenticated bearer token.

    • Missing schema coverage
    • Complex query structure
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    question
    required
    string

    Natural language question

    -
    max-results
    integer [ 1 .. 10000 ]
    Default: 100

    Maximum results to return when query is executed

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "Who does Alice know?",
    • "max-results": 50
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "graphql-query": "query GetConnections($person: ID!) {\n person(id: $person) {\n knows { name email }\n }\n}\n",
    • "variables": {},
    • "detected-schemas": [
      ],
    • "confidence": 0.92
    }

    Structured Query - question to results (all-in-one)

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    question
    required
    string

    Natural language question

    +
    max-results
    integer [ 1 .. 10000 ]
    Default: 100

    Maximum results to return when query is executed

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "Who does Alice know?",
    • "max-results": 50
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "graphql-query": "query GetConnections($person: ID!) {\n person(id: $person) {\n knows { name email }\n }\n}\n",
    • "variables": {},
    • "detected-schemas": [
      ],
    • "confidence": 0.92
    }

    Structured Query - question to results (all-in-one)

    Ask natural language questions and get results directly.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Ask natural language questions and get results directly.

    Structured Query Overview

    Combines two operations in one call:

      @@ -2382,24 +2282,23 @@ authenticated bearer token.

    1. Less control: Can't inspect/modify generated query
    2. Simpler code: No need to handle intermediate steps
    3. -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    question
    required
    string

    Natural language question

    -
    collection
    string
    Default: "default"

    Collection to query

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "Who does Alice know?",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "data": {
      },
    • "errors": [ ]
    }

    Structured Diag - analyze structured data formats

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    question
    required
    string

    Natural language question

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to query

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "question": "Who does Alice know?",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "data": {
      },
    • "errors": [ ]
    }

    Structured Diag - analyze structured data formats

    Analyze and understand structured data (CSV, JSON, XML).

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Analyze and understand structured data (CSV, JSON, XML).

    Structured Diag Overview

    Helps process unknown structured data:

      @@ -2524,42 +2420,39 @@ authenticated bearer token.

    • Use descriptor to process full dataset
    • Load data via document-load or text-load
    • -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "detect-type" "generate-descriptor" "diagnose" "schema-selection"
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    operation
    required
    string
    Enum: "detect-type" "generate-descriptor" "diagnose" "schema-selection"

    Diagnosis operation:

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    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
    -
    sample
    required
    string

    Data sample to analyze (text content)

    -
    type
    string
    Enum: "csv" "json" "xml"

    Data type (required for generate-descriptor)

    -
    schema-name
    string

    Target schema name for descriptor generation (optional)

    -
    object

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

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "detect-type",
    • "sample": "name,age,email\nAlice,30,alice@example.com\nBob,25,bob@example.com\n"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "operation": "detect-type",
    • "detected-type": "csv",
    • "confidence": 0.95
    }

    Graph Embeddings Query - find similar entities

    sample
    required
    string

    Data sample to analyze (text content)

    +
    type
    string
    Enum: "csv" "json" "xml"

    Data type (required for generate-descriptor)

    +
    schema-name
    string

    Target schema name for descriptor generation (optional)

    +
    object

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

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "operation": "detect-type",
    • "sample": "name,age,email\nAlice,30,alice@example.com\nBob,25,bob@example.com\n"
    }

    Response samples

    Content type
    application/json
    Example
    {
    • "operation": "detect-type",
    • "detected-type": "csv",
    • "confidence": 0.95
    }

    Graph Embeddings Query - find similar entities

    Query graph embeddings to find similar entities by vector similarity.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Query graph embeddings to find similar entities by vector similarity.

    Graph Embeddings Query Overview

    Find entities semantically similar to a query vector:

      @@ -2638,26 +2528,25 @@ authenticated bearer token.

    • These are references to knowledge graph entities
    • Use with triples query to get entity details
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    vectors
    required
    Array of numbers

    Query embedding vector

    -
    limit
    integer [ 1 .. 1000 ]
    Default: 10

    Maximum number of entities to return

    -
    collection
    string
    Default: "default"

    Collection to search

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vectors": [
      ],
    • "limit": 10,
    • "collection": "research"
    }

    Response samples

    Content type
    application/json

    Document Embeddings Query - find similar text chunks

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    vectors
    required
    Array of numbers

    Query embedding vector

    +
    limit
    integer [ 1 .. 1000 ]
    Default: 10

    Maximum number of entities to return

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to search

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vectors": [
      ],
    • "limit": 10,
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json

    Document Embeddings Query - find similar text chunks

    Query document embeddings to find similar text chunks by vector similarity.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Query document embeddings to find similar text chunks by vector similarity.

    Document Embeddings Query Overview

    Find document chunks semantically similar to a query vector:

      @@ -2752,27 +2638,26 @@ authenticated bearer token.

    • No metadata (source, position, etc.)
    • Use for LLM context directly
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    vectors
    required
    Array of numbers

    Query embedding vector

    -
    limit
    integer [ 1 .. 1000 ]
    Default: 10

    Maximum number of document chunks to return

    -
    collection
    string
    Default: "default"

    Collection to search

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vectors": [
      ],
    • "limit": 10,
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    {
    • "chunks": [
      ]
    }

    Row Embeddings Query - semantic search on structured data

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    vectors
    required
    Array of numbers

    Query embedding vector

    +
    limit
    integer [ 1 .. 1000 ]
    Default: 10

    Maximum number of document chunks to return

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to search

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vectors": [
      ],
    • "limit": 10,
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    {
    • "chunks": [
      ]
    }

    Row Embeddings Query - semantic search on structured data

    Query row embeddings to find similar rows by vector similarity on indexed fields.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    -

    Enables fuzzy/semantic matching on structured data.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Query row embeddings to find similar rows by vector similarity on indexed fields. +Enables fuzzy/semantic matching on structured data.

    Row Embeddings Query Overview

    Find rows whose indexed field values are semantically similar to a query:

      @@ -2840,30 +2722,29 @@ authenticated bearer token.

    • text: The text that was embedded
    • score: Similarity score (higher = more similar)
    -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    vectors
    required
    Array of numbers

    Query embedding vector

    -
    schema_name
    required
    string

    Schema name to search within

    -
    index_name
    string

    Optional index name to filter search to specific index

    -
    limit
    integer [ 1 .. 1000 ]
    Default: 10

    Maximum number of matches to return

    -
    collection
    string
    Default: "default"

    Collection to search

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vectors": [
      ],
    • "schema_name": "customers",
    • "limit": 10,
    • "collection": "sales"
    }

    Response samples

    Content type
    application/json
    {
    • "matches": [
      ]
    }

    Text Load - load text documents

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    vectors
    required
    Array of numbers

    Query embedding vector

    +
    schema_name
    required
    string

    Schema name to search within

    +
    index_name
    string

    Optional index name to filter search to specific index

    +
    limit
    integer [ 1 .. 1000 ]
    Default: 10

    Maximum number of matches to return

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection to search

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "vectors": [
      ],
    • "schema_name": "customers",
    • "limit": 10,
    • "user": "alice",
    • "collection": "sales"
    }

    Response samples

    Content type
    application/json
    {
    • "matches": [
      ]
    }

    Text Load - load text documents

    Load text documents into processing pipeline for indexing and embedding.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Load text documents into processing pipeline for indexing and embedding.

    Text Load Overview

    Fire-and-forget document loading:

      @@ -2970,30 +2848,29 @@ encoded = base64
      Authorizations:
      bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    text
    required
    string

    Text content, either raw text or base64 encoded for compatibility with older clients

    -
    id
    string

    Document identifier

    -
    collection
    string
    Default: "default"

    Collection for document

    -
    charset
    string
    Default: "utf-8"

    Text character encoding

    -
    Array of objects (Triple)

    Document metadata as RDF triples

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "text": "This is the document text...",
    • "id": "doc-123",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    { }

    Document Load - load binary documents (PDF, etc.)

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    text
    required
    string

    Text content, either raw text or base64 encoded for compatibility with older clients

    +
    id
    string

    Document identifier

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection for document

    +
    charset
    string
    Default: "utf-8"

    Text character encoding

    +
    Array of objects (Triple)

    Document metadata as RDF triples

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "text": "This is the document text...",
    • "id": "doc-123",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    { }

    Document Load - load binary documents (PDF, etc.)

    Load binary documents (PDF, Word, etc.) into processing pipeline.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Load binary documents (PDF, Word, etc.) into processing pipeline.

    Document Load Overview

    Fire-and-forget binary document loading:

      @@ -3106,28 +2980,27 @@ encoded = base64
      Authorizations:
      bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    data
    required
    string <byte>

    Document data (base64 encoded)

    -
    id
    string

    Document identifier

    -
    collection
    string
    Default: "default"

    Collection for document

    -
    Array of objects (Triple)

    Document metadata as RDF triples

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PmVuZG9iagoyIDAgb2JqCjw8L1R5cGUvUGFnZXMvS2lkc1szIDAgUl0vQ291bnQgMT4+ZW5kb2JqCg==",
    • "id": "doc-789",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    { }

    SPARQL query - execute SPARQL 1.1 queries against the knowledge graph

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    data
    required
    string <byte>

    Document data (base64 encoded)

    +
    id
    string

    Document identifier

    +
    user
    string
    Default: "trustgraph"

    User identifier

    +
    collection
    string
    Default: "default"

    Collection for document

    +
    Array of objects (Triple)

    Document metadata as RDF triples

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PmVuZG9iagoyIDAgb2JqCjw8L1R5cGUvUGFnZXMvS2lkc1szIDAgUl0vQ291bnQgMT4+ZW5kb2JqCg==",
    • "id": "doc-789",
    • "user": "alice",
    • "collection": "research"
    }

    Response samples

    Content type
    application/json
    { }

    SPARQL query - execute SPARQL 1.1 queries against the knowledge graph

    Execute a SPARQL 1.1 query against the knowledge graph.

    -

    This is a flow-scoped service. It requires a flow instance -and operates within the workspace associated with the -authenticated bearer token.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Execute a SPARQL 1.1 query against the knowledge graph.

    Supported Query Types

    • SELECT: Returns variable bindings as a table of results
    • @@ -3188,53 +3058,59 @@ LIMIT 10

      Check if an entity exists:

      ASK { <http://example.com/alice> ?p ?o }
       
      -
    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    -
    Request Body schema: application/json
    required
    query
    required
    string

    SPARQL 1.1 query string

    -
    collection
    string
    Default: "default"

    Collection identifier

    -
    limit
    integer
    Default: 10000

    Safety limit on number of results

    -

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10",
    • "collection": "default"
    }

    Response samples

    Content type
    application/json
    Example
    {}

    Import/Export

    Authorizations:
    bearerAuth
    path Parameters
    flow
    required
    string
    Example: my-flow

    Flow instance ID

    +
    Request Body schema: application/json
    required
    query
    required
    string

    SPARQL 1.1 query string

    +
    user
    string
    Default: "trustgraph"

    User/keyspace identifier

    +
    collection
    string
    Default: "default"

    Collection identifier

    +
    limit
    integer
    Default: 10000

    Safety limit on number of results

    +

    Responses

    Request samples

    Content type
    application/json
    Example
    {
    • "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10",
    • "user": "trustgraph",
    • "collection": "default"
    }

    Response samples

    Content type
    application/json
    Example
    {}

    Import/Export

    Bulk data import and export

    -

    Stream document content from library

    Stream document content from library

    Streams the raw content of a document stored in the library. +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Streams the raw content of a document stored in the library. Returns the document content in chunked transfer encoding.

    Parameters

      +
    • user: User identifier (required)
    • document-id: Document IRI to retrieve (required)
    • chunk-size: Size of each response chunk in bytes (optional, default: 1MB)
    -
    Authorizations:
    bearerAuth
    query Parameters
    document-id
    required
    string
    Example: document-id=urn:trustgraph:doc:abc123

    Document IRI to retrieve

    -
    chunk-size
    integer
    Default: 1048576

    Chunk size in bytes (default 1MB)

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    Import Core - bulk import triples and embeddings

    Authorizations:
    bearerAuth
    query Parameters
    user
    required
    string
    Example: user=trustgraph

    User identifier

    +
    document-id
    required
    string
    Example: document-id=urn:trustgraph:doc:abc123

    Document IRI to retrieve

    +
    chunk-size
    integer
    Default: 1048576

    Chunk size in bytes (default 1MB)

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    Import Core - bulk import triples and embeddings

    Import knowledge cores in bulk using streaming MessagePack format.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Import knowledge cores in bulk using streaming MessagePack format.

    Import Core Overview

    Bulk data import for knowledge graph:

      @@ -3301,6 +3180,7 @@ No response body - returns 202 Accepted.</p> "m": { // Metadata "i": "core-id", // Knowledge core ID "m": [...], // Metadata triples array + "u": "user", // User "c": "collection" // Collection }, "t": [...] // Triples array @@ -3311,6 +3191,7 @@ No response body - returns 202 Accepted.</p> "m": { // Metadata "i": "core-id", "m": [...], + "u": "user", "c": "collection" }, "e": [ // Entities array @@ -3324,6 +3205,7 @@ No response body - returns 202 Accepted.</p>

      Query Parameters

      • id: Knowledge core ID
      • +
      • user: User identifier

      Streaming

      Multiple messages can be sent in stream. @@ -3336,19 +3218,21 @@ No response body - returns 202 Accepted.

    • Bulk loading: Initial knowledge base population
    • Replication: Copy knowledge cores
    -
    Authorizations:
    bearerAuth
    query Parameters
    id
    required
    string
    Example: id=core-123

    Knowledge core ID to import

    -
    Request Body schema: application/msgpack
    required
    string <binary>

    MessagePack stream of knowledge data

    -

    Responses

    Response samples

    Content type
    application/json
    { }

    Export Core - bulk export triples and embeddings

    Authorizations:
    bearerAuth
    query Parameters
    id
    required
    string
    Example: id=core-123

    Knowledge core ID to import

    +
    user
    required
    string
    Example: user=alice

    User identifier

    +
    Request Body schema: application/msgpack
    required
    string <binary>

    MessagePack stream of knowledge data

    +

    Responses

    Response samples

    Content type
    application/json
    { }

    Export Core - bulk export triples and embeddings

    Export knowledge cores in bulk using streaming MessagePack format.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Export knowledge cores in bulk using streaming MessagePack format.

    Export Core Overview

    Bulk data export for knowledge graph:

      @@ -3423,6 +3310,7 @@ No response body - returns 202 Accepted.

      "m": { // Metadata "i": "core-id", // Knowledge core ID "m": [...], // Metadata triples array + "u": "user", // User "c": "collection" // Collection }, "t": [...] // Triples array @@ -3433,6 +3321,7 @@ No response body - returns 202 Accepted.

      "m": { // Metadata "i": "core-id", "m": [...], + "u": "user", "c": "collection" }, "e": [ // Entities array @@ -3449,6 +3338,7 @@ No response body - returns 202 Accepted.

      Query Parameters

      • id: Knowledge core ID to export
      • +
      • user: User identifier

      Streaming

      Data streamed incrementally:

      @@ -3466,19 +3356,21 @@ No response body - returns 202 Accepted.

    • Replication: Copy knowledge cores
    • Analysis: External processing
    -
    Authorizations:
    bearerAuth
    query Parameters
    id
    required
    string
    Example: id=core-123

    Knowledge core ID to export

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    WebSocket

    Authorizations:
    bearerAuth
    query Parameters
    id
    required
    string
    Example: id=core-123

    Knowledge core ID to export

    +
    user
    required
    string
    Example: user=alice

    User identifier

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    WebSocket

    WebSocket interfaces

    -

    WebSocket - multiplexed service interface

    WebSocket - multiplexed service interface

    WebSocket interface providing multiplexed access to all TrustGraph services over a single persistent connection.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    WebSocket interface providing multiplexed access to all TrustGraph services over a single persistent connection.

    Overview

    The WebSocket API provides access to the same services as the REST API but with:

      @@ -3637,7 +3529,7 @@ All subsequent requests operate within that workspace context.</p>

      Message Protocol

      All messages are JSON objects with the following structure:

      Request Message Format

      -

      Workspace-Scoped Service Request (no flow parameter):

      +

      Global Service Request (no flow parameter):

      {
         "id": "req-123",
         "service": "config",
      @@ -3647,7 +3539,7 @@ All subsequent requests operate within that workspace context.</p>
         }
       }
       
      -

      Flow-Scoped Service Request (with flow parameter):

      +

      Flow-Hosted Service Request (with flow parameter):

      {
         "id": "req-456",
         "service": "agent",
      @@ -3662,7 +3554,7 @@ All subsequent requests operate within that workspace context.</p>
       
      • id (string, required): Client-generated unique identifier for this request within the session. Used to match responses to requests.
      • service (string, required): Service identifier (e.g., "config", "agent", "document-rag"). Same as {kind} in REST URLs.
      • -
      • flow (string, optional): Flow ID for flow-scoped services. Omit for workspace-scoped and global services.
      • +
      • flow (string, optional): Flow ID for flow-hosted services. Omit for global services.
      • request (object, required): Service-specific request payload. Same structure as REST API request body.

      Response Message Format

      @@ -3709,7 +3601,7 @@ All subsequent requests operate within that workspace context.</p>
    {"service": "agent", "flow": "my-flow"}
    -

    Workspace-Scoped Services (no flow parameter, workspace from token):

    +

    Global Services (no flow parameter):

    • config - Configuration management
    • flow - Flow lifecycle and blueprints
    • @@ -3717,7 +3609,7 @@ All subsequent requests operate within that workspace context.</p>
    • knowledge - Knowledge graph core management
    • collection-management - Collection metadata
    -

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

    +

    Flow-Hosted Services (require flow parameter):

    • AI services: agent, text-completion, prompt, document-rag, graph-rag
    • Embeddings: embeddings, graph-embeddings, document-embeddings
    • @@ -3751,11 +3643,11 @@ See individual service documentation for detailed request/response formats.

      The end-of-stream flag (or service-specific completion flag) indicates the final message.

      Authentication

      -

      The /api/v1/socket endpoint uses in-band authentication. -The WebSocket handshake is accepted unconditionally. After -connecting, the client sends a bearer token as the first frame. -The gateway resolves the token to an identity and workspace. -All subsequent requests operate within that workspace context.

      +

      When GATEWAY_SECRET is set, include bearer token:

      +
        +
      • As query parameter: ws://localhost:8088/api/v1/socket?token=<token>
      • +
      • Or in WebSocket subprotocol header
      • +

      Benefits Over REST

      • Lower latency: No TCP/TLS handshake per request
      • @@ -3764,21 +3656,21 @@ All subsequent requests operate within that workspace context.

      • True streaming: Bidirectional real-time communication
      • Efficient multiplexing: Concurrent operations without connection pooling
      -
    Authorizations:
    bearerAuth
    header Parameters
    Upgrade
    required
    string
    Value: "websocket"

    WebSocket upgrade header

    -
    Connection
    required
    string
    Value: "Upgrade"

    Connection upgrade header

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    Metrics

    Authorizations:
    bearerAuth
    header Parameters
    Upgrade
    required
    string
    Value: "websocket"

    WebSocket upgrade header

    +
    Connection
    required
    string
    Value: "Upgrade"

    Connection upgrade header

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    Metrics

    System metrics and monitoring

    -

    Metrics - Prometheus metrics endpoint

    Metrics - Prometheus metrics endpoint

    Proxy to Prometheus metrics for system monitoring.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Proxy to Prometheus metrics for system monitoring.

    Metrics Overview

    Exposes system metrics via Prometheus format:

      @@ -3846,29 +3738,29 @@ metric_name{labelPath Parameter

      The {path} parameter allows querying specific Prometheus endpoints or metrics if the backend Prometheus supports it.

      -
    Authorizations:
    bearerAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    Metrics - Prometheus metrics with path

    Proxy to Prometheus metrics with optional path parameter.

    -
    Authorizations:
    bearerAuth
    path Parameters
    path
    required
    string
    Example: query

    Path to specific metrics endpoint

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }
    +
    Authorizations:
    bearerAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }

    Metrics - Prometheus metrics with path

    Proxy to Prometheus metrics with optional path parameter.

    +
    Authorizations:
    bearerAuth
    path Parameters
    path
    required
    string
    Example: query

    Path to specific metrics endpoint

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "error": "Unauthorized"
    }