{
  "openapi": "3.1.0",
  "info": {
    "title": "kLog Ingest API",
    "version": "0.1.0",
    "description": "Contrato REST exclusivo para ingesta de eventos. Un evento por POST."
  },
  "paths": {
    "/v1/ingest/{tenantId}/events": {
      "post": {
        "operationId": "ingestEvent",
        "summary": "Ingiere un evento en el tenant",
        "security": [
          {
            "userJWT": []
          },
          {
            "userCookie": []
          },
          {
            "apiToken": []
          }
        ],
        "parameters": [
          {
            "name": "tenantId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
              "description": "UUIDv7 público; nunca corresponde al ID incremental interno."
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IngestEventInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Evento persistido",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Event"
                }
              }
            }
          },
          "202": {
            "description": "Evento descartado por un transform de tipo filter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestDropped"
                }
              }
            }
          },
          "400": {
            "description": "Entrada inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "401": {
            "description": "No autenticado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "402": {
            "description": "Cuota del plan superada (BILLING_MODE=cloud)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "403": {
            "description": "Sin permiso events.write o fuera del scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          },
          "429": {
            "description": "Cuota de ingesta superada",
            "headers": {
              "Retry-After": {
                "description": "Segundos hasta poder reintentar",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "description": "Epoch Unix del fin de la ventana"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "userJWT": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Access JWT de usuario; sub contiene su UUIDv7 y su sesión debe seguir activa."
      },
      "userCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "klog_access"
      },
      "apiToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "klog_api_token",
        "description": "Token opaco ligado a un proyecto y al rol device."
      }
    },
    "schemas": {
      "IngestEventInput": {
        "type": "object",
        "required": [
          "message"
        ],
        "additionalProperties": false,
        "properties": {
          "applicationId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
            "description": "Obligatorio con API token; la aplicación debe pertenecer a su proyecto."
          },
          "level": {
            "type": "string",
            "description": "Severidad. Vacío → info. Alias warning→warn, err/fatal/critical→error, trace→debug.",
            "enum": [
              "debug",
              "info",
              "warn",
              "error",
              "warning",
              "err",
              "fatal",
              "critical",
              "trace"
            ]
          },
          "traceId": {
            "type": "string",
            "maxLength": 128,
            "description": "Identificador de traza opcional."
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32768
          },
          "payload": {
            "description": "Objeto JSON. Si falta, el servidor usa {}.",
            "default": {}
          },
          "tags": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            }
          }
        }
      },
      "Event": {
        "type": "object",
        "required": [
          "id",
          "message",
          "payload",
          "tags",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
          },
          "applicationId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
          },
          "level": {
            "type": "string",
            "enum": [
              "debug",
              "info",
              "warn",
              "error"
            ]
          },
          "message": {
            "type": "string"
          },
          "payload": {},
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "IngestDropped": {
        "type": "object",
        "required": [
          "dropped",
          "id"
        ],
        "additionalProperties": false,
        "properties": {
          "dropped": {
            "type": "boolean",
            "const": true
          },
          "id": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "APIError": {
        "type": "object",
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}