TrustGraph API Gateway (1.8)

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.

list

List all configuration items of a specific type (e.g., all flows, all prompts).

get

Retrieve specific configuration items by type and key.

put

Create or update configuration values.

delete

Delete configuration items.

Configuration Types

• flow - Flow instance definitions
• flow-blueprint - Flow blueprint definitions (stored separately from flow instances)
• prompt - Prompt templates
• token-cost - Model token pricing
• parameter-type - Parameter type definitions
• interface-description - Interface descriptions
• Custom types as needed

Important Distinction

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

• Use config service to store/retrieve flow definitions
• Use flow service to start/stop/manage running flows

Manage flow instances and blueprints.

Important Distinction

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

• Use flow service to start/stop/manage running flows
• Use config service to store/retrieve flow definitions

Flow Instance Operations

start-flow

Start a new flow instance from a blueprint. The blueprint must exist (either built-in or created via put-blueprint).

Parameters are resolved from:

1. User-provided values (--param)
2. Default values from parameter type definitions
3. Controlled-by relationships

stop-flow

Stop a running flow instance. This terminates all processors and releases resources.

list-flows

List all currently running flow instances.

get-flow

Get details of a running flow including its configuration, parameters, and interface queue names.

Blueprint Operations

list-blueprints

List all available flow blueprints (built-in and custom).

get-blueprint

Retrieve a blueprint definition showing its structure, parameters, processors, and interfaces.

put-blueprint

Create or update a flow blueprint definition.

Blueprints define:

• Class processors: Shared across all instances of this blueprint
• Flow processors: Unique to each flow instance
• Interfaces: Entry points for external systems
• Parameters: Configurable values for customization

delete-blueprint

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

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

Document Library

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

• Added with metadata for organization
• Queried and filtered by criteria
• Processed through flows on-demand or continuously
• Tracked for processing status

Operations

add-document

Add a document to the library with metadata (URL, title, author, etc.). Documents can be added by URL or with inline content.

remove-document

Remove a document from the library by document ID or URL.

list-documents

List all documents in the library, optionally filtered by criteria.

start-processing

Start processing library documents through a flow. Documents are queued for processing and handled asynchronously.

stop-processing

Stop ongoing library document processing.

list-processing

List current processing tasks and their status.

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

Knowledge Cores

Knowledge cores are the foundational storage units for:

• Triples: RDF triples representing knowledge graph data
• Graph Embeddings: Vector embeddings for entities
• Metadata: Descriptive information about the knowledge

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

Operations

list-kg-cores

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.

put-kg-core

Store triples and/or graph embeddings. Creates new core or updates existing. Can store triples only, embeddings only, or both together.

delete-kg-core

Delete a knowledge core by ID. Removes all associated data.

load-kg-core

Load a knowledge core into a running flow's collection. Makes the data available for querying within that flow instance.

unload-kg-core

Unload a knowledge core from a flow's collection. Removes data from flow instance but doesn't delete the core.

Streaming Responses

The get-kg-core operation streams data in chunks:

1. Multiple messages with triples or graph-embeddings
2. Final message with eos: true to signal completion

Manage collection metadata for organizing documents and knowledge.

Collections

Collections are organizational units for grouping:

• Documents in the librarian
• Knowledge cores
• User data

Each collection has:

• 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 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 user and collection ID. This removes the metadata but typically does not delete the associated data (documents, knowledge cores).

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

Agent Overview

The agent service provides a conversational AI that:

• Understands natural language questions
• Reasons about problems using thoughts
• Takes actions to gather information
• Provides coherent answers

Request Format

Send a question with optional:

• state: Continue from previous conversation
• history: Previous agent steps for context
• group: Collaborative agent identifiers
• streaming: Enable streaming responses

Response Modes

Streaming Mode (streaming: true)

Responses arrive as chunks with chunk-type:

• thought: Agent's reasoning process
• action: Action being taken
• observation: Result from action
• answer: Final response to user
• error: Error occurred

Each chunk may have multiple messages. Check flags:

