{
  "openapi": "3.1.0",
  "info": {
    "title": "SAIG by Terraxon — Public API",
    "version": "1.0.0",
    "description": "OpenAI-compatible AI governance runtime API. SAIG sits between applications and LLM providers to protect sensitive data, enforce policy, control provider residency, and create signed audit evidence.\n\nThis is a sanitized public reference for customer-facing endpoints only. Internal and admin endpoints are not included.",
    "contact": {
      "name": "Terraxon",
      "url": "https://saig.terraxon.eu",
      "email": "info@terraxon.com"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://api.your-domain.eu",
      "description": "Your SAIG deployment (replace with your actual domain)"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v1/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "summary": "Create a governed chat completion",
        "description": "OpenAI-compatible chat completions endpoint. Every request passes through the SAIG governance pipeline: PII detection, policy evaluation, anonymization, provider routing, and audit evidence creation.",
        "tags": ["Chat Completions"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Basic chat completion",
                  "value": {
                    "model": "saig-default",
                    "messages": [
                      {"role": "user", "content": "Summarize this quarter's results."}
                    ]
                  }
                },
                "sensitive-data": {
                  "summary": "Using sensitive-data model alias",
                  "value": {
                    "model": "saig-sensitive-data",
                    "messages": [
                      {"role": "user", "content": "Draft a summary for client Jan Kos."}
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Governed chat completion response",
            "headers": {
              "X-SAIG-Request-Id": {
                "description": "Unique governance request identifier",
                "schema": {"type": "string", "example": "req_7h2k9abc"}
              },
              "X-SAIG-Policy-Action": {
                "description": "Governance decision: ALLOW, ANONYMIZE, DENY, SYNTHETIC_ONLY",
                "schema": {"type": "string", "enum": ["ALLOW", "ANONYMIZE", "DENY", "SYNTHETIC_ONLY"]}
              },
              "X-SAIG-Risk-Level": {
                "description": "Risk assessment: NONE, LOW, MEDIUM, HIGH, CRITICAL",
                "schema": {"type": "string", "enum": ["NONE", "LOW", "MEDIUM", "HIGH", "CRITICAL"]}
              },
              "X-SAIG-Provider": {
                "description": "LLM provider that served the request",
                "schema": {"type": "string", "example": "azure-openai-eu"}
              },
              "X-SAIG-Model-Alias": {
                "description": "SAIG model alias used",
                "schema": {"type": "string", "example": "saig-default"}
              },
              "X-SAIG-Audit-Receipt-Id": {
                "description": "Audit trail receipt reference",
                "schema": {"type": "string"}
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              }
            }
          },
          "401": {"description": "Missing or invalid Bearer token"},
          "403": {"description": "Request denied by governance policy"},
          "429": {"description": "Rate limit exceeded"},
          "503": {"description": "All providers unavailable (circuit breaker open)"}
        }
      }
    },
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List available models and aliases",
        "description": "Returns available model aliases and their metadata. SAIG model aliases decouple applications from provider-specific model names.",
        "tags": ["Models"],
        "responses": {
          "200": {
            "description": "Model list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                }
              }
            }
          }
        }
      }
    },
    "/v1/capabilities": {
      "get": {
        "operationId": "getCapabilities",
        "summary": "Machine-readable capability matrix",
        "description": "Returns platform version, API version, and feature availability flags. Useful for client auto-discovery and integration testing.",
        "tags": ["Discovery"],
        "responses": {
          "200": {
            "description": "Capability matrix",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capabilities"
                }
              }
            }
          }
        }
      }
    },
    "/version": {
      "get": {
        "operationId": "getVersion",
        "summary": "Version and build information",
        "description": "Returns product version, API version, build metadata, and component versions.",
        "tags": ["Discovery"],
        "responses": {
          "200": {
            "description": "Version information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionInfo"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Health check",
        "description": "Returns service health status. Does not require authentication.",
        "tags": ["Discovery"],
        "security": [],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {"type": "string", "example": "ok"}
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "OIDC Bearer token from Keycloak. All endpoints except /health require authentication."
      }
    },
    "schemas": {
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": {
            "type": "string",
            "description": "Model alias or provider model name",
            "enum": ["saig-default", "saig-fast", "saig-sensitive-data", "saig-low-cost"],
            "example": "saig-default"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            }
          },
          "temperature": {"type": "number", "minimum": 0, "maximum": 2},
          "max_tokens": {"type": "integer"},
          "stream": {"type": "boolean", "default": false}
        }
      },
      "Message": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": {"type": "string", "enum": ["system", "user", "assistant"]},
          "content": {"type": "string"}
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "object": {"type": "string", "example": "chat.completion"},
          "created": {"type": "integer"},
          "model": {"type": "string"},
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {"type": "integer"},
                "message": {"$ref": "#/components/schemas/Message"},
                "finish_reason": {"type": "string"}
              }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "prompt_tokens": {"type": "integer"},
              "completion_tokens": {"type": "integer"},
              "total_tokens": {"type": "integer"}
            }
          }
        }
      },
      "ModelList": {
        "type": "object",
        "properties": {
          "object": {"type": "string", "example": "list"},
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {"type": "string", "example": "saig-default"},
                "object": {"type": "string", "example": "model"},
                "owned_by": {"type": "string", "example": "saig"}
              }
            }
          }
        }
      },
      "Capabilities": {
        "type": "object",
        "properties": {
          "platform_version": {"type": "string"},
          "api_version": {"type": "string", "example": "v1"},
          "features": {
            "type": "object",
            "description": "Feature availability flags"
          }
        }
      },
      "VersionInfo": {
        "type": "object",
        "properties": {
          "product": {"type": "string", "example": "SAIG by Terraxon"},
          "version": {"type": "string"},
          "api_version": {"type": "string", "example": "v1"},
          "build": {"type": "object"}
        }
      }
    }
  },
  "tags": [
    {"name": "Chat Completions", "description": "OpenAI-compatible governed chat completions"},
    {"name": "Models", "description": "Model alias listing"},
    {"name": "Discovery", "description": "Version, capabilities, and health"}
  ]
}