{
  "openapi": "3.1.0",
  "info": {
    "title": "Quub Exchange - Observability API",
    "version": "2.0.0",
    "license": {
      "name": "Proprietary",
      "url": "https://quub.exchange/license"
    },
    "description": "Audit logs, system logs, metrics, and observability.\n\n**Audit Logs:**\n- WORM (Write-Once-Read-Many)\n- Hash-chained for tamper detection\n- Immutable after write\n"
  },
  "servers": [
    {
      "url": "https://api.quub.exchange/v1",
      "description": "Production API"
    }
  ],
  "paths": {
    "/orgs/{orgId}/audit-logs": {
      "get": {
        "summary": "Query audit logs",
        "operationId": "queryAuditLogs",
        "tags": [
          "Audit Logs"
        ],
        "description": "Retrieve immutable audit log entries for an organization. Logs are hash-chained for tamper detection.",
        "security": [
          {
            "oauth2": [
              "read:observability"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "name": "startTime",
            "in": "query",
            "description": "Filter logs created after this timestamp",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "endTime",
            "in": "query",
            "description": "Filter logs created before this timestamp",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "eventType",
            "in": "query",
            "description": "Filter by event type",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Max number of logs to return",
            "schema": {
              "type": "integer",
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Cursor for pagination",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "List of audit log entries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AuditLogEntry"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      }
    },
    "/admin/system-logs": {
      "get": {
        "summary": "Query system logs",
        "operationId": "querySystemLogs",
        "tags": [
          "System Logs"
        ],
        "description": "Retrieve system-level runtime logs filtered by severity.",
        "security": [
          {
            "oauth2": [
              "read:observability"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "level",
            "in": "query",
            "description": "Filter by log severity level",
            "schema": {
              "type": "string",
              "enum": [
                "DEBUG",
                "INFO",
                "WARN",
                "ERROR"
              ]
            }
          },
          {
            "name": "service",
            "in": "query",
            "description": "Filter logs by service name",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Max number of logs to return",
            "schema": {
              "type": "integer",
              "default": 100
            }
          }
        ],
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "List of system log entries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SystemLogEntry"
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      }
    },
    "/orgs/{orgId}/metrics": {
      "get": {
        "summary": "Get organization metrics",
        "operationId": "getMetrics",
        "tags": [
          "Metrics"
        ],
        "description": "Retrieve performance and usage metrics for the organization.",
        "security": [
          {
            "oauth2": [
              "read:observability"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "name": "range",
            "in": "query",
            "description": "Time range (e.g., 24h, 7d)",
            "schema": {
              "type": "string",
              "example": "24h"
            }
          }
        ],
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "429": {
            "$ref": "./common/responses.yaml#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "Organization metrics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MetricsResponse"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "$ref": "./common/components.yaml#/components/securitySchemes/bearerAuth"
      },
      "oauth2": {
        "$ref": "./common/components.yaml#/components/securitySchemes/oauth2"
      },
      "apiKey": {
        "$ref": "./common/components.yaml#/components/securitySchemes/apiKey"
      }
    },
    "schemas": {
      "AuditLogEntry": {
        "type": "object",
        "description": "Immutable, hash-chained audit record.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "orgId": {
            "type": "string",
            "format": "uuid"
          },
          "accountId": {
            "type": "string",
            "format": "uuid"
          },
          "eventType": {
            "type": "string",
            "example": "USER_LOGIN"
          },
          "action": {
            "type": "string",
            "example": "LOGIN_SUCCESS"
          },
          "resourceType": {
            "type": "string",
            "example": "ACCOUNT"
          },
          "resourceId": {
            "type": "string"
          },
          "changes": {
            "type": "object",
            "description": "JSON object describing state changes"
          },
          "ipAddress": {
            "type": "string"
          },
          "userAgent": {
            "type": "string"
          },
          "hashChain": {
            "type": "string",
            "description": "Hash of previous entry + current entry (WORM)"
          }
        },
        "required": [
          "id",
          "timestamp",
          "orgId",
          "eventType",
          "hashChain"
        ]
      },
      "SystemLogEntry": {
        "type": "object",
        "description": "Application or system-level log entry.",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "level": {
            "type": "string",
            "enum": [
              "DEBUG",
              "INFO",
              "WARN",
              "ERROR"
            ]
          },
          "service": {
            "type": "string",
            "example": "exchange-core"
          },
          "message": {
            "type": "string"
          },
          "traceId": {
            "type": "string",
            "example": "req_abc123"
          },
          "metadata": {
            "type": "object",
            "description": "Additional contextual data"
          }
        }
      },
      "MetricsResponse": {
        "type": "object",
        "description": "Aggregated telemetry metrics.",
        "properties": {
          "collectedAt": {
            "type": "string",
            "format": "date-time"
          },
          "metrics": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "example": "request_rate"
                },
                "value": {
                  "type": "number"
                },
                "unit": {
                  "type": "string",
                  "example": "requests/sec"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Audit Logs",
      "description": "Audit Logs operations"
    },
    {
      "name": "Metrics",
      "description": "Metrics operations"
    },
    {
      "name": "System Logs",
      "description": "System Logs operations"
    }
  ]
}