{
  "openapi": "3.1.0",
  "info": {
    "title": "Tartini API",
    "version": "1.0.0",
    "description": "API publica do Tartini para integracao de RAG e inteligencia artificial com sistemas externos."
  },
  "servers": [
    {
      "url": "https://api-talk.saninternet.com/v1",
      "description": "Producao"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/status": {
      "get": {
        "operationId": "getApiStatus",
        "summary": "Status da API",
        "description": "Retorna o status da API e informacoes sobre a API key utilizada. Use este endpoint para verificar se sua chave esta valida e a API esta operacional.",
        "tags": ["Status"],
        "responses": {
          "200": {
            "description": "API operacional",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time",
                      "example": "2026-01-12T10:30:00.000Z"
                    },
                    "apiKey": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid",
                          "example": "123e4567-e89b-12d3-a456-426614174000"
                        },
                        "name": {
                          "type": "string",
                          "example": "Production API Key"
                        },
                        "companyId": {
                          "type": "string",
                          "format": "uuid",
                          "example": "123e4567-e89b-12d3-a456-426614174000"
                        },
                        "maskedToken": {
                          "type": "string",
                          "example": "pyp_live_************abc123"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "API key ausente ou invalida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 401,
                  "error": "Unauthorized",
                  "message": "Invalid or expired API key"
                }
              }
            }
          },
          "403": {
            "description": "Assinatura inativa",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionError"
                }
              }
            }
          }
        }
      }
    },
    "/api/rag/retrieve": {
      "post": {
        "operationId": "ragRetrieve",
        "summary": "RAG Retrieve",
        "description": "Busca chunks relevantes no banco de dados vetorial usando RAG (Retrieval-Augmented Generation). Pode retornar uma resposta gerada por IA ou apenas os chunks brutos, dependendo do `returnMode`.",
        "tags": ["RAG"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RagRetrieveRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultados recuperados com sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RagRetrieveResponse"
                }
              }
            }
          },
          "401": {
            "description": "API key ausente ou invalida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Assinatura inativa",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key no formato `pyp_live_*`. Enviada como Bearer token no header Authorization."
      }
    },
    "schemas": {
      "RagRetrieveRequest": {
        "type": "object",
        "required": ["queryText", "filters", "scoreThreshold", "returnMode"],
        "properties": {
          "queryText": {
            "type": "string",
            "description": "O texto da consulta para busca semantica.",
            "example": "Qual a politica de devolucao?"
          },
          "filters": {
            "type": "object",
            "description": "Filtros para refinar a busca.",
            "required": ["sourceTypes", "audience"],
            "properties": {
              "sourceTypes": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Tipos de fonte para filtrar. Valores possiveis: `document`, `qa`, `website`.",
                "example": ["document", "qa"]
              },
              "audience": {
                "type": "string",
                "enum": ["ai_agent", "copilot", "strategist"],
                "description": "Audiencia alvo para o conteudo recuperado.",
                "example": "ai_agent"
              }
            }
          },
          "scoreThreshold": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Score minimo de similaridade para incluir um resultado. Valores mais altos retornam resultados mais relevantes.",
            "example": 0.7
          },
          "returnMode": {
            "type": "string",
            "enum": ["ai_generated_answer", "chunks_only"],
            "description": "`ai_generated_answer` retorna uma resposta gerada por IA alem dos chunks. `chunks_only` retorna apenas os chunks brutos.",
            "example": "ai_generated_answer"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Numero maximo de resultados. Padrao: 10.",
            "example": 10
          },
          "useRerank": {
            "type": "boolean",
            "description": "Ativar reranking dos resultados para melhorar a relevancia.",
            "example": true
          },
          "companyName": {
            "type": "string",
            "description": "Nome da empresa para contexto na geracao de resposta.",
            "example": "Acme Corporation"
          },
          "companyProductsNames": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Nomes dos produtos da empresa para contexto.",
            "example": ["Produto Premium", "Produto Basic"]
          },
          "clientName": {
            "type": "string",
            "description": "Nome do cliente para personalizacao da resposta.",
            "example": "Joao Silva"
          },
          "clientServices": {
            "type": "string",
            "description": "Servicos ativos do cliente para contexto.",
            "example": "Plano Premium, Suporte 24/7"
          },
          "clientCurrentChatHistory": {
            "type": "string",
            "description": "Historico de chat atual do cliente para contexto."
          },
          "clientOlderChatHistory": {
            "type": "string",
            "description": "Historico de chat anterior do cliente."
          },
          "clientPaymentHistory": {
            "type": "string",
            "description": "Historico de pagamentos do cliente."
          },
          "clientLogs": {
            "type": "string",
            "description": "Logs do cliente para contexto adicional."
          }
        }
      },
      "RagRetrieveResponse": {
        "type": "object",
        "properties": {
          "aiGeneratedAnswer": {
            "type": "string",
            "description": "Resposta gerada por IA. Presente apenas quando `returnMode` e `ai_generated_answer`.",
            "example": "Com base nos documentos, a politica de devolucao permite devolucoes em ate 30 dias..."
          },
          "results": {
            "type": "array",
            "description": "Chunks recuperados do banco vetorial.",
            "items": {
              "$ref": "#/components/schemas/RagResult"
            }
          },
          "total": {
            "type": "integer",
            "description": "Numero total de resultados encontrados.",
            "example": 5
          },
          "retrievalTimeMs": {
            "type": "integer",
            "description": "Tempo de busca em milissegundos.",
            "example": 150
          }
        }
      },
      "RagResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID do resultado.",
            "example": "result-uuid-123"
          },
          "score": {
            "type": "number",
            "description": "Score de similaridade (0-1).",
            "example": 0.85
          },
          "payload": {
            "$ref": "#/components/schemas/RagResultPayload"
          }
        }
      },
      "RagResultPayload": {
        "type": "object",
        "properties": {
          "companyId": {
            "type": "string",
            "format": "uuid",
            "description": "ID da empresa."
          },
          "audience": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Audiencias para as quais este conteudo e relevante.",
            "example": ["ai_agent", "copilot"]
          },
          "contentCategory": {
            "type": "string",
            "description": "Categoria do conteudo.",
            "example": "policy"
          },
          "content": {
            "type": "string",
            "description": "Conteudo textual do chunk.",
            "example": "Nossa politica de devolucao permite devolucoes em ate 30 dias..."
          },
          "sourceType": {
            "type": "string",
            "description": "Tipo de fonte do conteudo.",
            "example": "document"
          },
          "sourceId": {
            "type": "string",
            "description": "ID da fonte original.",
            "example": "doc-123"
          },
          "title": {
            "type": "string",
            "description": "Titulo da fonte.",
            "example": "Politica de Devolucao"
          },
          "path": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Caminho hierarquico do conteudo.",
            "example": ["politicas", "devolucoes"]
          },
          "metadata": {
            "type": "object",
            "description": "Metadados adicionais.",
            "additionalProperties": true
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer",
            "example": 401
          },
          "error": {
            "type": "string",
            "example": "Unauthorized"
          },
          "message": {
            "type": "string",
            "example": "Invalid or expired API key"
          }
        }
      },
      "SubscriptionError": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer",
            "example": 403
          },
          "error": {
            "type": "string",
            "example": "SubscriptionInactive"
          },
          "message": {
            "type": "string",
            "example": "Sua assinatura nao esta ativa"
          },
          "subscriptionStatus": {
            "type": "string",
            "nullable": true,
            "example": "CANCELLED"
          }
        }
      }
    }
  }
}