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:
  # Global services will be added here as we build them
  # /api/v1/config:
  #   $ref: './paths/config.yaml'
  # /api/v1/flow:
  #   $ref: './paths/flow.yaml'
  # etc.

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'