• end-of-message: Current chunk type complete
• end-of-dialog: Entire conversation complete

Legacy Mode (streaming: false)

Single response with:

• answer: Complete answer
• thought: Reasoning (if any)
• observation: Observations (if any)

Multi-turn Conversations

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

Retrieval-Augmented Generation over document embeddings.

Document RAG Overview

Document RAG combines:

1. Retrieval: Search document embeddings using semantic similarity
2. Generation: Use LLM to synthesize answer from retrieved documents

This provides grounded answers based on your document corpus.

Query Process

1. Convert query to embedding
2. Search document embeddings for most similar chunks
3. Retrieve top N document chunks (configurable via doc-limit)
4. Pass query + retrieved context to LLM
5. Generate answer grounded in documents

Streaming

Enable streaming: true to receive the answer as it's generated:

• Multiple messages with response content
• Final message with end-of-stream: true

Without streaming, returns complete answer in single response.

Parameters

• doc-limit: Controls retrieval depth (1-100, default 20)
  • Higher = more context but slower
  • Lower = faster but may miss relevant info
• collection: Target specific document collection
• user: Multi-tenant isolation

Retrieval-Augmented Generation over knowledge graph.

Graph RAG Overview

Graph RAG combines:

1. Retrieval: Find relevant entities and subgraph from knowledge graph
2. Generation: Use LLM to reason over graph structure and generate answer

This provides graph-aware answers that leverage relationships and structure.

Query Process

1. Identify relevant entities from query (using embeddings)
2. Retrieve connected subgraph around entities
3. Optionally traverse paths up to max-path-length hops
4. Limit subgraph size to stay within context window
5. Pass query + graph structure to LLM
6. Generate answer incorporating graph relationships

Streaming

Enable streaming: true to receive the answer as it's generated:

• Multiple messages with response content
• Final message with end-of-stream: true

Without streaming, returns complete answer in single response.

Parameters

Control retrieval scope with multiple knobs:

• entity-limit: How many starting entities to find (1-200, default 50)
• triple-limit: Triples per entity (1-100, default 30)
• max-subgraph-size: Total subgraph cap (10-5000, default 1000)
• max-path-length: Graph traversal depth (1-5, default 2)

Higher limits = more context but:

• Slower retrieval
• Larger context for LLM
• May hit context window limits

Use Cases

Best for queries requiring:

• Relationship understanding ("How are X and Y connected?")
• Multi-hop reasoning ("What's the path from A to B?")
• Structural analysis ("What are the main entities related to X?")

Direct text completion using LLM without retrieval augmentation.

Text Completion Overview

Pure LLM generation for:

• General knowledge questions
• Creative writing
• Code generation
• Analysis and reasoning
• Any task not requiring specific document/graph context

System vs Prompt

• system: Sets LLM behavior, role, constraints
  • "You are a helpful assistant"
  • "You are an expert Python developer"
  • "Respond in JSON format"
• prompt: The actual user request/question

Streaming

Enable streaming: true to receive tokens as generated:

• Multiple messages with partial response
• Final message with end-of-stream: true

Without streaming, returns complete response in single message.

Token Counting

Response includes token usage:

• in-token: Input tokens (system + prompt)
• out-token: Generated tokens
• Useful for cost tracking and optimization

When to Use

Use text-completion when:

• No specific context needed (general knowledge)
• System prompt provides sufficient context
• Want direct control over prompting

Use document-rag/graph-rag when:

• Need to ground response in specific documents
• Want to leverage knowledge graph relationships
• Require citations or provenance

Execute stored prompt templates with variable substitution.

Prompt Service Overview

The prompt service enables:

• Reusable prompt templates stored in configuration
• Variable substitution for dynamic prompts
• Consistent prompt engineering across requests
• Text or structured object outputs

Template System

Prompts are stored via config service (/api/v1/config) with:

• id: Unique prompt identifier
• template: Prompt text with {variable} placeholders
• system: Optional system prompt
• output_format: "text" or "object"

