mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-05-30 01:35:14 +02:00

- Update API specs for 2.4 (#960)
- Update API docs
- Regenerate Python docs

2026-05-28 17:55:51 +01:00

3.8 KiB

Raw Blame History

TrustGraph OpenAPI Specification

This directory contains the modular OpenAPI 3.1 specification for the TrustGraph REST API Gateway.

Authentication

Clients authenticate by passing an opaque bearer token in the Authorization header. The gateway resolves the token to an authenticated identity and an associated workspace. Tokens are obtained via the IAM service (e.g. tg-login or tg-create-api-key).

Service Tiers

API services are organized into three tiers based on their scoping:

Global services

These services are not scoped to a workspace. They manage system-wide resources.

IAM — user management, authentication, API key lifecycle

Workspace-scoped services

These services operate within the workspace associated with the authenticated token. The workspace is resolved by the gateway from the bearer token — it is not passed as an explicit parameter.

Config — configuration management (prompts, token costs, etc.)
Librarian — document library management
Knowledge — knowledge graph core management
Collection Management — collection metadata
Flow — flow lifecycle and blueprint management

Flow-scoped services

These services require a flow parameter identifying the processing flow to use, in addition to the workspace context from the token.

Agent — agentic AI interactions
Document RAG — retrieval-augmented generation over documents
Graph RAG — retrieval-augmented generation over knowledge graphs
Text Completion — LLM text completion
Prompt — prompt template expansion
Embeddings — vector embedding generation
SPARQL Query — SPARQL queries against the knowledge graph
Graph Embeddings — knowledge graph embedding queries
Document Embeddings — document embedding queries
Structured Query — structured data queries
Row Embeddings — structured data embedding queries
Rows Query — row-level data queries
Triples Query — knowledge graph triple queries

Structure

specs/api/
├── openapi.yaml              # Main entry point
├── paths/                    # Endpoint definitions
│   ├── config.yaml
│   ├── flow.yaml
│   ├── flow-services/        # Flow-hosted services
│   └── import-export/
├── components/
│   ├── schemas/              # Request/response schemas
│   │   ├── config/
│   │   ├── flow/
│   │   ├── ai-services/
│   │   ├── common/
│   │   └── errors/
│   ├── parameters/           # Reusable parameters
│   ├── responses/            # Reusable responses
│   └── examples/             # Example payloads
└── security/                 # Security schemes
    └── bearerAuth.yaml

Viewing the Spec

Swagger UI

# Install swagger-ui
npm install -g swagger-ui-watcher

# View in browser
swagger-ui-watcher specs/api/openapi.yaml

Redoc

# Install redoc-cli
npm install -g redoc-cli

# Generate static HTML
redoc-cli bundle specs/api/openapi.yaml -o api-docs.html

# View
open api-docs.html

Online Validators

Upload openapi.yaml to:

Validation

# Install openapi-spec-validator
pip install openapi-spec-validator

# Validate
openapi-spec-validator specs/api/openapi.yaml

Development

When adding a new service:

Create schema files in components/schemas/{service}/
Create path file in paths/ or paths/flow-services/
Add examples if needed
Reference from openapi.yaml
Validate

3.8 KiB Raw Blame History