mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-07-23 20:21:03 +02:00
128 lines
3.7 KiB
YAML
128 lines
3.7 KiB
YAML
openapi: 3.1.0
|
|
|
|
info:
|
|
title: TrustGraph API Gateway
|
|
version: 1.8.0
|
|
description: |
|
|
REST API for TrustGraph - an AI-powered knowledge graph and RAG system.
|
|
|
|
## Overview
|
|
|
|
The API provides access to:
|
|
- **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
|
|
|
|
## Service Types
|
|
|
|
### Global Services
|
|
Fixed endpoints accessible via `/api/v1/{kind}`:
|
|
- `config` - Configuration management
|
|
- `flow` - Flow lifecycle and blueprints
|
|
- `librarian` - Document library management
|
|
- `knowledge` - Knowledge graph core management
|
|
- `collection-management` - Collection metadata
|
|
|
|
### 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
|
|
- Query: triples, objects, nlp-query, structured-query
|
|
- Data loading: text-load, document-load
|
|
- Utilities: mcp-tool, structured-diag
|
|
|
|
## 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
|
|
|
|
All endpoints may return errors in this format:
|
|
```json
|
|
{
|
|
"error": {
|
|
"type": "gateway-error",
|
|
"message": "Timeout"
|
|
}
|
|
}
|
|
```
|
|
|
|
contact:
|
|
name: TrustGraph Project
|
|
url: https://trustgraph.ai
|
|
license:
|
|
name: Apache 2.0
|
|
url: https://www.apache.org/licenses/LICENSE-2.0.html
|
|
|
|
servers:
|
|
- url: http://localhost:8088
|
|
description: Local development server
|
|
- url: http://localhost:8088/api/v1
|
|
description: API v1 base path
|
|
|
|
security:
|
|
- bearerAuth: []
|
|
|
|
tags:
|
|
- name: Config
|
|
description: Configuration management (global service)
|
|
- name: Flow
|
|
description: Flow lifecycle and blueprint management (global service)
|
|
- name: Librarian
|
|
description: Document library management (global service)
|
|
- name: Knowledge
|
|
description: Knowledge graph core management (global service)
|
|
- name: Collection
|
|
description: Collection metadata management (global service)
|
|
- name: AI Services
|
|
description: AI services hosted within flows
|
|
- name: Import/Export
|
|
description: Bulk data import and export
|
|
- name: WebSocket
|
|
description: WebSocket interfaces
|
|
- name: Metrics
|
|
description: System metrics and monitoring
|
|
|
|
paths:
|
|
/api/v1/config:
|
|
$ref: './paths/config.yaml'
|
|
/api/v1/flow:
|
|
$ref: './paths/flow.yaml'
|
|
# More services will be added here as we build them
|
|
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
$ref: './security/bearerAuth.yaml'
|
|
|
|
parameters:
|
|
# Common parameters will be referenced here
|
|
# FlowId:
|
|
# $ref: './components/parameters/FlowId.yaml'
|
|
|
|
responses:
|
|
# Common responses will be referenced here
|
|
# Unauthorized:
|
|
# $ref: './components/responses/Unauthorized.yaml'
|
|
# Error:
|
|
# $ref: './components/responses/Error.yaml'
|
|
|
|
schemas:
|
|
# Schemas will be referenced here as we build them
|
|
# Common:
|
|
# RdfValue:
|
|
# $ref: './components/schemas/common/RdfValue.yaml'
|
|
# Services:
|
|
# ConfigRequest:
|
|
# $ref: './components/schemas/config/ConfigRequest.yaml'
|