Example template:

Summarize the following document in {max_length} words:

{document}

Variable Substitution

Two ways to pass variables:

1. terms (explicit JSON strings):

   {
     "terms": {
       "document": "\"Text here...\"",
       "max_length": "\"200\""
     }
   }
   

2. variables (auto-converted):

   {
     "variables": {
       "document": "Text here...",
       "max_length": 200
     }
   }
   

Output Types

• text: Plain text response in text field
• object: Structured JSON in object field (as string)

Streaming

Enable streaming: true to receive response incrementally.

Use Cases

• Document summarization
• Entity extraction
• Classification tasks
• Data transformation
• Any repeatable LLM task with consistent prompting

Convert text to embedding vectors for semantic similarity search.

Embeddings Overview

Embeddings transform text into dense vector representations that:

• Capture semantic meaning
• Enable similarity comparisons via cosine distance
• Support semantic search and retrieval
• Power RAG systems

Use Cases

• Document indexing: Convert documents to vectors for storage
• Query encoding: Convert search queries for similarity matching
• Semantic similarity: Find related texts via vector distance
• Clustering: Group similar content
• Classification: Use as features for ML models

Vector Dimensions

Dimension count depends on embedding model:

• text-embedding-ada-002: 1536 dimensions
• text-embedding-3-small: 1536 dimensions
• text-embedding-3-large: 3072 dimensions
• Custom models: Varies

Single Request

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

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

MCP Tool Overview

MCP tools provide agent capabilities through standardized protocol:

• Search tools: Web search, document search
• Data tools: Database queries, API calls
• Action tools: File operations, system commands
• Integration tools: Third-party service connectors

Tools extend agent capabilities beyond pure LLM generation.

Tool Execution

Tools are:

1. Registered via MCP protocol
2. Discovered by agent
3. Called with structured parameters
4. Return text or structured results

Request Format

• name: Tool identifier (e.g., "search", "calculator", "weather")
• parameters: Tool-specific arguments as JSON object

Response Format

Tools can return:

• text: Plain text result (simple tools)
• object: Structured JSON result (complex tools)

Tool Registration

Tools are registered via MCP server configuration:

• Define tool schema (name, parameters, description)
• Implement tool handler
• Register with MCP server
• Agent discovers and uses tool

Use Cases

• Web search: Find external information
• Calculator: Perform calculations
• Database query: Retrieve structured data
• API integration: Call external services
• File operations: Read/write files
• Code execution: Run scripts

Query knowledge graph using subject-predicate-object patterns.

Triples Query Overview

Query RDF triples with flexible pattern matching:

• Specify subject, predicate, and/or object
• Any combination of filters (all optional)
• Returns matching triples up to limit

Pattern Matching

Pattern syntax supports:

• All triples: Omit all filters (returns everything up to limit)
• Subject match: Specify s only (all triples about that subject)
• Predicate match: Specify p only (all uses of that property)
• Object match: Specify o only (all triples with that value)
• Combinations: Any combination of s/p/o

RDF Value Format

Each component (s/p/o) uses RdfValue format:

• Entity/URI: {"v": "https://example.com/entity", "e": true}
• Literal: {"v": "Some text", "e": false}

Query Examples

Find all properties of an entity:

{"s": {"v": "https://example.com/person/alice", "e": true}}

Find all instances of a type:

