{
  "openapi": "3.0.3",
  "info": {
    "title": "pgEdge RAG Server API",
    "description": "REST API for querying RAG (Retrieval-Augmented Generation) pipelines",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "/v1",
      "description": "API v1"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "description": "Check if the server is running, and whether each pipeline's LLM providers are reachable",
        "operationId": "getHealth",
        "tags": [
          "System"
        ],
        "responses": {
          "200": {
            "description": "Server is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/live": {
      "get": {
        "summary": "Liveness check",
        "description": "Cheap, dependency-free check that the server process is up and serving; does not ping providers. Suitable for a latency-sensitive liveness probe",
        "operationId": "getLive",
        "tags": [
          "System"
        ],
        "responses": {
          "200": {
            "description": "Server process is up",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LiveResponse"
                }
              }
            }
          }
        }
      }
    },
    "/pipelines": {
      "get": {
        "summary": "List pipelines",
        "description": "Get a list of all available RAG pipelines",
        "operationId": "listPipelines",
        "tags": [
          "Pipelines"
        ],
        "responses": {
          "200": {
            "description": "List of pipelines",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PipelinesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/pipelines/{name}": {
      "post": {
        "summary": "Query pipeline",
        "description": "Execute a RAG query against a specific pipeline",
        "operationId": "queryPipeline",
        "tags": [
          "Pipelines"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "description": "Pipeline name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Query request",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Query response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-Sent Events stream"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Pipeline not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeds the 1 MiB limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/stats": {
      "get": {
        "summary": "Pipeline usage stats",
        "description": "Get cumulative LLM token usage for every pipeline",
        "operationId": "getStats",
        "tags": [
          "System"
        ],
        "responses": {
          "200": {
            "description": "Pipeline usage statistics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorDetail": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code"
          },
          "message": {
            "type": "string",
            "description": "Human-readable description of the failure class. Deliberately coarse: upstream provider error text is never relayed here, because providers echo a truncated form of the submitted API key on an authentication failure. Full detail is written to the server log instead."
          }
        },
        "required": [
          "code",
          "message"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        },
        "required": [
          "error"
        ]
      },
      "Filter": {
        "type": "object",
        "properties": {
          "conditions": {
            "type": "array",
            "description": "Filter conditions to apply",
            "items": {
              "$ref": "#/components/schemas/FilterCondition"
            },
            "maxItems": 50
          },
          "logic": {
            "type": "string",
            "description": "Logical operator to combine conditions: AND or OR (default: AND)",
            "default": "AND",
            "enum": [
              "AND",
              "OR"
            ]
          }
        },
        "required": [
          "conditions"
        ]
      },
      "FilterCondition": {
        "type": "object",
        "properties": {
          "column": {
            "type": "string",
            "description": "Column name to filter on"
          },
          "operator": {
            "type": "string",
            "description": "Comparison operator",
            "enum": [
              "=",
              "!=",
              "\u003c",
              "\u003e",
              "\u003c=",
              "\u003e=",
              "LIKE",
              "ILIKE",
              "IN",
              "NOT IN",
              "IS NULL",
              "IS NOT NULL"
            ]
          },
          "value": {
            "description": "Value to compare against (not required for IS NULL / IS NOT NULL)"
          }
        },
        "required": [
          "column",
          "operator"
        ]
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "pipelines": {
            "type": "array",
            "description": "Per-pipeline provider connectivity",
            "items": {
              "$ref": "#/components/schemas/PipelineHealth"
            }
          },
          "status": {
            "type": "string",
            "description": "Overall health status: \"healthy\" or \"degraded\" (one or more providers unreachable). Always HTTP 200"
          }
        },
        "required": [
          "status"
        ]
      },
      "LiveResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Liveness status; always \"ok\" when the process is serving"
          }
        },
        "required": [
          "status"
        ]
      },
      "Message": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "description": "Message content"
          },
          "role": {
            "type": "string",
            "description": "Message role (user or assistant)"
          }
        },
        "required": [
          "role",
          "content"
        ]
      },
      "PipelineHealth": {
        "type": "object",
        "properties": {
          "completion": {
            "description": "Completion provider connectivity",
            "$ref": "#/components/schemas/ProviderHealth"
          },
          "embedding": {
            "description": "Embedding provider connectivity",
            "$ref": "#/components/schemas/ProviderHealth"
          },
          "name": {
            "type": "string",
            "description": "Pipeline name"
          }
        },
        "required": [
          "name",
          "embedding",
          "completion"
        ]
      },
      "PipelineInfo": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "Pipeline description"
          },
          "name": {
            "type": "string",
            "description": "Pipeline name"
          }
        },
        "required": [
          "name"
        ]
      },
      "PipelineUsage": {
        "type": "object",
        "properties": {
          "completion": {
            "description": "Cumulative completion token usage",
            "$ref": "#/components/schemas/TokenUsage"
          },
          "description": {
            "type": "string",
            "description": "Pipeline description"
          },
          "embedding": {
            "description": "Cumulative embedding token usage",
            "$ref": "#/components/schemas/TokenUsage"
          },
          "name": {
            "type": "string",
            "description": "Pipeline name"
          }
        },
        "required": [
          "name",
          "embedding",
          "completion"
        ]
      },
      "PipelinesResponse": {
        "type": "object",
        "properties": {
          "pipelines": {
            "type": "array",
            "description": "List of available pipelines",
            "items": {
              "$ref": "#/components/schemas/PipelineInfo"
            }
          }
        },
        "required": [
          "pipelines"
        ]
      },
      "ProviderHealth": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Failure class if unreachable, drawn from a fixed set. Never contains upstream provider error text, since that can include part of the configured API key; see the server log for detail."
          },
          "reachable": {
            "type": "boolean",
            "description": "Whether the provider responded to a connectivity check"
          }
        },
        "required": [
          "reachable"
        ]
      },
      "QueryRequest": {
        "type": "object",
        "properties": {
          "disable_hybrid": {
            "type": "boolean",
            "description": "Skip the keyword-search arm for this request, using vector search alone. Reduces latency and database work. This can only turn hybrid search off: a request cannot enable it where the pipeline configuration has disabled it.",
            "default": false
          },
          "filter": {
            "description": "Structured filter to apply to search results",
            "$ref": "#/components/schemas/Filter"
          },
          "include_sources": {
            "type": "boolean",
            "description": "Request the source documents used to produce the answer. Honoured only if the pipeline is configured with allow_include_sources: true; otherwise the answer is returned without sources and the request still succeeds.",
            "default": false
          },
          "messages": {
            "type": "array",
            "description": "Previous conversation history for context",
            "items": {
              "$ref": "#/components/schemas/Message"
            }
          },
          "query": {
            "type": "string",
            "description": "The question to answer"
          },
          "stream": {
            "type": "boolean",
            "description": "Enable streaming response (SSE)",
            "default": false
          },
          "top_n": {
            "type": "integer",
            "description": "Override default result limit"
          }
        },
        "required": [
          "query"
        ]
      },
      "QueryResponse": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "string",
            "description": "The generated answer"
          },
          "sources": {
            "type": "array",
            "description": "Source documents. Present only when the request set include_sources=true and the pipeline permits it via allow_include_sources.",
            "items": {
              "$ref": "#/components/schemas/Source"
            }
          },
          "tokens_used": {
            "type": "integer",
            "description": "Total tokens consumed"
          }
        },
        "required": [
          "answer",
          "tokens_used"
        ]
      },
      "Source": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "description": "Document content"
          },
          "id": {
            "type": "string",
            "description": "Document identifier"
          },
          "score": {
            "type": "number",
            "format": "double",
            "description": "Relevance score"
          }
        },
        "required": [
          "content",
          "score"
        ]
      },
      "StatsResponse": {
        "type": "object",
        "properties": {
          "pipelines": {
            "type": "array",
            "description": "Per-pipeline cumulative token usage",
            "items": {
              "$ref": "#/components/schemas/PipelineUsage"
            }
          }
        },
        "required": [
          "pipelines"
        ]
      },
      "TokenUsage": {
        "type": "object",
        "description": "Cumulative token usage since client creation or last reset",
        "properties": {
          "cache_creation_input_tokens": {
            "type": "integer",
            "description": "Cumulative tokens used to write to the prompt cache"
          },
          "cache_read_input_tokens": {
            "type": "integer",
            "description": "Cumulative tokens read from the prompt cache"
          },
          "completion_tokens": {
            "type": "integer",
            "description": "Cumulative completion/output tokens"
          },
          "prompt_tokens": {
            "type": "integer",
            "description": "Cumulative prompt/input tokens"
          },
          "total_tokens": {
            "type": "integer",
            "description": "Cumulative total tokens (prompt + completion)"
          }
        },
        "required": [
          "prompt_tokens",
          "completion_tokens",
          "total_tokens"
        ]
      }
    }
  }
}