{
  "p": {"v": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type", "e": true},
  "o": {"v": "https://example.com/type/Person", "e": true}
}

Find specific relationship:

{
  "s": {"v": "https://example.com/person/alice", "e": true},
  "p": {"v": "https://example.com/knows", "e": true}
}

Performance

• Default limit: 10,000 triples
• Max limit: 100,000 triples
• More specific patterns = faster queries
• Consider limit for large result sets

Query knowledge graph using GraphQL for object-oriented data access.

Objects Query Overview

GraphQL interface to knowledge graph:

• Schema-driven: Predefined types and relationships
• Flexible queries: Request exactly what you need
• Nested data: Traverse relationships in single query
• Type-safe: Strong typing with introspection

Abstracts RDF triples into familiar object model.

GraphQL Benefits

Compared to triples query:

• Developer-friendly: Objects instead of triples
• Efficient: Get related data in one query
• Typed: Schema defines available fields
• Discoverable: Introspection for tooling

Query Structure

Standard GraphQL query format:

query OperationName($var: Type!) {
  fieldName(arg: $var) {
    subField1
    subField2
    nestedObject {
      nestedField
    }
  }
}

Variables

Pass variables for parameterized queries:

{
  "query": "query GetPerson($id: ID!) { person(id: $id) { name } }",
  "variables": {"id": "https://example.com/person/alice"}
}

Error Handling

GraphQL distinguishes:

• Field errors: Invalid query, missing fields (in errors array)
• System errors: Connection issues, timeouts (in error object)

Partial data may be returned with field errors.

Schema Definition

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

Convert natural language questions to structured GraphQL queries.

NLP Query Overview

Transforms user questions into executable GraphQL:

• Natural input: Ask questions in plain English
• Structured output: Get GraphQL query + variables
• Schema-aware: Uses knowledge graph schema
• Confidence scoring: Know how well question was understood

Enables non-technical users to query knowledge graph.

Process

1. Parse natural language question
2. Identify entities and relationships
3. Map to GraphQL schema types
4. Generate query with variables
5. Return query + confidence score

Using Results

Generated query can be:

• Executed via objects query service
• Inspected and modified if needed
• Cached for similar questions

Example workflow:

1. User asks: "Who does Alice know?"
2. NLP Query generates GraphQL
3. Execute via /api/v1/flow/{flow}/service/objects
4. Return results to user

Schema Detection

Response includes detected-schemas array showing:

• Which types were identified
• What entities were matched
• Schema coverage of question

Helps understand query scope.

Confidence Scores

• 0.9-1.0: High confidence, likely correct
• 0.7-0.9: Good confidence, probably correct
• 0.5-0.7: Medium confidence, may need review
• < 0.5: Low confidence, likely incorrect

Low scores suggest:

• Ambiguous question
• Missing schema coverage
• Complex query structure

Ask natural language questions and get results directly.

Structured Query Overview

Combines two operations in one call:

1. NLP Query: Generate GraphQL from question
2. Objects Query: Execute generated query
3. Return Results: Direct answer data

Simplest way to query knowledge graph with natural language.

Comparison with Other Services

Structured Query (this service)

• Input: Natural language question
• Output: Query results (data)
• Use when: Want simple, direct answers

NLP Query + Objects Query (separate calls)

• Step 1: Convert question → GraphQL
• Step 2: Execute GraphQL → results
• Use when: Need to inspect/modify query before execution

Triples Query (low-level)

• Input: RDF pattern
• Output: Matching triples
• Use when: Need precise control over graph queries

Response Format

Returns standard GraphQL response:

• data: Query results (null if error)
• errors: Field-level errors (array of strings)
• error: System-level error (generation or execution failure)

Error Handling

Three types of errors:

1. Query generation failed: Couldn't understand question
   • Error in error object
   • data = null
2. Query execution failed: Generated query had errors
   • Errors in errors array
   • data may be partial
3. System error: Infrastructure issue
   • Error in error object

Performance

Convenience vs control trade-off:

• Faster development: One call instead of two
• Less control: Can't inspect/modify generated query
• Simpler code: No need to handle intermediate steps

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

Structured Diag Overview

Helps process unknown structured data:

• Detect format: Identify CSV, JSON, or XML
• Generate schema: Create descriptor from sample
• Match schemas: Find existing schemas that fit data
• Full diagnosis: Complete analysis in one call

Essential for data ingestion pipelines.

Operations

detect-type

Identify data format from sample:

• Input: Data sample
• Output: Format (csv/json/xml) + confidence
• Use when: Format is unknown

generate-descriptor

Create schema descriptor:

• Input: Sample + known type
• Output: Field definitions, types, structure
• Use when: Need to understand data structure

diagnose (recommended)

Combined analysis:

• Input: Data sample
• Output: Format + descriptor + metadata
• Use when: Starting from scratch

schema-selection

Find matching schemas:

• Input: Data sample
• Output: List of schema IDs that match
• Use when: Have existing schemas, need to match data

Data Types

Supported formats:

• CSV: Comma-separated values (or custom delimiter)
• JSON: JSON objects or arrays
• XML: XML documents

Options

Format-specific options:

• CSV: delimiter, has_header, quote_char
• JSON: array_path (for nested arrays)
• XML: root_element, record_path

Workflow Example

1. Receive unknown data file
2. Call diagnose operation with sample
3. Get format + schema descriptor
4. Use descriptor to process full dataset
5. Load data via document-load or text-load

Query graph embeddings to find similar entities by vector similarity.

Graph Embeddings Query Overview

Find entities semantically similar to a query vector:

• Input: Query embedding vector
• Search: Compare against stored entity embeddings
• Output: Most similar entities (RDF URIs)

Core component of graph RAG retrieval.

Use Cases

• Entity discovery: Find related entities
• Concept expansion: Discover similar concepts
• Graph exploration: Navigate by semantic similarity
• RAG retrieval: Get entities for context

Process

1. Obtain query embedding (via embeddings service)
2. Query stored entity embeddings
3. Calculate cosine similarity
4. Return top N most similar entities
5. Use entities to retrieve triples/subgraph

Similarity Scoring

Uses cosine similarity between vectors:

• Results ordered by similarity (most similar first)
• No explicit similarity scores returned
• Limit controls result count

Entity Format

Returns RDF values (entities):

• URI entities: {v: "https://...", e: true}
• These are references to knowledge graph entities
• Use with triples query to get entity details

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

Document Embeddings Query Overview

Find document chunks semantically similar to a query vector:

• Input: Query embedding vector
• Search: Compare against stored chunk embeddings
• Output: Most similar text chunks

Core component of document RAG retrieval.

Use Cases

• Document retrieval: Find relevant passages
• Semantic search: Search by meaning not keywords
• Context gathering: Get text for RAG
• Similar content: Discover related documents

Process

1. Obtain query embedding (via embeddings service)
2. Query stored document chunk embeddings
3. Calculate cosine similarity
4. Return top N most similar chunks
5. Use chunks as context for generation

Chunking

Documents are split into chunks during indexing:

• Typical size: 200-1000 tokens
• Overlap between chunks for continuity
• Each chunk has own embedding

Queries return individual chunks, not full documents.

Similarity Scoring

Uses cosine similarity:

• Results ordered by similarity
• No explicit scores in response
• Limit controls result count

Output Format

Returns text chunks as strings:

• Raw chunk text
• No metadata (source, position, etc.)
• Use for LLM context directly

Load text documents into processing pipeline for indexing and embedding.

Text Load Overview

Fire-and-forget document loading:

• Input: Text content (base64 encoded)
• Process: Chunk, embed, store
• Output: None (202 Accepted)

Asynchronous processing - document queued for background processing.

Processing Pipeline

Text documents go through:

1. Chunking: Split into overlapping chunks
2. Embedding: Generate vectors for each chunk
3. Storage: Store chunks + embeddings
4. Indexing: Make searchable via document-embeddings query

Pipeline runs asynchronously after request returns.

Text Format

Text must be base64 encoded:

text_content = "This is the document..."
encoded = base64.b64encode(text_content.encode('utf-8'))

Default charset is UTF-8, specify charset if different.

Metadata

Optional RDF triples describing document:

• Title, author, date
• Source URL
• Custom properties
• Used for organization and retrieval

Use Cases

• Document ingestion: Add documents to knowledge base
• Bulk loading: Process multiple documents
• Content updates: Replace existing documents
• Library integration: Load from document library

No Response Data

Returns 202 Accepted immediately:

• Document queued for processing
• No synchronous result
• No processing status
• Check document-embeddings query later to verify indexed

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

Document Load Overview

Fire-and-forget binary document loading:

• Input: Document data (base64 encoded)
• Process: Extract text, chunk, embed, store
• Output: None (202 Accepted)

Asynchronous processing for PDF and other binary formats.

Processing Pipeline

Documents go through:

1. Text extraction: PDF→text, DOCX→text, etc.
2. Chunking: Split into overlapping chunks
3. Embedding: Generate vectors for each chunk
4. Storage: Store chunks + embeddings
5. Indexing: Make searchable

Pipeline runs asynchronously.

Supported Formats

• PDF: Portable Document Format
• DOCX: Microsoft Word
• HTML: Web pages
• Other formats via extractors

Format detected from content, not extension.

Binary Encoding

Documents must be base64 encoded:

with open('document.pdf', 'rb') as f:
    doc_bytes = f.read()
encoded = base64.b64encode(doc_bytes).decode('utf-8')

Metadata

Optional RDF triples:

• Document properties
• Source information
• Custom attributes

Use Cases

• PDF ingestion: Process research papers
• Document libraries: Index document collections
• Content migration: Import from other systems
• Automated processing: Batch document loading

No Response Data

Returns 202 Accepted immediately:

• Document queued
• Processing happens asynchronously
• No status tracking
• Query later to verify indexed

Import knowledge cores in bulk using streaming MessagePack format.

Import Core Overview

Bulk data import for knowledge graph:

• Format: MessagePack streaming
• Content: Triples and/or graph embeddings
• Target: Global knowledge storage
• Use: Backup restoration, data migration, bulk loading

MessagePack Protocol

Request body is MessagePack stream with message tuples:

Triple Message

("t", {
  "m": {              // Metadata
    "i": "core-id",   // Knowledge core ID
    "m": [...],       // Metadata triples array
    "u": "user",      // User
    "c": "collection" // Collection
  },
  "t": [...]          // Triples array
})

Graph Embeddings Message

("ge", {
  "m": {              // Metadata
    "i": "core-id",
    "m": [...],
    "u": "user",
    "c": "collection"
  },
  "e": [              // Entities array
    {
      "e": {"v": "uri", "e": true},  // Entity RdfValue
      "v": [0.1, 0.2, ...]             // Vectors
    }
  ]
})

Query Parameters

• id: Knowledge core ID
• user: User identifier

Streaming

Multiple messages can be sent in stream. Each message processed as received. No response body - returns 202 Accepted.

Use Cases

• Backup restoration: Restore from export
• Data migration: Move data between systems
• Bulk loading: Initial knowledge base population
• Replication: Copy knowledge cores

Export knowledge cores in bulk using streaming MessagePack format.

Export Core Overview

Bulk data export for knowledge graph:

• Format: MessagePack streaming
• Content: Triples and graph embeddings
• Source: Global knowledge storage
• Use: Backups, data migration, archival

MessagePack Protocol

Response body is MessagePack stream with message tuples:

Triple Message

("t", {
  "m": {              // Metadata
    "i": "core-id",   // Knowledge core ID
    "m": [...],       // Metadata triples array
    "u": "user",      // User
    "c": "collection" // Collection
  },
  "t": [...]          // Triples array
})

Graph Embeddings Message

("ge", {
  "m": {              // Metadata
    "i": "core-id",
    "m": [...],
    "u": "user",
    "c": "collection"
  },
  "e": [              // Entities array
    {
      "e": {"v": "uri", "e": true},  // Entity RdfValue
      "v": [0.1, 0.2, ...]             // Vectors
    }
  ]
})

End of Stream Message

("eos", {})

Query Parameters

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

Streaming

Data streamed incrementally:

• Triples sent first
• Graph embeddings sent next
• EOS marker signals completion

Client should process messages as received.

Use Cases

• Backups: Export for disaster recovery
• Data migration: Move to another system
• Archival: Long-term storage
• Replication: Copy knowledge cores
• Analysis: External processing